Micrometer Metrics & Export

A Counter records a value that only ever goes up (a total, like requests served). Use a Counter for cumulative counts you increment; use a Gauge for a value that can go up and down, like current queue size.

Add the micrometer-registry-prometheus dependency and expose the endpoint with management.endpoints.web.exposure.include=prometheus. Spring Boot then serves metrics as plain text at /actuator/prometheus, which the Prometheus server reads (scrapes).

MeterRegistry is Micrometer's central object that creates and holds meters (counters, gauges, timers). Spring Boot auto-configures one and injects it, so your code records metrics through it without knowing which monitoring backend receives them.

Tags are key/value labels (like method=GET, status=200) attached to a meter. They let you slice one metric by dimensions and filter or group in your monitoring system instead of creating many separate metrics.

A Timer measures how long operations take and counts how often they run. Register one on the MeterRegistry, then wrap the code with timer.record(() -> ...) or record a Duration, and Micrometer tracks count, total time, and max.

The @Timed annotation does nothing by itself — a TimedAspect bean has to intercept the method. If Spring AOP or that aspect bean is missing, nothing is recorded. Add spring-boot-starter-aop and make sure TimedAspect (and CountedAspect) are registered.

http.server.requests is a Timer recorded for every HTTP request, tagged with uri, method, status and outcome so you can see request rate, error rate and latency per endpoint. It is added automatically by an Actuator filter.

You bind the Gauge to an object plus a function that reads its current value, e.g. Gauge.builder("queue.size", queue, Queue::size).register(registry). Micrometer calls that function each time the registry is scraped, so the reported value is always current.

PrometheusMeterRegistry exposes metrics at /actuator/prometheus and waits for the Prometheus server to scrape (pull). OtlpMeterRegistry actively pushes metrics on a timer to an OTLP endpoint like an OpenTelemetry Collector. One waits; the other sends.

Each monitoring backend has its own MeterRegistry implementation (one per system). To send the same metrics to several backends at once, Micrometer uses a CompositeMeterRegistry that holds child registries and forwards every meter operation to all of them.

Define a MeterRegistryCustomizer<MeterRegistry> bean that calls registry.config().commonTags("application", "my-app"). Those tags are then attached to every meter. In Spring Boot you can also set management.metrics.tags.* properties.

@Timed relies on a Spring AOP proxy that wraps the bean. Self-invocation (this.method()) calls the method directly on the target object, bypassing the proxy, so the TimedAspect never runs and no metric is recorded.

Cardinality is the number of distinct tag-value combinations, each of which is a separate time series. Putting unbounded values (user IDs, raw URLs, timestamps) in tags creates millions of series — OOM in the app and heavy load/cost in Prometheus. Prevent it with bounded tags, templated URIs, and MeterFilters that strip or cap tags.

@Timed records how long a method takes (a Timer metric); @Counted counts how many times it runs (a Counter). You put them on a method and Micrometer publishes the metric automatically, without writing timing code by hand.

Boot exposes jvm.memory.used/max/committed (tagged by area and pool), jvm.gc.pause and allocation counters, jvm.threads.live/daemon/peak, plus system.cpu.usage and process.cpu.usage, process.uptime and process.start.time. They come from Micrometer JVM/System binders.

A LongTaskTimer measures tasks that are still running. It reports how many are in flight and their current accumulated duration, updated while they run. A regular Timer only records after an operation finishes.

Use Timer.Sample when the start and stop of an operation are in different places (e.g. async callbacks) so you can't wrap them in one lambda. Call Timer.start(registry), carry the Sample, then sample.stop(timer) later.

longTask=true measures long-running, still-in-progress calls with a LongTaskTimer (active count + in-flight duration). percentiles computes client-side percentile values (e.g. p95, p99). histogram=true publishes bucket counts so backends like Prometheus can aggregate percentiles across instances.

When a DataSource bean exists Boot registers jdbc.connections.* pool metrics; if the pool is HikariCP it also exposes hikaricp.connections.active/idle/pending/max plus timing metrics. logback.events counts log lines per level via LogbackMetrics, so you can alert on error-log rate.

Micrometer keeps only a weak reference to the collection, so if you don't hold a strong reference it gets collected and the Gauge shows NaN. Also, if you replace the collection with a new instance, the Gauge still points at the old one, and re-registering a same-named Gauge is ignored.

Micrometer uses dot-separated names internally. The Prometheus registry rewrites them to snake_case and adds unit/_total suffixes (http_server_requests_seconds...), turning tags into labels. The OTLP registry keeps the dotted name (http.server.requests) per OpenTelemetry conventions.

Add micrometer-registry-otlp; Spring Boot auto-configures OtlpMeterRegistry. Set management.otlp.metrics.export.url to the collector (default http://localhost:4318/v1/metrics), tune step (interval), add auth via export.headers, and pick the aggregation-temporality. It pushes on each step.

In Spring Boot you customize registries with MeterRegistryCustomizer beans (e.g. add common tags) and shape/filter meters with MeterFilter. Boot applies customizers to each registry including the composite; a filter on the composite affects all children fan-out.

Metrics.globalRegistry is a static, application-wide CompositeMeterRegistry. It lets code without dependency injection record metrics. The pitfall in Spring: unless you wire the Boot registry into it, metrics recorded there aren't exported by Boot's own registry.

A MeterFilter runs at meter registration and can accept, deny, or transform meters. It has three hooks: accept() to include/exclude, map() to rename meters or add/rename/drop tags, and configure() to tune distribution stats. You register it via registry.config().meterFilter(...) or as a bean.

A DistributionSummary tracks the distribution of non-time measurements, like request payload sizes or items per batch. It records count, total, and max like a Timer but for arbitrary magnitudes instead of durations, via summary.record(value).

Built-in meters get tags from Observation conventions (server/client). To limit cardinality, ensure client calls use URI templates (not interpolated URLs), and add a MeterFilter to deny high-cardinality tags, cap max tag values, rename, or drop whole meters registry-wide.

Use a Counter for cumulative, only-up event totals. Use a bound Gauge when you already have a live object to read a current value from. Back a metric with an AtomicInteger/LongAdder + Gauge when the current value goes up and down but no natural object exposes it, so you maintain the number yourself.

Add both registry starters so Boot fans out via one CompositeMeterRegistry. Instrument once against the injected MeterRegistry. Apply per-child MeterFilters for cost/cardinality, tune each backend's step, and ensure push registries close on shutdown to flush.