0
# Core Runtime API
1

2
Core runtime classes for metrics metadata handling, factory integration, read-only counter implementations, and build-time processing.
3

4
## Capabilities
5

6
### MetadataHolder
7

8
Transfer object for metric metadata between build-time and runtime processing.
9

10
```java { .api }
11
/**
12
 * Wrapper for passing metric metadata from deployment to runtime
13
 */
14
public class MetadataHolder {
15
    /** Get the metric name */
16
    public String getName();
17
    /** Set the metric name */
18
    public void setName(String name);
19
    
20
    /** Get the metric type */
21
    public MetricType getMetricType();
22
    /** Set the metric type */
23
    public void setMetricType(MetricType metricType);
24
    
25
    /** Get the metric description */
26
    public String getDescription();
27
    /** Set the metric description */
28
    public void setDescription(String description);
29
    
30
    /** Get the display name */
31
    public String getDisplayName();
32
    /** Set the display name */
33
    public void setDisplayName(String displayName);
34
    
35
    /** Get the metric unit */
36
    public String getUnit();
37
    /** Set the metric unit */
38
    public void setUnit(String unit);
39
    
40
    /** Create MetadataHolder from MicroProfile Metrics Metadata */
41
    public static MetadataHolder from(Metadata metadata);
42
    
43
    /** Convert back to MicroProfile Metrics Metadata */
44
    public Metadata toMetadata();
45
}
46
```
47

48
**Usage Example:**
49

50
```java
51
import io.quarkus.smallrye.metrics.runtime.MetadataHolder;
52
import org.eclipse.microprofile.metrics.Metadata;
53
import org.eclipse.microprofile.metrics.MetricType;
54

55
// Convert from MP Metrics Metadata
56
Metadata mpMetadata = Metadata.builder()
57
    .withName("my_counter")
58
    .withType(MetricType.COUNTER)
59
    .withDescription("Counts something important")
60
    .build();
61

62
MetadataHolder holder = MetadataHolder.from(mpMetadata);
63

64
// Convert back to MP Metrics
65
Metadata converted = holder.toMetadata();
66
```
67

68
### TagHolder
69

70
Transfer object for metric tags between build-time and runtime processing.
71

72
```java { .api }
73
/**
74
 * Wrapper for passing metric tags from deployment to runtime
75
 */
76
public class TagHolder {
77
    /** Get the tag name */
78
    public String getName();
79
    /** Set the tag name */
80
    public void setName(String name);
81
    
82
    /** Get the tag value */
83
    public String getValue();
84
    /** Set the tag value */
85
    public void setValue(String value);
86
    
87
    /** Create TagHolder from MicroProfile Metrics Tag */
88
    public static TagHolder from(Tag tag);
89
    
90
    /** Convert back to MicroProfile Metrics Tag */
91
    public Tag toTag();
92
}
93
```
94

95
**Usage Example:**
96

97
```java
98
import io.quarkus.smallrye.metrics.runtime.TagHolder;
99
import org.eclipse.microprofile.metrics.Tag;
100

101
// Convert from MP Metrics Tag
102
Tag mpTag = new Tag("environment", "production");
103
TagHolder holder = TagHolder.from(mpTag);
104

105
// Convert back to MP Metrics
106
Tag converted = holder.toTag();
107
```
108

109
### SmallRyeMetricsFactory
110

111
Implementation of Quarkus MetricsFactory for SmallRye Metrics integration.
112

113
```java { .api }
114
/**
115
 * Implementation of Quarkus MetricsFactory for SmallRye Metrics
116
 */
117
public class SmallRyeMetricsFactory implements MetricsFactory {
118
    /** Check if the metrics system supports the named metrics system */
119
    public boolean metricsSystemSupported(String name);
120
    
121
    /** Create a metric builder for the specified type */
122
    public MetricBuilder builder(String name, MetricsFactory.Type type);
123
}
124

125
/**
126
 * Internal metric builder implementation
127
 */
128
static class SmallRyeMetricBuilder implements MetricsFactory.MetricBuilder {
129
    /** Set the metric unit */
130
    public MetricBuilder unit(String unit);
131
    
132
    /** Add a tag to the metric */
133
    public MetricBuilder tag(String key, String value);
134
    
135
    /** Set the metric description */
136
    public MetricBuilder description(String description);
137
    
138
    /** Build a counter metric with supplier function */
139
    public void buildCounter(Supplier<Number> countFunction);
140
    
141
    /** Build a counter metric with object and function */
142
    public <T, R extends Number> void buildCounter(T obj, Function<T, R> countFunction);
143
    
144
    /** Build a gauge metric with supplier function */
145
    public void buildGauge(Supplier<Number> gaugeFunction);
146
    
147
    /** Build a gauge metric with object and function */
148
    public <T, R extends Number> void buildGauge(T obj, Function<T, R> gaugeFunction);
149
    
150
    /** Build a timer metric and return time recorder */
151
    public TimeRecorder buildTimer();
152
    
153
    /** Build a timer metric wrapping a Runnable */
154
    public Runnable buildTimer(Runnable f);
155
    
156
    /** Build a timer metric wrapping a Callable */
157
    public <T> Callable<T> buildTimer(Callable<T> f);
158
    
159
    /** Build a timer metric wrapping a Supplier */
160
    public <T> Supplier<T> buildTimer(Supplier<T> f);
161
}
162
```
163

164
**Usage Example:**
165

166
```java
167
import io.quarkus.smallrye.metrics.runtime.SmallRyeMetricsFactory;
168
import io.quarkus.runtime.metrics.MetricsFactory;
169

170
SmallRyeMetricsFactory factory = new SmallRyeMetricsFactory();
171

172
// Check if system is supported
173
boolean supported = factory.metricsSystemSupported("smallrye-metrics");
174

175
// Create a metric builder
176
MetricBuilder builder = factory.builder("my_metric", MetricsFactory.Type.APPLICATION);
177
```
178

