Micrometer Skill

Quick Start

Add metrics to a Spring Boot service in 2 minutes:

@Service
public class ChargeProcessingService {

    private final Counter chargesProcessed;
    private final Timer processingTimer;

    public ChargeProcessingService(MeterRegistry registry) {
        // Counter - monotonically increasing
        this.chargesProcessed = Counter.builder("charge.processed")
            .tag("type", "supplier")
            .register(registry);

        // Timer - measures duration and frequency
        this.processingTimer = Timer.builder("charge.processing.duration")
            .serviceLevelObjectives(
                Duration.ofMillis(100),
                Duration.ofMillis(500),
                Duration.ofSeconds(1)
            )
            .register(registry);
    }

    public void processCharge(Charge charge) {
        Timer.Sample sample = Timer.start();

        try {
            // Process charge...
            chargesProcessed.increment();
        } finally {
            sample.stop(processingTimer);
        }
    }
}

Expose metrics:

# View all metrics
curl http://localhost:8080/actuator/metrics

# View specific metric
curl http://localhost:8080/actuator/metrics/charge.processed

# Prometheus scrape endpoint (add micrometer-registry-prometheus)
curl http://localhost:8080/actuator/prometheus

Table of Contents

1. When to Use
2. Setup
3. Meter Types
4. Tags and Cardinality
5. Common Patterns
6. Supporting Files
7. Requirements

When to Use

Use this skill when you need to:

• Add metrics to microservices (counters, timers, gauges, distributions)
• Integrate with monitoring systems (Prometheus, GCP Cloud Monitoring, Datadog)
• Implement dimensional metrics with tags for filtering
• Configure Spring Boot Actuator auto-metrics
• Create custom application-specific measurements

When NOT to use:

• For initial Micrometer setup (use python-micrometer-metrics-setup)
• For business KPI metrics (use python-micrometer-business-metrics)
• For cardinality management (use python-micrometer-cardinality-control)
• For GCP export (use python-micrometer-gcp-cloud-monitoring)

Setup

Dependencies

dependencies {
    // Spring Boot Actuator (includes Micrometer)
    implementation("org.springframework.boot:spring-boot-starter-actuator")

    // Backend registries
    implementation("io.micrometer:micrometer-registry-prometheus")  // Prometheus
    implementation("io.micrometer:micrometer-registry-stackdriver")  // GCP
}

Configuration

# application.yml
management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus

  metrics:
    enable:
      jvm: true
      process: true
      system: true

    distribution:
      percentiles-histogram:
        http.server.requests: true  # Create histogram buckets

      slo:
        http.server.requests: 10ms,50ms,100ms,500ms,1s  # SLO thresholds

    tags:
      application: ${spring.application.name}
      environment: ${ENVIRONMENT:local}

Meter Types

Counter – Monotonically Increasing

Counter counter = Counter.builder("api.requests")
    .tag("endpoint", "/charges")
    .register(registry);

counter.increment();    // +1
counter.increment(5);   // +5

Gauge – Point-in-Time Value

// Function-based (recommended)
Gauge.builder("queue.size", queue, Queue::size)
    .register(registry);

Timer – Duration and Frequency

Timer timer = Timer.builder("database.query")
    .register(registry);

timer.record(() -> {
    // database operation
});

// Or with Sample
Timer.Sample sample = Timer.start(registry);
// ... perform operation
sample.stop(Timer.builder("api.latency").register(registry));

DistributionSummary – Non-Time Distributions

DistributionSummary summary = DistributionSummary.builder("request.size")
    .baseUnit("bytes")
    .register(registry);

summary.record(fileSize);

See references/meter-types-reference.md for comprehensive meter type guide and decision trees.

Tags and Cardinality

Safe Tags (Bounded, Low Cardinality)

// ✅ HTTP method (4-10 values)
.tag("method", "GET")

// ✅ Status class (5 values)
.tag("status.class", "2xx")

// ✅ Environment (3-5 values)
.tag("env", "production")

Dangerous Tags (Unbounded, High Cardinality)

// ❌ User ID (millions of values) → Use tracing instead
.tag("user.id", userId)

// ❌ Request ID (infinite values) → Use tracing instead
.tag("request.id", requestId)

// ❌ Full URI with parameters → Normalize!
.tag("uri", "/api/charges?supplier=123&date=2025-01-01")

Cardinality Limits

@Bean
public MeterFilter cardinalityLimiter() {
    // Limit unique URIs to 100
    return MeterFilter.maximumAllowableTags(
        "http.requests",
        "uri",
        100,
        MeterFilter.deny()  // Deny new meters after limit
    );
}

See python-micrometer-cardinality-control for comprehensive cardinality management.

Common Patterns

Service Metrics

@Service
public class OrderService {

    private final Counter ordersCreated;
    private final Timer orderLookup;

    public OrderService(MeterRegistry registry) {
        this.ordersCreated = Counter.builder("order.created")
            .description("Orders created")
            .register(registry);

        this.orderLookup = Timer.builder("order.lookup.duration")
            .description("Time to lookup order")
            .register(registry);
    }

    public Order createOrder(OrderRequest request) {
        Timer.Sample sample = Timer.start();
        try {
            Order order = new Order(request);
            ordersCreated.increment();
            return order;
        } finally {
            sample.stop(orderLookup);
        }
    }
}

@Timed Annotation

@Configuration
public class MetricsConfig {
    @Bean
    public TimedAspect timedAspect(MeterRegistry registry) {
        return new TimedAspect(registry);
    }
}

@Service
public class InvoiceService {

    @Timed(
        value = "invoice.generation",
        description = "Time to generate invoice",
        percentiles = {0.95, 0.99}
    )
    public Invoice generateInvoice(String supplierId) {
        // Implementation
        return invoice;
    }
}

Common Tags Organization-Wide

@Configuration
public class MetricsConfig {

    @Bean
    public MeterRegistryCustomizer<MeterRegistry> commonTags(
            @Value("${spring.application.name}") String appName,
            @Value("${environment}") String environment) {

        return registry -> registry.config()
            .commonTags(
                "application", appName,
                "environment", environment,
                "region", "europe-west2"
            );
    }
}

Supporting Files

Requirements

• Spring Boot 2.2+ (Micrometer included)
• Micrometer core library (auto-included with Actuator)
• JVM application with Spring Boot
• Monitoring system backend (Prometheus, Cloud Monitoring)

Dependencies:

implementation("org.springframework.boot:spring-boot-starter-actuator")
implementation("io.micrometer:micrometer-registry-prometheus")  // Choose backend

See Also

• python-micrometer-cardinality-control – High cardinality prevention
• python-micrometer-business-metrics – Business KPIs
• python-micrometer-gcp-cloud-monitoring – GCP export
• python-micrometer-metrics-setup – Initial setup