0
# JMX Management
1

2
Runtime monitoring and configuration through JMX MBeans, providing comprehensive visibility into pool statistics, connection health, and the ability to modify configuration parameters during runtime without application restarts.
3

4
## Capabilities
5

6
### HikariConfigMXBean
7

8
JMX MBean interface for runtime configuration management, allowing dynamic modification of key pool parameters during application execution.
9

10
```java { .api }
11
public interface HikariConfigMXBean {
12
    /**
13
     * Get connection acquisition timeout in milliseconds.
14
     * 
15
     * @return timeout in milliseconds
16
     */
17
    long getConnectionTimeout();
18
    
19
    /**
20
     * Set connection acquisition timeout in milliseconds.
21
     * 
22
     * @param connectionTimeoutMs timeout in milliseconds
23
     */
24
    void setConnectionTimeout(long connectionTimeoutMs);
25
    
26
    /**
27
     * Get connection validation timeout in milliseconds.
28
     * 
29
     * @return timeout in milliseconds
30
     */
31
    long getValidationTimeout();
32
    
33
    /**
34
     * Set connection validation timeout in milliseconds.
35
     * 
36
     * @param validationTimeoutMs timeout in milliseconds
37
     */
38
    void setValidationTimeout(long validationTimeoutMs);
39
    
40
    /**
41
     * Get idle connection timeout in milliseconds.
42
     * 
43
     * @return timeout in milliseconds
44
     */
45
    long getIdleTimeout();
46
    
47
    /**
48
     * Set idle connection timeout in milliseconds.
49
     * 
50
     * @param idleTimeoutMs timeout in milliseconds
51
     */
52
    void setIdleTimeout(long idleTimeoutMs);
53
    
54
    /**
55
     * Get connection leak detection threshold in milliseconds.
56
     * 
57
     * @return threshold in milliseconds, 0 = disabled
58
     */
59
    long getLeakDetectionThreshold();
60
    
61
    /**
62
     * Set connection leak detection threshold in milliseconds.
63
     * 
64
     * @param leakDetectionThresholdMs threshold in milliseconds, 0 to disable
65
     */
66
    void setLeakDetectionThreshold(long leakDetectionThresholdMs);
67
    
68
    /**
69
     * Get maximum connection lifetime in milliseconds.
70
     * 
71
     * @return lifetime in milliseconds
72
     */
73
    long getMaxLifetime();
74
    
75
    /**
76
     * Set maximum connection lifetime in milliseconds.
77
     * 
78
     * @param maxLifetimeMs lifetime in milliseconds
79
     */
80
    void setMaxLifetime(long maxLifetimeMs);
81
    
82
    /**
83
     * Get minimum number of idle connections.
84
     * 
85
     * @return minimum idle connections
86
     */
87
    int getMinimumIdle();
88
    
89
    /**
90
     * Set minimum number of idle connections.
91
     * 
92
     * @param minIdle minimum idle connections
93
     */
94
    void setMinimumIdle(int minIdle);
95
    
96
    /**
97
     * Get maximum pool size.
98
     * 
99
     * @return maximum pool size
100
     */
101
    int getMaximumPoolSize();
102
    
103
    /**
104
     * Set maximum pool size.
105
     * 
106
     * @param maxPoolSize maximum pool size
107
     */
108
    void setMaximumPoolSize(int maxPoolSize);
109
    
110
    /**
111
     * Get pool name (read-only).
112
     * 
113
     * @return pool name
114
     */
115
    String getPoolName();
116
}
117
```
118

119
### HikariPoolMXBean
120

121
JMX MBean interface for pool monitoring and management, providing real-time statistics and operational control over the connection pool.
122