179
### FilterUtil
180

181
Internal utility class for JAX-RS metrics collection and REST endpoint metric creation.
182

183
```java { .api }
184
/**
185
 * Internal utility class for JAX-RS metrics collection
186
 * Package-private class used by filter implementations
187
 */
188
final class FilterUtil {
189
    /** Complete a request and record metrics based on success/failure */
190
    static void finishRequest(Long start, Class<?> resourceClass, String methodName, 
191
                            Class<?>[] parameterTypes, Supplier<Boolean> wasSuccessful);
192
    
193
    /** Create metrics for a REST endpoint if they don't already exist */
194
    static void maybeCreateMetrics(Class<?> resourceClass, Method resourceMethod);
195
    
196
    /** Generate MetricID for REST endpoint metrics */
197
    static MetricID getMetricID(Class<?> resourceClass, String methodName, 
198
                              Class<?>[] parameterTypes, boolean requestWasSuccessful);
199
}
200
```
201

202
**Usage Example:**
203

204
```java
205
// This class is used internally by QuarkusRestMetricsFilter and QuarkusRestEasyMetricsFilter
206
// Application code typically doesn't interact with it directly
207

208
// Example usage in filters:
209
FilterUtil.maybeCreateMetrics(MyResource.class, method);
210
FilterUtil.finishRequest(startTime, MyResource.class, "getUsers", 
211
                        new Class[0], () -> true);
212

213
// Generates metric names like:
214
// - REST.request (for successful requests)
215
// - REST.request.unmappedException.total (for failed requests)
216
// With tags: class=com.example.MyResource, method=getUsers
217
```
218

219
### GetCountOnlyCounter
220

221
Abstract base class for implementing read-only counter metrics.
222

223
```java { .api }
224
/**
225
 * Helper abstract class for implementing read-only counters
226
 * Implements org.eclipse.microprofile.metrics.Counter
227
 */
228
public abstract class GetCountOnlyCounter implements Counter {
229
    /** Get the current count value - must be implemented by subclasses */
230
    public abstract long getCount();
231
    
232
    /** Increment counter - throws IllegalStateException (read-only) */
233
    public void inc();
234
    
235
    /** Increment counter by specified amount - throws IllegalStateException (read-only) */
236
    public void inc(long n);
237
}
238
```
239

240
**Usage Example:**
241

242
```java
243
import io.quarkus.smallrye.metrics.runtime.GetCountOnlyCounter;
244

245
// Implementation of a read-only counter
246
public class MyReadOnlyCounter extends GetCountOnlyCounter {
247
    private final AtomicLong value = new AtomicLong(0);
248
    
249
    @Override
250
    public long getCount() {
251
        return value.get();
252
    }
253
    
254
    // inc() and inc(long) will throw IllegalStateException
255
}
256
```
257

258
### SmallRyeMetricsRecorder
259

260
Build-time recorder for metrics configuration and registration. This class handles deployment-time processing for optimal native compilation.
261

262
```java { .api }
263
/**
264
 * Build-time recorder for metrics configuration
265
 * Annotated with @Recorder for Quarkus build-time processing
266
 */
267
@Recorder
268
public class SmallRyeMetricsRecorder {
269
    /** Create metrics handler with specified path */
270
    public SmallRyeMetricsHandler handler(String metricsPath);
271
    
272
    /** Register vendor-specific metrics */
273
    public void registerVendorMetrics();
274
    
275
    /** Register base JVM metrics */
276
    public void registerBaseMetrics();
277
    
278
    /** Register Micrometer-compatible JVM metrics */
279
    public void registerMicrometerJvmMetrics(ShutdownContext shutdown);
280
    
281
    /** Register metrics from bean and member information */
282
    public void registerMetrics(BeanInfo beanInfo, MemberInfo memberInfo);
283
    
284
    /** Register individual metric with metadata and tags */
285
    public void registerMetric(/* multiple overloads for different metric types */);
286
    
287
    /** Register metrics via factory consumer */
288
    public void registerMetrics(Consumer<MetricsFactory> consumer);
289
    
290
    /** Initialize metric registries */
291
    public void createRegistries(BeanContainer container);
292
    
293
    /** Cleanup registries at shutdown */
294
    public void dropRegistriesAtShutdown(ShutdownContext shutdownContext);
295
}
296
```
297

298
**Usage Example:**
299

300
```java
301
// This class is primarily used by the Quarkus deployment processor
302
// Application code typically doesn't interact with it directly
303

304
@BuildStep
305
void registerApplicationMetrics(SmallRyeMetricsRecorder recorder) {
306
    // Build-time metric registration
307
    recorder.registerVendorMetrics();
308
    recorder.registerBaseMetrics();
309
}
310
```
311

312
## Types
313

314
### Key Types from Dependencies
315

316
```java { .api }
317
// From MicroProfile Metrics API
318
interface Metadata {
319
    String getName();
320
    MetricType getType();
321
    String getDescription();
322
    String getDisplayName();
323
    String getUnit();
324
}
325

326
class Tag {
327
    Tag(String name, String value);
328
    String getTagName();
329
    String getTagValue();
330
}
331

332
enum MetricType {
333
    COUNTER, GAUGE, TIMER, HISTOGRAM, METER, CONCURRENT_GAUGE
334
}
335

336
// From Quarkus Runtime Metrics
337
interface MetricsFactory {
338
    boolean metricsSystemSupported(String name);
339
    MetricBuilder builder(String name, Type type);
340
    
341
    enum Type {
342
        APPLICATION, BASE, VENDOR
343
    }
344
}
345
```