0
# Configuration
1

2
Configuration properties and build-time setup for customizing SmallRye Metrics behavior in Quarkus applications.
3

4
## Capabilities
5

6
### SmallRyeMetricsConfig
7

8
Configuration interface defining all available properties for SmallRye Metrics extension.
9

10
```java { .api }
11
/**
12
 * Configuration mapping for SmallRye Metrics extension properties
13
 * All properties use the quarkus.smallrye-metrics prefix
14
 */
15
@ConfigMapping(prefix = "quarkus.smallrye-metrics")
16
public interface SmallRyeMetricsConfig {
17
    // Configuration properties are accessed via application.properties
18
    // or environment variables with corresponding names
19
}
20
```
21

22
### Configuration Properties
23

24
#### Metrics Endpoint Path
25

26
```java { .api }
27
// Property: quarkus.smallrye-metrics.path
28
// Default: "metrics"
29
// Type: String
30
// Description: The path for the metrics endpoint
31
```
32

33
**Usage Example:**
34

35
```properties
36
# Default metrics endpoint: /q/metrics
37
quarkus.smallrye-metrics.path=metrics
38

39
# Custom metrics endpoint: /q/custom-metrics  
40
quarkus.smallrye-metrics.path=custom-metrics
41

42
# Root level metrics: /metrics
43
quarkus.smallrye-metrics.path=/metrics
44
```
45

46
#### Extension Metrics Control
47

48
```java { .api }
49
// Property: quarkus.smallrye-metrics.extensions.enabled
50
// Default: true
51
// Type: Boolean
52
// Description: Enable or disable extension-provided metrics
53
```
54

55
**Usage Example:**
56

57
```properties
58
# Enable extension metrics (default)
59
quarkus.smallrye-metrics.extensions.enabled=true
60

61
# Disable extension metrics
62
quarkus.smallrye-metrics.extensions.enabled=false
63
```
64

65
#### Micrometer Compatibility Mode
66

67
```java { .api }
68
// Property: quarkus.smallrye-metrics.micrometer.compatibility
69
// Default: false
70
// Type: Boolean  
71
// Description: Enable Micrometer compatibility mode for migration
72
```
73

74
**Usage Example:**
75

76
```properties
77
# Enable Micrometer compatibility (for migration)
78
quarkus.smallrye-metrics.micrometer.compatibility=true
79

80
# Standard SmallRye Metrics mode (default)
81
quarkus.smallrye-metrics.micrometer.compatibility=false
82
```
83

84
#### JAX-RS Metrics Control
85

86
```java { .api }
87
// Property: quarkus.smallrye-metrics.jaxrs.enabled
88
// Default: false
89
// Type: Boolean
90
// Description: Enable automatic JAX-RS endpoint metrics collection
91
```
92

93
**Usage Example:**
94

95
```properties
96
# Enable JAX-RS metrics collection
97
quarkus.smallrye-metrics.jaxrs.enabled=true
98

99
# Disable JAX-RS metrics (default)
100
quarkus.smallrye-metrics.jaxrs.enabled=false
101
```
102

103
### MicroProfile Metrics Configuration
104

105
Standard MicroProfile Metrics properties are also supported:
106

107
```java { .api }
108
// Property prefix: mp.metrics
109
// These are standard MicroProfile Metrics configuration options
110
```
111

112
**Common MP Metrics Properties:**
113

114
```properties
115
# Disable specific metric types
116
mp.metrics.tags=app=myapp,version=1.0
117

118
# Configure metric export format
119
mp.metrics.defaulted=true
120
```
121

122
## Extension Metadata
123

124
### Extension Definition
125

126
The extension provides the following capabilities and metadata:
127

128
```java { .api }
129
/**
130
 * Extension metadata from quarkus-extension.yaml
131
 */
132
public class ExtensionMetadata {
133
    // Name: SmallRye Metrics
134
    // Short Name: metrics
135
    // Status: deprecated
136
    // Categories: observability
137
    // Configuration Prefixes: quarkus.smallrye-metrics., mp.metrics.
138
    // Capabilities: io.quarkus.metrics, io.quarkus.smallrye.metrics
139
}
140
```
141

142
### SPI Build Item (Deprecated)
143

144
```java { .api }
145
/**
146
 * Build item for metrics configuration (DEPRECATED)
147
 * Used during deployment-time processing
148
 */
149
@Deprecated
150
public final class MetricsConfigurationBuildItem extends SimpleBuildItem {
151
    /** Create build item with metrics path */
152
    public MetricsConfigurationBuildItem(String path);
153
    
154
    /** Get the configured metrics path */
155
    public String getPath();
156
}
157
```
158

