En esta guía (19 elementos)

Observability — Metrics

Project-agnostic. Part of the Observability suite. Covers: dependency setup, Prometheus configuration, custom metrics via decorator pattern, metric naming conventions, tag conventions.

Replace com.example.platform / platform-service placeholders with your project’s actual package and service name when applying patterns.

Companion files:

observability.md — index + three-pillars overview.
obs-tracing.md — OTEL tracing + NewRelic.
obs-logging.md — structured logging.
obs-recipes.md — step-by-step + dashboards + alerting + checklist.

2. Dependency Setup

bootstrap/build.gradle.kts (already present)

These dependencies are already configured in the project:

1
dependencies {
2
    // Actuator for /actuator endpoints (health, metrics, prometheus)
3
    implementation("org.springframework.boot:spring-boot-starter-actuator")
4

5
    // Micrometer Tracing Bridge to OpenTelemetry
6
    implementation("io.micrometer:micrometer-tracing-bridge-otel")
7

8
    // OTEL Exporter for sending traces to an OTEL Collector
9
    implementation("io.opentelemetry:opentelemetry-exporter-otlp")
10
}

bootstrap/build.gradle.kts (add for Prometheus registry)

To expose metrics in Prometheus format at /actuator/prometheus, add the Prometheus registry:

1
dependencies {
2
    // Prometheus metrics registry -- exposes /actuator/prometheus endpoint
3
    implementation("io.micrometer:micrometer-registry-prometheus")
4
}

metrics-publisher/build.gradle.kts (already present)

The metrics-publisher infrastructure module already has:

1
dependencies {
2
    implementation(project(":application"))
3
    implementation(project(":domain"))
4

5
    implementation("org.springframework:spring-context")
6
    implementation("io.micrometer:micrometer-core")
7
}

No additional dependencies are needed for the metrics-publisher module. It uses micrometer-core for MeterRegistry, Timer, Counter, and Tag APIs.

3. Prometheus Configuration

application.yml (bootstrap module)

Add the prometheus endpoint to the management section and enable the Prometheus registry:

1
management:
2
  endpoints:
3
    web:
4
      exposure:
5
        include: health,info,loggers,metrics,env,threaddump,heapdump,beans,mappings,prometheus
6
  endpoint:
7
    health:
8
      show-details: ${MANAGEMENT_HEALTH_SHOW_DETAILS:always}
9
    prometheus:
10
      enabled: true
11
  prometheus:
12
    metrics:
13
      export:
14
        enabled: true
15
  info:
16
    env:
17
      enabled: true
18
  metrics:
19
    distribution:
20
      percentiles-histogram:
21
        usecase.operation: true
22
      percentiles:
23
        usecase.operation: 0.5,0.95,0.99
24
    tags:
25
      application: ${spring.application.name}
26
      environment: ${SPRING_PROFILES_ACTIVE:local}
27
  tracing:
28
    enabled: ${MANAGEMENT_TRACING_ENABLED:true}
29
    sampling:
30
      probability: ${MANAGEMENT_TRACING_SAMPLING_PROBABILITY:1.0}

Actuator Endpoints

Endpoint	Purpose
`/actuator/prometheus`	Metrics in Prometheus exposition format
`/actuator/metrics`	JSON list of all registered meter names
`/actuator/metrics/{name}`	Detailed view of a specific metric
`/actuator/health`	Application health status and component checks
`/actuator/info`	Application info (version, build, environment)

Custom Metrics Flow

Custom metrics are registered automatically by MetricRecorded subclasses through the decorator pattern. When a use case executes, the chain invokes the metrics adapter first, which records timers and counters before delegating to the next link in the chain. These metrics appear automatically at /actuator/prometheus.

4. Custom Metrics with Decorator Pattern

The MetricRecorded Abstract Class

All metrics adapters extend the MetricRecorded abstract class, which lives in:

1
infrastructure/driven-adapters/metrics-publisher/
2
  src/main/kotlin/.../metrics/support/MetricRecorded.kt

This class provides the record() method that wraps any operation with:

A Timer to measure duration (usecase.operation)
A success/failure Counter (usecase.operation.calls with success tag)
An error Counter (usecase.operation.errors)

All adapters inherit Ordered with a default order of 10, placing them at the highest priority in the chain (executed first).

Kotlin Example: CreateUserMetricsAdapter

This is the actual pattern used in the project:

1
package com.example.platform.infrastructure.driven.adapters.metrics
2

3
import com.example.platform.domain.User
4
import com.example.platform.infrastructure.driven.adapters.metrics.support.MetricRecorded
5
import com.example.platform.port.inbound.CreateUserPort
6
import com.example.platform.usecase.user.command.CreateUserCommand
7
import io.micrometer.core.instrument.MeterRegistry
8
import org.springframework.stereotype.Component
9