123
```java { .api }
124
public interface HikariPoolMXBean {
125
    /**
126
     * Get number of idle connections in the pool.
127
     * 
128
     * @return count of idle connections
129
     */
130
    int getIdleConnections();
131
    
132
    /**
133
     * Get number of active (in-use) connections.
134
     * 
135
     * @return count of active connections
136
     */
137
    int getActiveConnections();
138
    
139
    /**
140
     * Get total number of connections in the pool.
141
     * 
142
     * @return total connection count (active + idle)
143
     */
144
    int getTotalConnections();
145
    
146
    /**
147
     * Get number of threads waiting for connections.
148
     * 
149
     * @return count of threads awaiting connections
150
     */
151
    int getThreadsAwaitingConnection();
152
    
153
    /**
154
     * Soft evict idle connections from the pool.
155
     * Removes idle connections that have exceeded their idle timeout.
156
     */
157
    void softEvictConnections();
158
    
159
    /**
160
     * Suspend the connection pool.
161
     * Prevents new connections from being allocated while allowing
162
     * existing connections to continue operating.
163
     */
164
    void suspendPool();
165
    
166
    /**
167
     * Resume the connection pool after suspension.
168
     * Re-enables connection allocation.
169
     */
170
    void resumePool();
171
}
172
```
173

174
## Usage Examples
175

176
### Enabling JMX Management
177

178
```java
179
import com.zaxxer.hikari.HikariConfig;
180
import com.zaxxer.hikari.HikariDataSource;
181

182
// Enable MBean registration in configuration
183
HikariConfig config = new HikariConfig();
184
config.setJdbcUrl("jdbc:postgresql://localhost/mydb");
185
config.setUsername("user");
186
config.setPassword("password");
187
config.setPoolName("MyAppPool");  // Important: set pool name for JMX identification
188
config.setRegisterMbeans(true);   // Enable JMX MBean registration
189

190
HikariDataSource dataSource = new HikariDataSource(config);
191
```
192

193
### Accessing MBeans Programmatically
194

195
```java
196
import javax.management.MBeanServer;
197
import javax.management.MBeanServerInvocationHandler;
198
import javax.management.ObjectName;
199
import java.lang.management.ManagementFactory;
200
import com.zaxxer.hikari.HikariConfigMXBean;
201
import com.zaxxer.hikari.pool.HikariPoolMXBean;
202

203
// Get the platform MBean server
204
MBeanServer server = ManagementFactory.getPlatformMBeanServer();
205

206
// Access configuration MBean
207
ObjectName configObjectName = new ObjectName("com.zaxxer.hikari:type=Pool (MyAppPool)");
208
HikariConfigMXBean configMBean = MBeanServerInvocationHandler.newProxyInstance(
209
    server, configObjectName, HikariConfigMXBean.class, false);
210

211
// Access pool monitoring MBean  
212
ObjectName poolObjectName = new ObjectName("com.zaxxer.hikari:type=PoolStats (MyAppPool)");
213
HikariPoolMXBean poolMBean = MBeanServerInvocationHandler.newProxyInstance(
214
    server, poolObjectName, HikariPoolMXBean.class, false);
215

216
// Read current configuration
217
long connectionTimeout = configMBean.getConnectionTimeout();
218
int maxPoolSize = configMBean.getMaximumPoolSize();
219

220
// Monitor pool statistics
221
int activeConnections = poolMBean.getActiveConnections();
222
int idleConnections = poolMBean.getIdleConnections();
223
int totalConnections = poolMBean.getTotalConnections();
224
int waitingThreads = poolMBean.getThreadsAwaitingConnection();
225

226
System.out.println("Pool Stats:");
227
System.out.println("  Active: " + activeConnections);
228
System.out.println("  Idle: " + idleConnections);
229
System.out.println("  Total: " + totalConnections);
230
System.out.println("  Waiting Threads: " + waitingThreads);
231
```
232

233
### Runtime Configuration Changes
234

235
```java
236
// Dynamically adjust pool configuration
237
configMBean.setMaximumPoolSize(25);        // Increase max pool size
238
configMBean.setConnectionTimeout(45000);   // Increase connection timeout to 45 seconds
239
configMBean.setIdleTimeout(900000);        // Increase idle timeout to 15 minutes
240

241
// Enable leak detection if not already enabled
242
configMBean.setLeakDetectionThreshold(120000); // 2 minutes
243
```
244

