Spring AI Observability: 7 Built-in Observation Points, Micrometer Integration & OpenTelemetry Setup

1. Overview

Spring AI's observability architecture is built on Micrometer's Observation abstraction, introduced in Spring Boot 3 as a unified observability layer that handles both Metrics and Tracing, providing a more consistent developer experience than the traditional separated MeterRegistry + Tracer approach.

Spring AI instruments seven observation points:

CHAT_MODEL_OPERATION (module: model) — Observes model operations, recording full request/response lifecycle including parameters, results, and token usage.

EMBEDDING_MODEL_OPERATION (module: model) — Tracks embedding model requests, capturing vector dimensions and token consumption.

IMAGE_MODEL_OPERATION (module: model) — Records image generation parameters such as size, format, style, and token usage.

TOOL_CALL (module: model) — Traces function calls, capturing arguments, results, and tool definitions.

AI_VECTOR_STORE (module: vector-store) — Covers vector similarity searches, including query content, filters, and similarity thresholds; unified interface for all vector database implementations.

AI_CHAT_CLIENT (module: client-chat) — Observes ChatClient layer, logging configured advisors, conversation IDs, and streaming response flags.

AI_ADVISOR (module: client-chat) — Traces the advisor interceptor chain, recording order and names of interceptors for prompt rewriting, memory management, RAG, etc.

These observation points trigger automatically during corresponding business operations without manual annotation. For example, calling ChatClient.call() automatically triggers the CHAT_MODEL_OPERATION observation point, recording the complete request-response lifecycle.

2. Observation Four-Component Collaboration Pattern

Spring AI adopts Micrometer Observation's recommended four-component pattern for each observation point: ObservationDocumentation: Defines observation point and attribute names. ObservationConvention: Extracts tags from Context. Observation.Context: Carries runtime request/response data. ObservationHandler: Post-processing logic for the observation point.

Using CHAT_MODEL_OPERATION as an example, the Observation processing flow is:

ChatModelObservationDocumentation.CHAT_MODEL_OPERATION
 │
 ├─ observation(contextSupplier, registry) → create Observation
 │
 ├─ .observe(() -> bizLogic)
 │   │
 │   ├─ onStart() ──────────────► TracingAwareLoggingHandler
 │   │
 │   ├─ [business logic execution]
 │   │     │
 │   │     ├─ context.setResponse()  ← response data injection
 │   │     │
 │   │     └─ [may trigger onEvent() multiple times]
 │   │
 │   ├─ [Filter.map()] ─────────► ToolCallingContentObservationFilter
 │   │       (optionally modifies Context)
 │   │
 │   ├─ Convention.getContextualName()
 │   ├─ Convention.getLowCardinalityKeyValues()
 │   ├─ Convention.getHighCardinalityKeyValues()
 │   │
 │   ├─ onStop() ───────────────► ChatModelMeterObservationHandler
 │   │       (generates Meter metrics)
 │   │       ► ChatModelCompletionObservationHandler
 │   │             (logs completion content)
 │   │       ► ChatModelPromptContentObservationHandler
 │   │             (logs Prompt content)
 │   │
 │   └─ [possible exception]
 │         │
 │         └─ onError() ─────► ErrorLoggingObservationHandler
 │               (records error to Trace)
 │
 └─ return business result

Beyond built-in Metrics and Tracing, the flexible ObservationHandler callback mechanism enables non-invasive capabilities such as recording sensitive data, generating custom metrics, or integrating with external monitoring systems.

Custom ObservationHandler Example:

@Bean
public ObservationHandler<ChatModelObservationContext> myCustomHandler() {
    return new ObservationHandler<>() {
        @Override
        public void onStart(ChatModelObservationContext context) {
            // Record request start time, parameters, etc.
        }

        @Override
        public void onStop(ChatModelObservationContext context) {
            // Calculate latency, extract response results
            String modelName = context.getContextualName();
            // Custom logic: send to self-hosted monitoring system
        }

        @Override
        public boolean supportsContext(Context context) {
            return context instanceof ChatModelObservationContext;
        }
    };
}

3. OTel Integration

Observation's Tracer acts like slf4j and can bridge to OpenTelemetry via micrometer-tracing-bridge-otel.

Key components:

TracingObservationHandler (module: micrometer-tracing) — Bridge converting Observation → Span.

Tracer (interface) (module: micrometer-tracing) — Abstract tracing API.

OtelTracer (implementation) (module: micrometer-tracing-bridge-otel) — OpenTelemetry implementation, auto-activated via classpath detection.

OpenTelemetry SDK (module: opentelemetry-sdk) — Actual span processing and export.

OTLP Exporter (module: opentelemetry-exporter-otlp) — Exports to collector.

Thanks to Spring Boot auto-configuration, these components coordinate automatically after adding the bridge and exporter dependencies.

The integration flow:

OpenTelemetry SDK
micrometer-tracing-bridge-otel
Spring Boot
Your Application

Startup:
1. Discover OtelTracer implementation via META-INF/services
2. Register OtelTracer as Tracer Bean
3. ObservationAutoConfiguration registers TracingObservationHandler
4. Inject Tracer Bean into TracingObservationHandler

Runtime:
1. Spring AI calls ChatModel
2. ObservationRegistry.start(chatObservation)
3. Tracer.createSpan("chat")
4. OtelSDK.getTracer().spanBuilder("chat").startSpan()
5. Span wrapped in TracingContext
6. Observation lifecycle continues...
7. SpanProcessor.onEnd(span)
8. Export to OTLP Collector

Maven Dependencies:

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-tracing-bridge-otel</artifactId>
</dependency>
<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-exporter-otlp</artifactId>
</dependency>

Configuration Example (YAML):

spring:
  application:
    name: spring-ai-app
management:
  tracing:
    sampling:
      probability: 1.0  # full sampling
  otlp:
    tracing:
      endpoint: http://127.0.0.1:4318/v1/traces  # OTLP receiver address

After configuration, all Spring AI observation points automatically generate corresponding Trace Spans and export them to the configured OTLP collector.