0
# HTTP Integration
1

2
JAX-RS filters and Vert.x handlers for automatic metrics collection from REST endpoints and metrics endpoint exposure.
3

4
## Capabilities
5

6
### QuarkusRestMetricsFilter
7

8
JAX-RS response filter for automatic metrics collection from Quarkus REST endpoints.
9

10
```java { .api }
11
/**
12
 * JAX-RS response filter for Quarkus REST metrics collection
13
 * Automatically collects timing and request count metrics for REST endpoints
14
 */
15
@ServerResponseFilter
16
public class QuarkusRestMetricsFilter {
17
    // Filter is automatically applied to Quarkus REST endpoints
18
    // No public methods - integration is annotation-based
19
}
20
```
21

22
**Usage Example:**
23

24
```java
25
// Filter is automatically applied when the extension is present
26
// No explicit configuration needed - metrics are collected automatically
27

28
@Path("/api")
29
public class MyResource {
30
    
31
    @GET
32
    @Path("/users")
33
    public List<User> getUsers() {
34
        // Metrics automatically collected:
35
        // - REST.request timer (execution time)
36
        // - Request count by status code
37
        return userService.getAllUsers();
38
    }
39
}
40
```
41

42
### QuarkusRestEasyMetricsFilter
43

44
JAX-RS filter for automatic metrics collection from RESTEasy Classic endpoints.
45

46
```java { .api }
47
/**
48
 * JAX-RS filter for RESTEasy metrics collection
49
 * Implements both request and response filtering
50
 */
51
public class QuarkusRestEasyMetricsFilter 
52
    implements ContainerRequestFilter, ContainerResponseFilter {
53
    
54
    /** Filter incoming requests to start timing */
55
    public void filter(ContainerRequestContext requestContext);
56
    
57
    /** Filter outgoing responses to complete timing and record metrics */
58
    public void filter(
59
        ContainerRequestContext requestContext,
60
        ContainerResponseContext responseContext
61
    );
62
}
63
```
64

65
**Usage Example:**
66

67
```java
68
// Filter is automatically applied when using RESTEasy Classic
69
// Metrics are collected for all JAX-RS endpoints
70

71
@Path("/api/v1")
72
public class LegacyResource {
73
    
74
    @GET
75
    @Path("/products")
76
    public Response getProducts() {
77
        // Metrics automatically collected:
78
        // - Request timing
79
        // - Response status codes
80
        // - Request counts
81
        return Response.ok(productService.getAllProducts()).build();
82
    }
83
}
84
```
85

86
### SmallRyeMetricsHandler
87

88
Vert.x handler for exposing metrics endpoint via HTTP.
89

90
```java { .api }
91
/**
92
 * Vert.x handler for metrics endpoint exposure
93
 * Handles HTTP requests to the metrics endpoint
94
 */
95
public class SmallRyeMetricsHandler implements Handler<RoutingContext> {
96
    /** Configure the metrics endpoint path */
97
    public void setMetricsPath(String metricsPath);
98
    
99
    /** Handle incoming HTTP requests for metrics */
100
    public void handle(RoutingContext routingContext);
101
}
102
```
103

104
**Usage Example:**
105

106
```java
107
import io.quarkus.smallrye.metrics.runtime.SmallRyeMetricsHandler;
108
import io.vertx.ext.web.RoutingContext;
109

110
// Typically configured by the extension deployment processor
111
SmallRyeMetricsHandler handler = new SmallRyeMetricsHandler();
112
handler.setMetricsPath("/custom-metrics");
113

114
// Handler processes requests to metrics endpoint
115
// Returns metrics in Prometheus format by default
116
// Supports JSON format via Accept: application/json header
117
```
118

119
## Automatic Metrics Collection
120

121
### REST Endpoint Metrics
122

123
The extension automatically collects metrics for JAX-RS endpoints:
124

125
```java { .api }
126
// Metrics automatically created:
127
// - REST.request timer per endpoint
128
// - Request counts by HTTP status code
129
// - Response time percentiles
130
// - Exception counts
131

132
// Timer naming pattern:
133
// REST.request.{class}.{method}
134
// Tags: class, method, uri, status
135

136
// Example metric names:
137
// REST.request.com_example_UserResource_getUsers_GET
138
// REST.request.com_example_ProductResource_createProduct_POST
139
```
140

141
**Metric Tags:**
142

143
```java
144
// Tags applied to REST metrics:
145
Tag.of("class", "com.example.UserResource")
146
Tag.of("method", "getUsers") 
147
Tag.of("uri", "/api/users")
148
Tag.of("status", "200")
149
```
150

151
### Metrics Endpoint
152

153
The `/q/metrics` endpoint (or custom path) exposes all metrics:
154

155
```java { .api }
156
// Default endpoint: /q/metrics
157
// Configurable via: quarkus.smallrye-metrics.path
158

159
// Response formats:
160
// - Prometheus format (default, text/plain)
161
// - JSON format (Accept: application/json)
162

163
// Example Prometheus output:
164
// # TYPE REST_request_total counter
165
// REST_request_total{class="UserResource",method="getUsers",status="200"} 42
166
//
167
// # TYPE REST_request_seconds summary  
168
// REST_request_seconds{class="UserResource",method="getUsers",quantile="0.5"} 0.123
169
```
170

171
## Integration with Vert.x
172

173
### Handler Registration
174

175
```java { .api }
176
// Handler is registered by the deployment processor
177
// Typically at build time via SmallRyeMetricsRecorder
178

179
// Example registration (internal):
180
Router router = Router.router(vertx);
181
SmallRyeMetricsHandler handler = recorder.handler("/q/metrics");
182
router.get("/q/metrics").handler(handler);
183
```
184

185
### Request Processing
186

187
The metrics handler processes requests:
188

189
1. **Content Negotiation**: Checks Accept header for format preference
190
2. **Registry Selection**: Handles scope parameter (`scope=application`, `scope=base`, `scope=vendor`)  
191
3. **Format Rendering**: Returns metrics in requested format (Prometheus/JSON)
192
4. **Error Handling**: Returns appropriate HTTP status codes for errors
193

194
## Configuration Integration
195

196
### JAX-RS Metrics Control
197

198
```java
199
// Enable/disable JAX-RS metrics collection
200
// quarkus.smallrye-metrics.jaxrs.enabled=true|false
201

202
// When disabled, REST endpoint metrics are not collected
203
// Application and base metrics remain available
204
```
205

206
### Metrics Path Configuration
207

208
```java
209
// Default metrics path: /q/metrics
210
// Custom path via configuration:
211
// quarkus.smallrye-metrics.path=/custom-metrics
212

213
SmallRyeMetricsHandler handler = new SmallRyeMetricsHandler();
214
handler.setMetricsPath("/custom-metrics");
215
```
216

217
## Types
218

219
### Key Integration Types
220

221
```java { .api }
222
// JAX-RS Types
223
interface ContainerRequestFilter {
224
    void filter(ContainerRequestContext requestContext);
225
}
226

227
interface ContainerResponseFilter {
228
    void filter(
229
        ContainerRequestContext requestContext,
230
        ContainerResponseContext responseContext
231
    );
232
}
233

234
// Vert.x Types  
235
interface Handler<T> {
236
    void handle(T event);
237
}
238

239
class RoutingContext {
240
    HttpServerRequest request();
241
    HttpServerResponse response();
242
    void next();
243
    void fail(int statusCode);
244
}
245
```