Metrics with Micrometer

Micrometer is to metrics what SLF4J is to logging: a vendor-neutral facade you code against once, with pluggable backends (Prometheus, Datadog, CloudWatch...) chosen by a dependency. Spring Boot auto-configures it, so BookVault already emits dozens of metrics. This lesson is about instrumenting your own - picking the right meter type and, above all, tagging without blowing up your metrics backend.

The meter types

Micrometer offers a few meter types, and choosing the right one is most of the skill:

• Counter - a value that only ever increases: books borrowed, requests served, errors. You ask questions about its rate ("borrows per second"), not its raw total.
• Gauge - a value that goes up and down, sampled now: active loans, queue depth, cache size. A gauge observes a live value; you don't set it, you point it at something to read.
• Timer - records how long things take and how often: it captures count, total time, and max, and (configured) latency percentiles. The workhorse for request/operation latency.
• Distribution Summary - like a timer but for non-time distributions: payload sizes, batch counts.

@Component
class LoanMetrics {
    private final Counter borrows;
    private final Timer checkoutTimer;

    LoanMetrics(MeterRegistry registry) {
        this.borrows = Counter.builder("bookvault.loans.borrowed")
            .description("Total books borrowed").register(registry);
        this.checkoutTimer = Timer.builder("bookvault.checkout.duration")
            .publishPercentiles(0.95, 0.99).register(registry);
        // a gauge observes a live value - here, the current active-loan count
        Gauge.builder("bookvault.loans.active", loanService, LoanService::activeCount)
            .register(registry);
    }

    void recordBorrow() { borrows.increment(); }
    <T> T timeCheckout(Supplier<T> op) { return checkoutTimer.record(op); }
}

Tags: the dimensional model - and the cardinality trap

Modern metrics are dimensional: one metric name with tags (key-value labels) you slice by. Instead of borrows_fiction, borrows_scifi, you record one bookvault.loans.borrowed with a genre tag and query sum by (genre):

Counter.builder("bookvault.loans.borrowed")
    .tag("genre", book.genre())          // good: bounded set of values
    .tag("branch", book.branch())        // good: dozens of branches
    .register(registry).increment();

This is powerful - but tags are also the single biggest way to melt a metrics system. Every unique combination of tag values creates a separate stored time series. That's cardinality, and it multiplies:

genre (12) × branch (30) = 360 series      ✅  fine
+ member_id (500,000)     = 180,000,000 series  💥  catastrophe

What you already get free

Before writing custom meters, know Spring Boot auto-instruments a lot: http.server.requests (a Timer tagged by URI, method, status - your latency and error rate), JVM memory and GC, thread pools, DataSource connections, and cache stats. Export them to Prometheus by adding micrometer-registry-prometheus, which exposes /actuator/prometheus for Prometheus to scrape. Add custom meters only for business signals (borrows, checkout duration) the framework can't know about.