0
# Metrics Integration
1

2
HikariCP provides built-in support for popular metrics libraries including Dropwizard Metrics (Codahale), Micrometer, and Prometheus. This enables detailed monitoring of connection pool performance and behavior.
3

4
## Capabilities
5

6
### Dropwizard/Codahale Metrics Integration
7

8
Integrates with Dropwizard Metrics (formerly Codahale Metrics) to provide detailed connection pool telemetry.
9

10
```java { .api }
11
/**
12
 * Metrics tracker factory for Dropwizard/Codahale Metrics integration
13
 */
14
public class CodahaleMetricsTrackerFactory implements MetricsTrackerFactory {
15
    /**
16
     * Create factory with existing MetricRegistry
17
     * @param registry The MetricRegistry to use for metrics collection
18
     */
19
    public CodahaleMetricsTrackerFactory(MetricRegistry registry);
20
    
21
    /**
22
     * Create metrics tracker for named pool
23
     * @param poolName Name of the connection pool
24
     * @param poolStats Pool statistics provider
25
     * @return Configured metrics tracker
26
     */
27
    public IMetricsTracker create(String poolName, PoolStats poolStats);
28
}
29
```
30

31
**Usage Example:**
32

33
```java
34
import com.codahale.metrics.MetricRegistry;
35
import com.zaxxer.hikari.metrics.dropwizard.CodahaleMetricsTrackerFactory;
36

37
// Create metrics registry
38
MetricRegistry metricRegistry = new MetricRegistry();
39

40
// Configure HikariCP with metrics
41
HikariConfig config = new HikariConfig();
42
config.setJdbcUrl("jdbc:mysql://localhost:3306/mydb");
43
config.setUsername("user");
44
config.setPassword("password");
45
config.setMetricsTrackerFactory(new CodahaleMetricsTrackerFactory(metricRegistry));
46

47
HikariDataSource dataSource = new HikariDataSource(config);
48
```
49

50
### Micrometer Metrics Integration
51

52
Integrates with Micrometer for metrics collection with support for various monitoring systems.
53

54
```java { .api }
55
/**
56
 * Metrics tracker factory for Micrometer integration
57
 */
58
public class MicrometerMetricsTrackerFactory implements MetricsTrackerFactory {
59
    /**
60
     * Create factory with existing MeterRegistry
61
     * @param registry The MeterRegistry to use for metrics collection
62
     */
63
    public MicrometerMetricsTrackerFactory(MeterRegistry registry);
64
    
65
    /**
66
     * Create metrics tracker for named pool
67
     * @param poolName Name of the connection pool
68
     * @param poolStats Pool statistics provider
69
     * @return Configured metrics tracker
70
     */
71
    public IMetricsTracker create(String poolName, PoolStats poolStats);
72
}
73
```
74

75
**Usage Example:**
76

77
```java
78
import io.micrometer.core.instrument.MeterRegistry;
79
import com.zaxxer.hikari.metrics.micrometer.MicrometerMetricsTrackerFactory;
80

81
// Configure HikariCP with Micrometer metrics
82
HikariConfig config = new HikariConfig();
83
config.setJdbcUrl("jdbc:mysql://localhost:3306/mydb");
84
config.setUsername("user");
85
config.setPassword("password");
86
config.setMetricsTrackerFactory(new MicrometerMetricsTrackerFactory(meterRegistry));
87

88
HikariDataSource dataSource = new HikariDataSource(config);
89
```
90

91
### Prometheus Metrics Integration
92

93
Direct integration with Prometheus for metrics collection without requiring additional libraries.
94

95
```java { .api }
96
/**
97
 * Metrics tracker factory for Prometheus integration
98
 */
99
public class PrometheusMetricsTrackerFactory implements MetricsTrackerFactory {
100
    /**
101
     * Create factory with default CollectorRegistry
102
     */
103
    public PrometheusMetricsTrackerFactory();
104
    
105
    /**
106
     * Create factory with custom CollectorRegistry
107
     * @param collectorRegistry The CollectorRegistry to use for metrics collection
108
     */
109
    public PrometheusMetricsTrackerFactory(CollectorRegistry collectorRegistry);
110
    
111
    /**
112
     * Create metrics tracker for named pool
113
     * @param poolName Name of the connection pool
114
     * @param poolStats Pool statistics provider
115
     * @return Configured metrics tracker
116
     */
117
    public IMetricsTracker create(String poolName, PoolStats poolStats);
118
}
119
```
120

121
**Usage Example:**
122

123
```java
124
import io.prometheus.client.CollectorRegistry;
125
import com.zaxxer.hikari.metrics.prometheus.PrometheusMetricsTrackerFactory;
126

127
// Configure HikariCP with Prometheus metrics
128
HikariConfig config = new HikariConfig();
129
config.setJdbcUrl("jdbc:mysql://localhost:3306/mydb");
130
config.setUsername("user");
131
config.setPassword("password");
132
config.setMetricsTrackerFactory(new PrometheusMetricsTrackerFactory());
133

134
HikariDataSource dataSource = new HikariDataSource(config);
135
```
136

137
### Prometheus Histogram Metrics Integration
138

139
Alternative Prometheus integration using histograms instead of summaries for better performance characteristics.
140

