0
# Micrometer JMX Registry
1
2
A JMX (Java Management Extensions) registry implementation for the Micrometer application metrics facade. This library enables applications to expose metrics via JMX MBeans, allowing monitoring tools and management consoles to access application metrics through the standard JMX interface.
3
4
## Package Information
5
6
- **Package Name**: micrometer-registry-jmx
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Group ID**: io.micrometer
10
- **Artifact ID**: micrometer-registry-jmx
11
- **Installation**: Add dependency to your build file
12
13
Maven:
14
```xml
15
<dependency>
16
<groupId>io.micrometer</groupId>
17
<artifactId>micrometer-registry-jmx</artifactId>
18
<version>2.0.0-M3</version>
19
</dependency>
20
```
21
22
Gradle:
23
```gradle
24
implementation 'io.micrometer:micrometer-registry-jmx:2.0.0-M3'
25
```
26
27
## Core Imports
28
29
```java
30
import io.micrometer.jmx.JmxMeterRegistry;
31
import io.micrometer.jmx.JmxConfig;
32
import io.micrometer.core.instrument.Clock;
33
import io.micrometer.core.instrument.util.HierarchicalNameMapper;
34
```
35
36
## Basic Usage
37
38
```java
39
import io.micrometer.jmx.JmxMeterRegistry;
40
import io.micrometer.jmx.JmxConfig;
41
import io.micrometer.core.instrument.Clock;
42
import io.micrometer.core.instrument.Timer;
43
44
// Create JMX registry with default configuration
45
JmxMeterRegistry registry = new JmxMeterRegistry(JmxConfig.DEFAULT, Clock.SYSTEM);
46
47
// Create and use meters
48
Timer timer = registry.timer("request.duration");
49
timer.record(() -> {
50
// Your timed code here
51
});
52
53
// Metrics are automatically published to JMX MBeans
54
// Access via JConsole, VisualVM, or programmatically via MBeanServer
55
```
56
57
## Architecture
58
59
The JMX registry implementation consists of several key components:
60
61
- **JmxMeterRegistry**: Main registry class that extends DropwizardMeterRegistry
62
- **JmxConfig**: Configuration interface for JMX-specific settings like domain name
63
- **JmxReporter Integration**: Uses Dropwizard Metrics' JmxReporter for MBean registration
64
- **Name Mapping**: Converts dimensional metric names to hierarchical JMX object names
65
- **Lifecycle Management**: Provides start/stop control for JMX metric publication
66
- **Automatic Startup**: The JMX reporter automatically starts upon registry construction
67
68
## Capabilities
69
70
### JMX Meter Registry
71
72
The main registry class that collects metrics and publishes them as JMX MBeans.
73
74
```java { .api }
75
public class JmxMeterRegistry extends DropwizardMeterRegistry {
76
77
/**
78
* Create JMX registry with default name mapper
79
*/
80
public JmxMeterRegistry(JmxConfig config, Clock clock);
81
82
/**
83
* Create JMX registry with custom name mapper
84
*/
85
public JmxMeterRegistry(JmxConfig config, Clock clock, HierarchicalNameMapper nameMapper);
86
87
/**
88
* Create JMX registry with custom metric registry
89
*/
90
public JmxMeterRegistry(JmxConfig config, Clock clock, HierarchicalNameMapper nameMapper, MetricRegistry metricRegistry);
91
92
/**
93
* Create JMX registry with full customization
94
* Note: The JMX reporter starts automatically upon construction
95
*/
96
public JmxMeterRegistry(JmxConfig config, Clock clock, HierarchicalNameMapper nameMapper, MetricRegistry metricRegistry, JmxReporter jmxReporter);
97
98
/**
99
* Start the JMX reporter to begin publishing metrics
100
*/
101
public void start();
102
103
/**
104
* Stop the JMX reporter to cease publishing metrics
105
*/
106
public void stop();
107
108
/**
109
* Close the registry and stop the JMX reporter
110
*/
111
@Override
112
public void close();
113
114
}
115
```
116
117
### JMX Configuration
118
119
Configuration interface for JMX-specific settings.
120
121
```java { .api }
122
public interface JmxConfig extends DropwizardConfig {
123
124
/**
125
* Accept configuration defaults
126
*/
127
JmxConfig DEFAULT = k -> null;
128
129
@Override
130
default String prefix();
131
132
/**
133
* @return JMX domain under which to publish metrics.
134
*/
135
default String domain();
136
}
137
```
138
139
## Types
140
141
### Inherited Types
142
143
The JMX registry inherits all standard Micrometer types through DropwizardMeterRegistry:
144
145
```java { .api }
146
// From Micrometer Core
147
import io.micrometer.core.instrument.Clock;
148
import io.micrometer.core.instrument.util.HierarchicalNameMapper;
149
import io.micrometer.core.instrument.dropwizard.DropwizardConfig;
150
151
// From Dropwizard Metrics
152
import com.codahale.metrics.MetricRegistry;
153
import com.codahale.metrics.jmx.JmxReporter;
154
```
155
156
### Standard Meter Types
157
158
All standard Micrometer meter types are supported:
159
160
- **Counter**: Monotonically increasing values
161
- **Gauge**: Current value snapshots
162
- **Timer**: Duration and frequency of events
163
- **DistributionSummary**: Distribution of event sizes
164
- **LongTaskTimer**: Duration of long-running tasks
165
- **FunctionCounter**: Counter backed by a function
166
- **FunctionTimer**: Timer backed by functions
167
- **TimeGauge**: Gauge for time-based values
168
169
## Usage Examples
170
171
### Basic Setup
172
173
```java
174
import io.micrometer.jmx.JmxMeterRegistry;
175
import io.micrometer.jmx.JmxConfig;
176
import io.micrometer.core.instrument.Clock;
177
178
// Create registry
179
JmxMeterRegistry registry = new JmxMeterRegistry(JmxConfig.DEFAULT, Clock.SYSTEM);
180
181
// Create metrics
182
registry.counter("requests.total").increment();
183
registry.gauge("memory.usage", Runtime.getRuntime().totalMemory());
184
registry.timer("request.duration").record(Duration.ofMillis(150));
185
```
186
187
### Custom Configuration
188
189
```java
190
import io.micrometer.jmx.JmxConfig;
191
192
// Custom configuration
193
JmxConfig config = new JmxConfig() {
194
@Override
195
public String domain() {
196
return "myapp.metrics"; // Custom JMX domain
197
}
198
199
@Override
200
public String get(String key) {
201
return null; // Use defaults for other settings
202
}
203
};
204
205
JmxMeterRegistry registry = new JmxMeterRegistry(config, Clock.SYSTEM);
206
```
207
208
### Custom Name Mapping
209
210
```java
211
import io.micrometer.core.instrument.util.HierarchicalNameMapper;
212
213
// Custom name mapper for JMX object names
214
HierarchicalNameMapper nameMapper = (id, convention) -> {
215
return "myapp." + id.getName().replace(".", "_");
216
};
217
218
JmxMeterRegistry registry = new JmxMeterRegistry(
219
JmxConfig.DEFAULT,
220
Clock.SYSTEM,
221
nameMapper
222
);
223
```
224
225
### Lifecycle Management
226
227
```java
228
JmxMeterRegistry registry = new JmxMeterRegistry(JmxConfig.DEFAULT, Clock.SYSTEM);
229
230
// Registry starts automatically upon construction, but you can control it
231
registry.stop(); // Stop publishing metrics
232
registry.start(); // Resume publishing metrics
233
234
// Proper cleanup
235
registry.close(); // Stops reporter and closes registry
236
```
237
238