0
# JMX Attribute Access
1

2
Generic JMX attribute monitoring for custom MBean attributes, providing flexible access to any JMX-exposed metric in the JVM or application.
3

4
## Core Imports
5

6
```java
7
import com.codahale.metrics.jvm.JmxAttributeGauge;
8
import com.codahale.metrics.MetricRegistry;
9
import javax.management.ObjectName;
10
import javax.management.MBeanServerConnection;
11
```
12

13
## Capabilities
14

15
### JmxAttributeGauge
16

17
Provides direct access to JMX MBean attributes with flexible connection and naming support.
18

19
```java { .api }
20
/**
21
 * A Gauge implementation which queries an MBeanServerConnection for an attribute of an object.
22
 */
23
public class JmxAttributeGauge implements Gauge<Object> {
24
    /**
25
     * Creates a new JmxAttributeGauge using the platform MBean server.
26
     * @param objectName the name of the object
27
     * @param attributeName the name of the object's attribute
28
     */
29
    public JmxAttributeGauge(ObjectName objectName, String attributeName);
30
    
31
    /**
32
     * Creates a new JmxAttributeGauge with a custom MBeanServerConnection.
33
     * @param mBeanServerConn the MBeanServerConnection
34
     * @param objectName the name of the object
35
     * @param attributeName the name of the object's attribute
36
     */
37
    public JmxAttributeGauge(MBeanServerConnection mBeanServerConn, ObjectName objectName, String attributeName);
38
    
39
    /**
40
     * Gets the current value of the JMX attribute.
41
     * @return the attribute value, or null if unavailable
42
     */
43
    public Object getValue();
44
}
45
```
46

47
**Usage Examples:**
48

49
```java
50
import com.codahale.metrics.MetricRegistry;
51
import com.codahale.metrics.jvm.JmxAttributeGauge;
52
import javax.management.ObjectName;
53
import java.lang.management.ManagementFactory;
54

55
// Basic usage with platform MBean server
56
MetricRegistry registry = new MetricRegistry();
57

58
// Monitor JVM memory usage
59
ObjectName memoryName = new ObjectName("java.lang:type=Memory");
60
JmxAttributeGauge heapUsed = new JmxAttributeGauge(memoryName, "HeapMemoryUsage");
61
registry.register("jvm.memory.heap.composite", heapUsed);
62

63
// Monitor specific memory pool
64
ObjectName poolName = new ObjectName("java.lang:type=MemoryPool,name=PS Eden Space");
65
JmxAttributeGauge poolUsage = new JmxAttributeGauge(poolName, "Usage");
66
registry.register("jvm.memory.pool.eden.usage", poolUsage);
67

68
// Monitor garbage collector information
69
ObjectName gcName = new ObjectName("java.lang:type=GarbageCollector,name=PS Scavenge");
70
JmxAttributeGauge gcCount = new JmxAttributeGauge(gcName, "CollectionCount");
71
JmxAttributeGauge gcTime = new JmxAttributeGauge(gcName, "CollectionTime");
72
registry.register("jvm.gc.ps-scavenge.count", gcCount);
73
registry.register("jvm.gc.ps-scavenge.time", gcTime);
74

75
// Access attribute values
76
Object heapUsage = heapUsed.getValue();
77
System.out.println("Heap usage: " + heapUsage);
78

79
Long collectionCount = (Long) gcCount.getValue();
80
Long collectionTime = (Long) gcTime.getValue();
81
System.out.println("GC collections: " + collectionCount);
82
System.out.println("GC time: " + collectionTime + " ms");
83

84
// Custom MBeanServerConnection
85
MBeanServerConnection customConnection = ManagementFactory.getPlatformMBeanServer();
86
ObjectName customName = new ObjectName("com.example:type=CustomMetric");
87
JmxAttributeGauge customGauge = new JmxAttributeGauge(customConnection, customName, "Value");
88
registry.register("custom.metric", customGauge);
89
```
90