141
```java { .api }
142
/**
143
 * Metrics tracker factory for Prometheus histogram-based metrics (recommended for performance)
144
 */
145
public class PrometheusHistogramMetricsTrackerFactory implements MetricsTrackerFactory {
146
    /**
147
     * Create factory with default CollectorRegistry
148
     */
149
    public PrometheusHistogramMetricsTrackerFactory();
150
    
151
    /**
152
     * Create factory with custom CollectorRegistry
153
     * @param collectorRegistry The CollectorRegistry to use for metrics collection
154
     */
155
    public PrometheusHistogramMetricsTrackerFactory(CollectorRegistry collectorRegistry);
156
    
157
    /**
158
     * Create metrics tracker for named pool
159
     * @param poolName Name of the connection pool
160
     * @param poolStats Pool statistics provider
161
     * @return Configured metrics tracker
162
     */
163
    public IMetricsTracker create(String poolName, PoolStats poolStats);
164
}
165
```
166

167
### HikariCP Prometheus Collector
168

169
Direct Prometheus collector for HikariCP pool metrics, enabling custom metrics collection scenarios.
170

171
```java { .api }
172
/**
173
 * Prometheus collector for HikariCP pool metrics
174
 */
175
public class HikariCPCollector extends Collector {
176
    /**
177
     * Collect metrics samples for Prometheus
178
     * @return List of metric samples
179
     */
180
    public List<MetricFamilySamples> collect();
181
    
182
    /**
183
     * Add pool for metrics collection
184
     * @param poolName Name of the pool to monitor
185
     * @param poolStats Pool statistics provider
186
     */
187
    public void add(String poolName, PoolStats poolStats);
188
    
189
    /**
190
     * Remove pool from metrics collection
191
     * @param poolName Name of the pool to stop monitoring
192
     */
193
    public void remove(String poolName);
194
}
195
```
196

197
### Core Metrics Interface
198

199
The foundational interface for all metrics tracking implementations.
200

201
```java { .api }
202
/**
203
 * Core interface for metrics tracking implementations
204
 */
205
public interface IMetricsTracker extends AutoCloseable {
206
    /**
207
     * Record the time it took to create a connection
208
     * @param connectionCreatedMillis Time in milliseconds to create connection
209
     */
210
    default void recordConnectionCreatedMillis(long connectionCreatedMillis);
211
    
212
    /**
213
     * Record the time it took to acquire a connection from the pool
214
     * @param elapsedAcquiredNanos Time in nanoseconds to acquire connection
215
     */
216
    default void recordConnectionAcquiredNanos(final long elapsedAcquiredNanos);
217
    
218
    /**
219
     * Record how long a connection was used (borrowed from pool)
220
     * @param elapsedBorrowedMillis Time in milliseconds connection was in use
221
     */
222
    default void recordConnectionUsageMillis(final long elapsedBorrowedMillis);
223
    
224
    /**
225
     * Record a connection timeout event
226
     */
227
    default void recordConnectionTimeout();
228
    
229
    /**
230
     * Close the metrics tracker and release resources
231
     */
232
    default void close();
233
}
234

235
/**
236
 * Factory interface for creating metrics tracker instances
237
 */
238
public interface MetricsTrackerFactory {
239
    /**
240
     * Create a metrics tracker for a named pool
241
     * @param poolName Name of the connection pool
242
     * @param poolStats Pool statistics provider
243
     * @return Configured metrics tracker instance
244
     */
245
    IMetricsTracker create(String poolName, PoolStats poolStats);
246
}
247
```
248

249
### Pool Statistics Provider
250

251
Abstract class providing access to pool statistics for metrics collection.
252

253
```java { .api }
254
/**
255
 * Abstract class providing pool statistics for metrics tracking
256
 */
257
public abstract class PoolStats {
258
    /**
259
     * Create pool stats with timeout configuration
260
     * @param timeoutMs Connection timeout in milliseconds
261
     */
262
    public PoolStats(final long timeoutMs);
263
    
264
    /**
265
     * Get total number of connections in the pool
266
     * @return Total connection count
267
     */
268
    public int getTotalConnections();
269
    
270
    /**
271
     * Get number of idle connections in the pool
272
     * @return Idle connection count
273
     */
274
    public int getIdleConnections();
275
    
276
    /**
277
     * Get number of active (in-use) connections
278
     * @return Active connection count
279
     */
280
    public int getActiveConnections();
281
    
282
    /**
283
     * Get number of threads waiting for connections
284
     * @return Pending thread count
285
     */
286
    public int getPendingThreads();
287
    
288
    /**
289
     * Get maximum number of connections allowed in pool
290
     * @return Maximum connection count
291
     */
292
    public int getMaxConnections();
293
    
294
    /**
295
     * Get minimum number of idle connections maintained
296
     * @return Minimum connection count
297
     */
298
    public int getMinConnections();
299
}
300
```
301

302
## Collected Metrics
303

304
HikariCP metrics integrations typically collect the following metrics:
305

306
- **Connection Creation Time**: Time taken to create new database connections
307
- **Connection Acquisition Time**: Time spent waiting to acquire a connection from the pool
308
- **Connection Usage Time**: How long connections are held before being returned to the pool
309
- **Connection Timeout Events**: Number of times connection acquisition timed out
310
- **Pool Statistics**: Current active, idle, and total connection counts
311
- **Pending Threads**: Number of threads waiting for available connections
312

313
## Configuration
314

315
Metrics can be configured at the pool level during HikariConfig setup:
316

317
```java
318
HikariConfig config = new HikariConfig();
319
// ... other configuration ...
320
config.setMetricsTrackerFactory(metricsTrackerFactory);
321
config.setPoolName("MyConnectionPool"); // Important for metrics identification
322
```
323

324
The pool name is crucial for metrics as it's used to identify the pool in metrics systems, especially when running multiple pools in the same application.