0
# Buffer Pool Monitoring
1

2
Buffer pool usage statistics for direct and mapped buffers, providing insight into off-heap memory usage. Available on Java 7 and above.
3

4
## Core Imports
5

6
```java
7
import com.codahale.metrics.jvm.BufferPoolMetricSet;
8
import com.codahale.metrics.MetricRegistry;
9
import javax.management.MBeanServer;
10
import java.lang.management.ManagementFactory;
11
```
12

13
## Capabilities
14

15
### BufferPoolMetricSet
16

17
Monitors JVM buffer pools including direct and mapped buffer usage statistics.
18

19
```java { .api }
20
/**
21
 * A set of gauges for the count, usage, and capacity of the JVM's direct and mapped buffer pools.
22
 * These JMX objects are only available on Java 7 and above.
23
 */
24
public class BufferPoolMetricSet implements MetricSet {
25
    /**
26
     * Creates a new set of buffer pool gauges.
27
     * @param mBeanServer the MBeanServer to query for buffer pool statistics
28
     */
29
    public BufferPoolMetricSet(MBeanServer mBeanServer);
30
    
31
    /**
32
     * Returns all buffer pool metrics.
33
     * @return map of metric names to Metric instances
34
     */
35
    public Map<String, Metric> getMetrics();
36
}
37
```
38

39
**Metrics Provided:**
40

41
For each buffer pool type (direct and mapped):
42
- `{pool-type}.count` - Number of buffers in the pool
43
- `{pool-type}.used` - Memory used by buffers in bytes
44
- `{pool-type}.capacity` - Total capacity of buffers in bytes
45

46
Specific metrics:
47
- `direct.count`, `direct.used`, `direct.capacity` - Direct buffer statistics
48
- `mapped.count`, `mapped.used`, `mapped.capacity` - Mapped buffer statistics
49

50
**Usage Examples:**
51

52
```java
53
import com.codahale.metrics.MetricRegistry;
54
import com.codahale.metrics.jvm.BufferPoolMetricSet;
55
import java.lang.management.ManagementFactory;
56

57
// Basic usage with platform MBean server
58
MetricRegistry registry = new MetricRegistry();
59
MBeanServer server = ManagementFactory.getPlatformMBeanServer();
60
registry.registerAll(new BufferPoolMetricSet(server));
61

62
// Access buffer pool metrics
63
Gauge<Long> directCount = registry.getGauges().get("direct.count");
64
Gauge<Long> directUsed = registry.getGauges().get("direct.used");
65
Gauge<Long> directCapacity = registry.getGauges().get("direct.capacity");
66

67
Gauge<Long> mappedCount = registry.getGauges().get("mapped.count");
68
Gauge<Long> mappedUsed = registry.getGauges().get("mapped.used");
69
Gauge<Long> mappedCapacity = registry.getGauges().get("mapped.capacity");
70

71
// Display direct buffer statistics
72
if (directCount != null) {
73
    System.out.println("Direct buffers: " + directCount.getValue());
74
    System.out.println("Direct buffer memory used: " + directUsed.getValue() + " bytes");
75
    System.out.println("Direct buffer capacity: " + directCapacity.getValue() + " bytes");
76
    
77
    // Calculate utilization ratio
78
    double directUtilization = directCapacity.getValue() > 0 ? 
79
        (double) directUsed.getValue() / directCapacity.getValue() : 0.0;
80
    System.out.println("Direct buffer utilization: " + (directUtilization * 100) + "%");
81
}
82

83
// Display mapped buffer statistics
84
if (mappedCount != null) {
85
    System.out.println("Mapped buffers: " + mappedCount.getValue());
86
    System.out.println("Mapped buffer memory used: " + mappedUsed.getValue() + " bytes");
87
    System.out.println("Mapped buffer capacity: " + mappedCapacity.getValue() + " bytes");
88
}
89

90
// Custom MBean server
91
MBeanServer customServer = MBeanServerFactory.createMBeanServer();
92
registry.registerAll(new BufferPoolMetricSet(customServer));
93
```
94

95
**Buffer Pool Types:**
96

97
- **Direct Buffers**: Off-heap memory allocated using `ByteBuffer.allocateDirect()` or similar methods
98
  - Used for NIO operations, networking, and memory-mapped files
99
  - Not subject to GC but limited by available system memory
100
  - Freed when the buffer object is garbage collected
101

102
- **Mapped Buffers**: Memory-mapped file buffers created using `FileChannel.map()`
103
  - Backed by files on disk but cached in memory
104
  - Provide efficient file I/O through virtual memory mapping
105
  - Memory usage depends on file size and OS caching behavior
106

107
**Monitoring Considerations:**
108

109
- **High direct buffer usage** may indicate memory leaks or excessive off-heap allocation
110
- **Growing buffer counts** without corresponding decreases may suggest reference leaks
111
- **Capacity vs. used ratios** help identify buffer pool efficiency
112
- **Missing metrics** on older Java versions (< 7) will result in empty metric maps
113

114
**Platform Compatibility:**
115

116
- Requires Java 7 or higher for JMX buffer pool support
117
- On Java 6 or when buffer pool MBeans are unavailable, metrics will be empty
118
- Different JVM implementations may expose different buffer pool types