DOCSEARCHbyAlgolia
Submit Docs

Micrometer Documentation

repository·main·Indexed 26 days ago

https://github.com/micrometer-metrics/micrometer

A dimensional metrics facade for JVM-based applications that provides a vendor-neutral API to instrument code for various monitoring backends. It includes support for Counters, Gauges, DistributionSummaries, and an Observation API for unified metrics and tracing. Compatible with Java 8 or later.

Tokens
48.6K
Snippets
137
Records
252
Agent score
89%

What's inside Micrometer

  1. Overview of Micrometer Application Metrics

    main
    Micrometer is an application metrics facade designed for popular monitoring tools. It allows you to instrument your code using dimensional metrics through a vendor-neutral interface, enabling you to choose or change your monitoring backend without modifying your application code. Micrometer artifacts are compatible with Java 8 or later (with specific exceptions like micrometer-java11 and micrometer-jetty11).

  2. Overview of Micrometer Purpose and Capabilities

    main

    Micrometer is a metrics instrumentation library for JVM-based applications. It acts as a facade over various monitoring system clients, allowing you to instrument application code without vendor lock-in. It is designed for low overhead and high portability.

    Key features include:

    • Metrics Instrumentation: A vendor-neutral API for collecting application metrics.
    • Observation API: Introduced in Micrometer 1.10, this API provides a unified way to handle both metrics and tracing via a plugin mechanism.
    • Tracing Support: Through the Observation API, Micrometer can integrate with tracing features (refer to the Micrometer Tracing documentation for details).

  3. Overview of Micrometer Application Metrics

    main

    Micrometer is a vendor-neutral observability facade for JVM-based applications, similar to how SLF4J works for logging. It allows you to instrument your application code using a consistent API while decoupling your code from specific observability backends.

    Key features include:

    • Dimensional Metrics: Provides interfaces for Timer, Gauge, Counter, DistributionSummary, and LongTaskTimer using a dimensional data model for efficient drilling down into metrics.
    • Pre-configured Bindings: Offers out-of-the-box instrumentation for system components like caches, class loaders, garbage collection, processor utilization, and thread pools.
    • Spring Integration: Serves as the primary instrumentation library for Spring Boot applications.
    • Extensive Backend Support: Built-in support for numerous observability systems including Prometheus, Datadog, New Relic, OpenTelemetry Protocol (OTLP), Azure Monitor, CloudWatch, and many others.

  4. Identify existing Micrometer Observation instrumentations

    main

    Micrometer Observation is used to instrument a wide variety of external projects, allowing developers to "instrument once and have multiple benefits out of it." Many popular libraries and frameworks already provide built-in support for Micrometer Observation.

    Commonly instrumented projects include:

    • Web & HTTP: Apache HttpComponents, Jetty, Jersey, OkHttp, Spring MVC, Spring WebFlux, JDK Http Client.
    • Messaging & Streaming: RabbitMQ, RabbitMQ Stream, Spring Kafka, Spring AMQP, JMS, RSocket.
    • Databases & Persistence: JDBC, R2DBC, Lettuce (Redis), Spring Data Cassandra, Spring Data MongoDB, Spring Data Redis, Couchbase.
    • Frameworks & Runtimes: Apache Camel, Apache Dubbo, Micronaut, Spring Cloud (Gateway, Config, Function, etc.), Spring Modulith, Reactor, Kotlin Coroutines.
    • Resilience & RPC: Resilience4j, gRPC, OpenFeign, Retrofit.

    If your project uses one of these technologies, check the official Micrometer documentation or the specific project's integration guide to see how to enable observation.

  5. Understand Micrometer Observation lifecycle and components

    main

    Micrometer Observation is a mechanism for instrumenting code with metadata that can be used for metrics, tracing, and logging. An Observation lifecycle is managed by ObservationHandler objects registered in an ObservationRegistry.

    Lifecycle Events

    Handlers react to the following events:

    • start: Triggered by Observation#start().
    • stop: Triggered by Observation#stop().
    • error: Triggered by Observation#error(exception).
    • event: Triggered by Observation#event(event).
    • scope started: Triggered by Observation#openScope().
    • scope stopped: Triggered by Observation.Scope#close().

    Core Components

    • ObservationRegistry: The central registry containing configuration like handlers, predicates, and filters.
    • ObservationHandler: Reacts to lifecycle events (e.g., creating a timer when an observation starts).
    • ObservationFilter: Mutates the Observation.Context before the observation stops (e.g., adding high-cardinality tags).
    • ObservationPredicate: Determines if an observation should be created at all.
    • Observation.Context: A mutable map attached to an observation used to pass state between handlers.
    • ObservationConvention: Separates lifecycle logic from metadata configuration (naming and tags).

  6. Use HighCardinalityTagsDetector to identify problematic tags

    main

    The HighCardinalityTagsDetector monitors your MeterRegistry to identify Meters that likely have high cardinality tags. It works by counting how many Meters share the same name; if this count exceeds a configurable threshold, it triggers a notification (via logging or a custom consumer).

    Note: The detector specifically identifies potential high cardinality tags by counting Meters with the same name. It does not detect random values appended to Meter names or other memory leaks.

  7. Understand Dimensionality in Monitoring Systems

    main

    Micrometer supports both Dimensional and Hierarchical monitoring systems.

    • Dimensional systems allow metric names to be enriched with tag key/value pairs.
    • Hierarchical systems only support flat metric names.

    When using a hierarchical system, Micrometer automatically flattens the tag key/value pairs and appends them to the metric name to ensure compatibility.

  8. Understand Micrometer Meter types and identification

    main

    A Meter is the primary interface for collecting measurements (metrics) about an application.

    Supported Meter Primitives

    Micrometer provides several meter types, each producing different numbers of time series metrics:

    • Timer: Measures both the count of timed events and the total time of all timed events.
    • Counter
    • Gauge
    • DistributionSummary
    • LongTaskTimer
    • FunctionCounter
    • FunctionTimer
    • TimeGauge

    Identification via Name and Dimensions

    Each meter is uniquely identified by its name and its dimensions (also referred to as tags).

    • Name: Should be used as a pivot point for your data.
    • Dimensions/Tags: Used to slice a named metric to allow for drilling down into specific data subsets. If you select only the metric name, you should be able to use dimensions to reason about the specific values being shown.

  9. Understand Rate Aggregation Strategies

    main

    Micrometer handles rate aggregation differently depending on whether the target monitoring system performs math on the server or expects pre-aggregated data from the client.

    Server-side Aggregation

    Monitoring systems like Prometheus expect absolute values (e.g., the total count of increments since application start) to be reported at each publishing interval. The monitoring system then performs the rate math (e.g., rate() in PromQL) during the query.

    Best Practice: For production automation, alerting, or canary analysis, always base your logic on rate-aggregated data rather than raw absolute counter values to avoid issues with service restarts or deployment dips.

    Client-side Aggregation

    Some monitoring systems either require pre-aggregated data or lack the mathematical capabilities to calculate rates from absolute values. In these cases, Micrometer performs the aggregation locally before publishing.

    Micrometer uses a "step value" mechanism to maintain this data. It accumulates data for the current interval and, once the interval elapses, moves the data to a previous state. This previous state is what is reported to the backend until the next interval is completed. The value reported is always rate per second * interval.

  10. Understand the Micrometer Observation flow

    main

    Micrometer Observation follows a specific lifecycle. An Observation is created via an ObservationRegistry using a mutable Observation.Context.

    Detailed Flow:

    1. Creation: ObservationRegistry creates an Observation with an Observation.Context. An ObservationConvention is used to customize the name and key-value pairs.
    2. Validation: An ObservationPredicate determines if the observation should be fully created or a no-op version.
    3. Lifecycle: As lifecycle actions occur (e.g., start()), the corresponding ObservationHandler methods (e.g., onStart) are called with the Observation.Context.
    4. Termination: Upon stop(), a list of ObservationFilter instances is called to optionally modify the Observation.Context before the ObservationHandler.onStop methods are executed.