0
# Memory Monitoring
1

2
Comprehensive memory usage tracking for the Java Virtual Machine including heap, non-heap, and individual memory pool statistics with usage ratios and garbage collection metrics.
3

4
## Core Imports
5

6
```java
7
import com.codahale.metrics.jvm.MemoryUsageGaugeSet;
8
import com.codahale.metrics.MetricRegistry;
9
import java.lang.management.MemoryMXBean;
10
import java.lang.management.MemoryPoolMXBean;
11
```
12

13
## Capabilities
14

15
### MemoryUsageGaugeSet
16

17
Provides detailed memory usage metrics for all areas of JVM memory including total, heap, non-heap, and individual memory pools.
18

19
```java { .api }
20
/**
21
 * A set of gauges for JVM memory usage, including stats on heap vs. non-heap memory, plus GC-specific memory pools.
22
 */
23
public class MemoryUsageGaugeSet implements MetricSet {
24
    /**
25
     * Creates a new set of gauges using the default MemoryMXBean and MemoryPoolMXBeans.
26
     */
27
    public MemoryUsageGaugeSet();
28
    
29
    /**
30
     * Creates a new set of gauges with custom MXBeans.
31
     * @param mxBean the MemoryMXBean to use for memory statistics
32
     * @param memoryPools collection of MemoryPoolMXBeans for pool-specific metrics
33
     */
34
    public MemoryUsageGaugeSet(MemoryMXBean mxBean, Collection<MemoryPoolMXBean> memoryPools);
35
    
36
    /**
37
     * Returns all memory-related metrics.
38
     * @return map of metric names to Metric instances
39
     */
40
    public Map<String, Metric> getMetrics();
41
}
42
```
43

44
**Metrics Provided:**
45

46
- **Total Memory**: `total.init`, `total.used`, `total.max`, `total.committed`
47
- **Heap Memory**: `heap.init`, `heap.used`, `heap.max`, `heap.committed`, `heap.usage` (ratio)
48
- **Non-Heap Memory**: `non-heap.init`, `non-heap.used`, `non-heap.max`, `non-heap.committed`, `non-heap.usage` (ratio)
49
- **Memory Pool Metrics**: For each memory pool (e.g., Eden Space, Old Generation):
50
  - `pools.{pool-name}.init`, `pools.{pool-name}.used`, `pools.{pool-name}.max`
51
  - `pools.{pool-name}.committed`, `pools.{pool-name}.usage` (ratio)
52
  - `pools.{pool-name}.used-after-gc` (if collection usage is supported)
53

54
**Usage Examples:**
55

56
```java
57
import com.codahale.metrics.MetricRegistry;
58
import com.codahale.metrics.jvm.MemoryUsageGaugeSet;
59

60
// Basic usage with default MXBeans
61
MetricRegistry registry = new MetricRegistry();
62
registry.registerAll(new MemoryUsageGaugeSet());
63

64
// Access specific metrics
65
Gauge<Double> heapUsage = registry.getGauges().get("heap.usage");
66
Gauge<Long> heapUsed = registry.getGauges().get("heap.used");
67
Gauge<Long> heapMax = registry.getGauges().get("heap.max");
68

69
System.out.println("Heap usage ratio: " + heapUsage.getValue());
70
System.out.println("Heap used: " + heapUsed.getValue() + " bytes");
71
System.out.println("Heap max: " + heapMax.getValue() + " bytes");
72

73
// Custom MXBeans usage
74
MemoryMXBean customMemoryBean = ManagementFactory.getMemoryMXBean();
75
Collection<MemoryPoolMXBean> customPools = ManagementFactory.getMemoryPoolMXBeans();
76
registry.registerAll(new MemoryUsageGaugeSet(customMemoryBean, customPools));
77
```
78

79
**Memory Pool Examples:**
80

81
Common memory pool names include:
82
- `pools.PS-Eden-Space.*` - Young generation Eden space
83
- `pools.PS-Old-Gen.*` - Old generation space  
84
- `pools.PS-Survivor-Space.*` - Young generation survivor space
85
- `pools.Metaspace.*` - Class metadata space
86
- `pools.Code-Cache.*` - Compiled code cache
87

88
**Memory Usage Ratios:**
89

90
Usage ratios are calculated as used/max, or used/committed when max is -1 (unlimited). Values range from 0.0 to 1.0, where 1.0 indicates full utilization.