How to Add Health Checks Metrics and Tracing in Quarkus
Add health checks, Micrometer metrics and OpenTelemetry tracing to a Quarkus service: the extensions, endpoints, custom checks and settings for Kubernetes.

A service in production needs to answer three questions: is it alive, how is it behaving, and where did a slow request spend its time. Quarkus answers them through three extensions that share one configuration style and need almost no code. This guide wires up health checks, metrics and tracing on Quarkus 3 and JDK 25, in a Kubernetes-style deployment, and spends as much time on what not to put in each as on what to put. The deployment side, including probe timings, is in probes and resources.
Add the extensions
quarkus extension add smallrye-health micrometer-registry-prometheus opentelemetryThree names, three jobs. SmallRye Health implements the MicroProfile Health specification, Micrometer collects metrics and exposes them in the Prometheus format, and OpenTelemetry produces traces. None of them needs code to be useful: with the extensions on the classpath you already get endpoints, standard JVM metrics and spans for incoming requests.
Health checks
With the extension present, /q/health reports UP or DOWN, and /q/health/live, /q/health/ready and /q/health/started report the three probe types separately. A custom check is a bean:
@Readiness
@ApplicationScoped
public class PaymentGatewayCheck implements HealthCheck {
@Inject PaymentGateway gateway;
@Override
public HealthCheckResponse call() {
return gateway.ping()
? HealthCheckResponse.up("payment-gateway")
: HealthCheckResponse.down("payment-gateway");
}
}| Qualifier | Question it answers | Used for |
|---|---|---|
@Liveness | Is the process stuck beyond recovery? | Restart decision |
@Readiness | Can it take traffic now? | Load balancer routing |
@Startup | Has it finished starting? | Delays the other probes |
Keep liveness cheap and independent of other systems. If liveness checks the database, a database outage makes Kubernetes restart every pod at once, which turns a partial failure into a total one and delays recovery because every pod must warm up again. Datasource and messaging checks belong in readiness, where a failure removes the pod from rotation without killing it, and the extensions for those add their checks automatically. A readiness check that calls a remote service on every probe also adds load to that service, so cache its result for a few seconds.
Metrics
Micrometer collects JVM, HTTP server and HTTP client metrics out of the box, and /q/metrics serves the Prometheus format. Add your own with the registry:
@Inject MeterRegistry registry;
void orderPlaced(Order order) {
registry.counter("orders.placed", "channel", order.channel()).increment();
}Keep tag values bounded. A tag holding a user id or an order id creates one time series per value, which overloads the metrics store and its bill. Tag by channel, status and region, never by identifier. Choose metric names in dot notation and let the registry convert them to the Prometheus convention. Timers are better than gauges for durations: a Timer gives count, sum and a histogram, from which a dashboard can compute rates and percentiles. For the JVM-level detail behind a dashboard, see JDK diagnostic tools.
Tracing
quarkus.application.name=orders
quarkus.otel.exporter.otlp.endpoint=http://otel-collector:4317
quarkus.otel.traces.sampler=parentbased_traceidratio
quarkus.otel.traces.sampler.arg=0.1Incoming HTTP requests become spans, and outgoing calls through the REST client and many drivers continue the trace by passing a W3C traceparent header. The parentbased sampler respects the caller's decision, so a trace is complete or absent across services, not half-recorded. Sample a fraction in production, because recording every request costs CPU and storage; ten percent is a starting point to adjust from cost and from how often you need to find a specific request. To add a custom span around a unit of work, annotate a method with @WithSpan.
Put the trace id in the logs so a trace and its log lines can be joined. With the OpenTelemetry extension the trace and span ids are available in the MDC, and a log format that prints them lets support go from a customer's error to the whole request in two clicks. The message side is covered in writing log messages.
Protect the management endpoints
/q/health, /q/metrics and the Dev UI describe your internals. In production, move them to a separate port or restrict them with network policy:
quarkus.management.enabled=true
quarkus.management.port=9000Probes and Prometheus scrape the management port, and the public port serves only the application. This also stops a public load balancer from exposing metrics by accident. If you cannot split the port, put the endpoints behind authentication or block the /q/ prefix at the ingress.
Checking that it works
Start the application and call each endpoint by hand: curl localhost:8080/q/health/ready should return UP, and curl localhost:8080/q/metrics | head should show lines starting with jvm_ and http_server_requests. Break something on purpose, such as pointing the datasource at a closed port, and confirm that readiness goes DOWN while liveness stays UP. That one experiment tells you whether the probe design will behave during a real outage. In a test, @QuarkusTest can assert on the health endpoint with REST Assured.
Alerting on what these signals say
Collecting signals is half the job; the other half is deciding which ones page a person. Alert on symptoms that users feel, not on every metric that moves. Three rules cover most services: the error rate of the HTTP server above a threshold for several minutes, the 99th percentile latency above the agreed target, and readiness failing on more than a fraction of the pods. CPU and heap graphs belong on dashboards used during an investigation, not in the pager rotation. Write each alert with a runbook link that says what to check first, and delete alerts that fire without anyone acting on them, since an ignored alert teaches the team to ignore the next one.
Cost and cardinality
Metrics and traces both cost money in proportion to volume. Review the number of active time series every quarter, and look for the label that exploded. Common offenders are a path template that includes raw ids, because the HTTP metrics record the matched route only when the framework knows it, and a custom tag holding a free-form string. For traces, keep span names low-cardinality as well, and use attributes for the details. If the bill is rising, lower the sampling ratio before removing instrumentation.
Where this setup is more than you need
For a single instance on a VM with no orchestrator, a simple health URL and log-based monitoring may be enough, and tracing adds a collector to operate for little gain. Add tracing when a request crosses services, not before. The full options are in the SmallRye Health guide, the Micrometer guide and the OpenTelemetry guide.