159
## Complete Configuration Example
160

161
### Application Properties
162

163
```properties
164
# Metrics endpoint configuration
165
quarkus.smallrye-metrics.path=observability/metrics
166

167
# Enable extension and JAX-RS metrics
168
quarkus.smallrye-metrics.extensions.enabled=true
169
quarkus.smallrye-metrics.jaxrs.enabled=true
170

171
# Micrometer compatibility for migration
172
quarkus.smallrye-metrics.micrometer.compatibility=true
173

174
# MicroProfile Metrics tags
175
mp.metrics.tags=application=user-service,version=2.1.0,environment=production
176
```
177

178
### Environment Variables
179

180
```bash
181
# Equivalent environment variables
182
QUARKUS_SMALLRYE_METRICS_PATH=observability/metrics
183
QUARKUS_SMALLRYE_METRICS_EXTENSIONS_ENABLED=true  
184
QUARKUS_SMALLRYE_METRICS_JAXRS_ENABLED=true
185
QUARKUS_SMALLRYE_METRICS_MICROMETER_COMPATIBILITY=true
186

187
MP_METRICS_TAGS=application=user-service,version=2.1.0
188
```
189

190
### Programmatic Configuration
191

192
```java
193
import org.eclipse.microprofile.config.ConfigProvider;
194

195
// Access configuration programmatically
196
Config config = ConfigProvider.getConfig();
197

198
String metricsPath = config.getValue("quarkus.smallrye-metrics.path", String.class);
199
boolean jaxrsEnabled = config.getValue("quarkus.smallrye-metrics.jaxrs.enabled", Boolean.class);
200
```
201

202
## Migration Configuration
203

204
### Transitioning to Micrometer
205

206
```properties
207
# Step 1: Enable compatibility mode
208
quarkus.smallrye-metrics.micrometer.compatibility=true
209

210
# Step 2: Add Micrometer extension to dependencies
211
# <dependency>
212
#   <groupId>io.quarkus</groupId>
213
#   <artifactId>quarkus-micrometer</artifactId>
214
# </dependency>
215

216
# Step 3: Configure Micrometer
217
quarkus.micrometer.enabled=true
218
quarkus.micrometer.export.prometheus.enabled=true
219

220
# Step 4: Remove SmallRye Metrics extension after testing
221
```
222

223
### Production Configuration
224

225
```properties
226
# Recommended production settings
227
quarkus.smallrye-metrics.path=metrics
228
quarkus.smallrye-metrics.extensions.enabled=true
229
quarkus.smallrye-metrics.jaxrs.enabled=true
230

231
# Production tags for monitoring
232
mp.metrics.tags=datacenter=us-east-1,service=user-api,instance=${HOSTNAME:unknown}
233

234
# Security: metrics endpoint typically behind management interface
235
quarkus.management.enabled=true
236
quarkus.management.port=9000
237
```
238

239
## Configuration Validation
240

241
### Required Dependencies
242

243
```xml
244
<!-- Core dependency -->
245
<dependency>
246
    <groupId>io.quarkus</groupId>
247
    <artifactId>quarkus-smallrye-metrics</artifactId>
248
</dependency>
249

250
<!-- Optional: Management interface for secure metrics -->
251
<dependency>
252
    <groupId>io.quarkus</groupId>
253
    <artifactId>quarkus-management</artifactId>
254
</dependency>
255
```
256

257
### Configuration Precedence
258

259
1. **System Properties**: `-Dquarkus.smallrye-metrics.path=custom`
260
2. **Environment Variables**: `QUARKUS_SMALLRYE_METRICS_PATH=custom`  
261
3. **application.properties**: `quarkus.smallrye-metrics.path=custom`
262
4. **Default Values**: Built-in defaults from extension
263

264
## Types
265

266
### Configuration Types
267

268
```java { .api }
269
// Configuration mapping annotation
270
@ConfigMapping(prefix = "quarkus.smallrye-metrics")
271
public interface SmallRyeMetricsConfig {
272
    // Properties are accessed via MicroProfile Config
273
}
274

275
// Build item for deployment processing
276
public final class MetricsConfigurationBuildItem extends SimpleBuildItem {
277
    public MetricsConfigurationBuildItem(String path);
278
    public String getPath();
279
}
280

281
// From MicroProfile Config
282
interface Config {
283
    <T> T getValue(String propertyName, Class<T> propertyType);
284
    <T> Optional<T> getOptionalValue(String propertyName, Class<T> propertyType);
285
}
286
```