245
### Pool Management Operations
246

247
```java
248
// Suspend pool during maintenance
249
poolMBean.suspendPool();
250
System.out.println("Pool suspended - no new connections will be allocated");
251

252
// Perform maintenance tasks...
253

254
// Resume pool operations
255
poolMBean.resumePool();
256
System.out.println("Pool resumed - normal operations restored");
257

258
// Force eviction of idle connections
259
poolMBean.softEvictConnections();
260
System.out.println("Idle connections evicted");
261
```
262

263
### Monitoring and Alerting
264

265
```java
266
import java.util.concurrent.Executors;
267
import java.util.concurrent.ScheduledExecutorService;
268
import java.util.concurrent.TimeUnit;
269

270
// Create monitoring service
271
ScheduledExecutorService monitoring = Executors.newScheduledThreadPool(1);
272

273
// Monitor pool health every 30 seconds
274
monitoring.scheduleAtFixedRate(() -> {
275
    try {
276
        int active = poolMBean.getActiveConnections();
277
        int total = poolMBean.getTotalConnections();
278
        int waiting = poolMBean.getThreadsAwaitingConnection();
279
        
280
        // Calculate pool utilization
281
        double utilization = total > 0 ? (double) active / total : 0.0;
282
        
283
        // Alert on high utilization
284
        if (utilization > 0.8) {
285
            System.err.println("WARNING: High pool utilization: " + 
286
                String.format("%.1f%% (%d/%d)", utilization * 100, active, total));
287
        }
288
        
289
        // Alert on waiting threads
290
        if (waiting > 0) {
291
            System.err.println("WARNING: " + waiting + " threads waiting for connections");
292
        }
293
        
294
        // Log current status
295
        System.out.println("Pool Status - Active: " + active + 
296
                          ", Total: " + total + 
297
                          ", Utilization: " + String.format("%.1f%%", utilization * 100));
298
                          
299
    } catch (Exception e) {
300
        System.err.println("Error monitoring pool: " + e.getMessage());
301
    }
302
}, 0, 30, TimeUnit.SECONDS);
303
```
304

305
### JConsole Integration
306

307
When JMX MBeans are enabled, HikariCP pools appear in JConsole under the `com.zaxxer.hikari` domain:
308

309
- **Configuration MBean**: `com.zaxxer.hikari:type=Pool (PoolName)`
310
  - Allows runtime modification of timeout settings and pool sizing
311
  - Shows current configuration values
312
  
313
- **Pool Statistics MBean**: `com.zaxxer.hikari:type=PoolStats (PoolName)`
314
  - Real-time connection statistics
315
  - Pool management operations (suspend/resume, soft eviction)
316

317
### Spring Boot Integration
318

319
```java
320
// In Spring Boot, enable JMX management in application.properties:
321
// management.endpoints.jmx.exposure.include=*
322
// spring.jmx.enabled=true
323

324
@Component
325
public class HikariMonitor {
326
    
327
    @Autowired
328
    private HikariDataSource dataSource;
329
    
330
    @Autowired
331
    private MBeanServer mBeanServer;
332
    
333
    @EventListener
334
    public void onApplicationReady(ApplicationReadyEvent event) {
335
        // Access HikariCP MBeans after application startup
336
        String poolName = dataSource.getPoolName();
337
        ObjectName configMBean = new ObjectName(
338
            "com.zaxxer.hikari:type=Pool (" + poolName + ")");
339
        ObjectName poolMBean = new ObjectName(
340
            "com.zaxxer.hikari:type=PoolStats (" + poolName + ")");
341
        
342
        // Register custom monitoring logic
343
        startPoolMonitoring(configMBean, poolMBean);
344
    }
345
}
346
```