10
@Component
11
class CreateUserMetricsAdapter(
12
    meterRegistry: MeterRegistry,
13
) : MetricRecorded(meterRegistry),
14
    CreateUserPort {
15

16
    private lateinit var delegate: CreateUserPort
17

18
    override fun execute(command: CreateUserCommand): User =
19
        record("user", "create_user") { delegate.execute(command) }
20

21
    override fun setDelegate(delegate: CreateUserPort) {
22
        this.delegate = delegate
23
    }
24
}

Key characteristics:

Annotated with @Component (Spring-managed bean).
Inherits order 10 from MetricRecorded (no explicit @Order needed).
Implements the same port interface (CreateUserPort) as the use case.
Delegates to the next link in the chain via delegate.execute(command).
Wraps the delegation call with record(entity, operation) { ... }.
The setDelegate() method is called by UseCaseConfig.buildChain() at startup.

Java Equivalent: CreateUserMetricsAdapter

1
package com.example.platform.infrastructure.driven.adapters.metrics;
2

3
import com.example.platform.domain.User;
4
import com.example.platform.infrastructure.driven.adapters.metrics.support.MetricRecorded;
5
import com.example.platform.port.inbound.CreateUserPort;
6
import com.example.platform.usecase.user.command.CreateUserCommand;
7
import io.micrometer.core.instrument.MeterRegistry;
8
import org.springframework.stereotype.Component;
9

10
@Component
11
public class CreateUserMetricsAdapter extends MetricRecorded implements CreateUserPort {
12

13
    private CreateUserPort delegate;
14

15
    public CreateUserMetricsAdapter(MeterRegistry meterRegistry) {
16
        super(meterRegistry);
17
    }
18

19
    public void setDelegate(CreateUserPort delegate) {
20
        this.delegate = delegate;
21
    }
22

23
    @Override
24
    public User execute(CreateUserCommand command) {
25
        return record("user", "create_user", () -> delegate.execute(command));
26
    }
27
}

Note: The Java version of MetricRecorded.record() would accept a Supplier<T> instead of a Kotlin lambda () -> T:

1
// Java-compatible MetricRecorded.record() signature
2
protected <T> T record(String entity, String operation, Supplier<T> execute) {
3
    // ... same timing and counting logic
4
}

5. Metric Naming Conventions

Timer Naming Pattern

1
usecase.operation

All use case timers share the same base metric name usecase.operation and are differentiated by tags.

Tag Conventions

Tag	Description	Examples
`entity`	The domain entity being operated on	`user`, `organization`, `workflow`
`operation`	The specific operation being performed	`create_user`, `enable_user`, `create_organization`
`success`	Whether the operation succeeded	`true`, `false`
`error`	Exception class name (on errors only)	`UserNotFoundException`, `TimeoutException`

Metric Types and Names

Timers (duration of use case execution):

Metric Name	Tags	Description
`usecase.operation`	entity, operation	Duration histogram for each use case

Counters (call and error counts):

Metric Name	Tags	Description
`usecase.operation.calls`	entity, operation, success	Total calls with success/failure tag
`usecase.operation.errors`	entity, operation	Total error count per use case

Prometheus Output Examples

After Prometheus scraping, the metrics appear as:

1
# Timer (histogram buckets)
2
usecase_operation_seconds_bucket{entity="user",operation="create_user",le="0.001"} 5
3
usecase_operation_seconds_bucket{entity="user",operation="create_user",le="0.01"} 42
4
usecase_operation_seconds_count{entity="user",operation="create_user"} 100
5
usecase_operation_seconds_sum{entity="user",operation="create_user"} 1.234
6

7
# Counters
8
usecase_operation_calls_total{entity="user",operation="create_user",success="true"} 95
9
usecase_operation_calls_total{entity="user",operation="create_user",success="false"} 5
10
usecase_operation_errors_total{entity="user",operation="create_user"} 5

Gauges (for stateful metrics)

Use gauges for values that go up and down (active connections, queue size):

1
// Kotlin
2
meterRegistry.gauge("repository.connection.pool.active", dataSource, { it.activeConnections.toDouble() })
3

4
// Java
5
meterRegistry.gauge("repository.connection.pool.active", dataSource, ds -> (double) ds.getActiveConnections());

Naming Rules Summary

Use lowercase with dots as separators: usecase.operation.
Use underscores within tag values: create_user, enable_user.
Prefix with the layer: usecase.* for use cases, repository.* for repositories.
Always include entity and operation tags for filtering.
Never include high-cardinality values (IDs, emails) as tags — they will explode your metrics storage.