91
**Pattern Matching Support:**
92

93
The JmxAttributeGauge supports ObjectName patterns for dynamic MBean discovery:
94

95
```java
96
// Pattern-based ObjectName for dynamic discovery
97
ObjectName pattern = new ObjectName("java.lang:type=MemoryPool,name=*");
98
JmxAttributeGauge dynamicGauge = new JmxAttributeGauge(pattern, "Usage");
99

100
// When multiple MBeans match the pattern, the first one found is used
101
// For single-match scenarios, this provides flexibility in MBean naming
102
```
103

104
**Common JMX ObjectName Patterns:**
105

106
```java
107
// Memory and GC monitoring
108
new ObjectName("java.lang:type=Memory");
109
new ObjectName("java.lang:type=MemoryPool,name=*");
110
new ObjectName("java.lang:type=GarbageCollector,name=*");
111

112
// Thread monitoring
113
new ObjectName("java.lang:type=Threading");
114

115
// Class loading
116
new ObjectName("java.lang:type=ClassLoading");
117

118
// Runtime information
119
new ObjectName("java.lang:type=Runtime");
120

121
// Operating system
122
new ObjectName("java.lang:type=OperatingSystem");
123

124
// Buffer pools (Java 7+)
125
new ObjectName("java.nio:type=BufferPool,name=*");
126

127
// Application-specific MBeans
128
new ObjectName("com.myapp:type=DatabasePool,name=primary");
129
new ObjectName("com.myapp:type=Cache,name=*");
130
```
131

132
**Error Handling:**
133

134
```java
135
// Robust error handling example
136
public class SafeJmxAttributeGauge extends JmxAttributeGauge {
137
    private final String description;
138
    
139
    public SafeJmxAttributeGauge(ObjectName objectName, String attributeName, String description) {
140
        super(objectName, attributeName);
141
        this.description = description;
142
    }
143
    
144
    @Override
145
    public Object getValue() {
146
        try {
147
            Object value = super.getValue();
148
            if (value == null) {
149
                System.err.println("Warning: " + description + " returned null");
150
            }
151
            return value;
152
        } catch (Exception e) {
153
            System.err.println("Error reading " + description + ": " + e.getMessage());
154
            return null;
155
        }
156
    }
157
}
158

159
// Usage with error handling
160
SafeJmxAttributeGauge safeGauge = new SafeJmxAttributeGauge(
161
    new ObjectName("java.lang:type=Memory"),
162
    "HeapMemoryUsage",
163
    "JVM Heap Memory Usage"
164
);
165
```
166

167
**Composite Attributes:**
168

169
Many JMX attributes return composite data types. Handle them appropriately:
170

171
```java
172
import javax.management.openmbean.CompositeData;
173

174
JmxAttributeGauge memoryUsage = new JmxAttributeGauge(
175
    new ObjectName("java.lang:type=Memory"), 
176
    "HeapMemoryUsage"
177
);
178

179
Object value = memoryUsage.getValue();
180
if (value instanceof CompositeData) {
181
    CompositeData composite = (CompositeData) value;
182
    Long used = (Long) composite.get("used");
183
    Long max = (Long) composite.get("max");
184
    Long committed = (Long) composite.get("committed");
185
    Long init = (Long) composite.get("init");
186
    
187
    System.out.println("Heap used: " + used);
188
    System.out.println("Heap max: " + max);
189
    System.out.println("Heap committed: " + committed);
190
    System.out.println("Heap init: " + init);
191
}
192
```
193

194
**Best Practices:**
195

196
- **Null Checking**: Always check for null return values due to JMX connectivity issues
197
- **Type Safety**: Cast return values appropriately based on expected attribute types  
198
- **Connection Management**: Use appropriate MBeanServerConnection for local vs. remote monitoring
199
- **Pattern Usage**: Use ObjectName patterns judiciously to avoid unexpected MBean matches
200
- **Error Handling**: Implement robust error handling for network and availability issues