Observability

Spring AI builds upon the observability features in the Spring ecosystem to provide insights into AI-related operations.

The spring-boot-actuator module is required for enabling observability. Add the Spring Boot Actuator dependency to your project’s Maven pom.xml build file:

<dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

or to your Gradle build.gradle build file.

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
}

Spring AI provides metrics and tracing capabilities for its core components: ChatClient (including Advisor), ChatModel, EmbeddingModel, ImageModel, and VectorStore.

1.0.0-RC1 Breaking Changes

Following configuration properties have been renamed to better reflect their purpose:

• spring.ai.chat.client.observations.include-prompt → spring.ai.chat.client.observations.log-prompt
• spring.ai.chat.observations.include-prompt → spring.ai.chat.observations.log-prompt
• spring.ai.chat.observations.include-completion → spring.ai.chat.observations.log-completion
• spring.ai.image.observations.include-prompt → spring.ai.image.observations.log-prompt
• spring.ai.vectorstore.observations.include-query-response → spring.ai.vectorstore.observations.log-query-response

Chat Client

The spring.ai.chat.client observations are recorded when a ChatClient call() or stream() operations are invoked. They measure the time spent performing the invocation and propagate the related tracing information.

Table 1. Low Cardinality Keys

Table 2. High Cardinality Keys

Prompt and Completion Data

The ChatClient prompt and completion data is typically big and possibly containing sensitive information. For those reasons, it is not exported by default.

Spring AI supports logging the prompt and completion data to help with debugging and troubleshooting.

Input Data (Deprecated)

The ChatClient input data is typically big and possibly containing sensitive information. For those reasons, it is not exported by default.

Spring AI supports logging input data to help with debugging and troubleshooting.

Chat Client Advisors

The spring.ai.advisor observations are recorded when an advisor is executed. They measure the time spent in the advisor (including the time spend on the inner advisors) and propagate the related tracing information.

Table 3. Low Cardinality Keys

Table 4. High Cardinality Keys

Chat Model

The gen_ai.client.operation observations are recorded when calling the ChatModel call or stream methods. They measure the time spent on method completion and propagate the related tracing information.

Table 5. Low Cardinality Keys

Table 6. High Cardinality Keys

Chat Prompt and Completion Data

The chat prompt and completion data is typically big and possibly containing sensitive information. For those reasons, it is not exported by default.

Spring AI supports logging chat prompt and completion data, useful for troubleshooting scenarios. When tracing is available, the logs will include trace information for better correlation.

Tool Calling

The spring.ai.tool observations are recorded when performing tool calling in the context of a chat model interaction. They measure the time spent on toll call completion and propagate the related tracing information.

Table 7. Low Cardinality Keys

Table 8. High Cardinality Keys

Tool Call Arguments and Result Data

The input arguments and result from the tool call are not exported by default, as they can be potentially sensitive.

Spring AI supports exporting tool call arguments and result data as span attributes.

EmbeddingModel

The gen_ai.client.operation observations are recorded on embedding model method calls. They measure the time spent on method completion and propagate the related tracing information.

Table 9. Low Cardinality Keys

Table 10. High Cardinality Keys

Image Model

The gen_ai.client.operation observations are recorded on image model method calls. They measure the time spent on method completion and propagate the related tracing information.

Table 11. Low Cardinality Keys

Table 12. High Cardinality Keys

Image Prompt Data

The image prompt data is typically big and possibly containing sensitive information. For those reasons, it is not exported by default.

Spring AI supports logging image prompt data, useful for troubleshooting scenarios. When tracing is available, the logs will include trace information for better correlation.

Vector Stores

All vector store implementations in Spring AI are instrumented to provide metrics and distributed tracing data through Micrometer.

The db.vector.client.operation observations are recorded when interacting with the Vector Store. They measure the time spent on the query, add and remove operations and propagate the related tracing information.

Table 13. Low Cardinality Keys

Table 14. High Cardinality Keys

Response Data

The vector search response data is typically big and possibly containing sensitive information. For those reasons, it is not exported by default.

Spring AI supports logging vector search response data, useful for troubleshooting scenarios. When tracing is available, the logs will include trace information for better correlation.

More Metrics Reference

This section documents the metrics emitted by Spring AI components as they appear in Prometheus.

Metric Naming Conventions

Spring AI uses Micrometer. Base metric names use dots (e.g., gen_ai.client.operation), which Prometheus exports with underscores and standard suffixes:

• Timers → <base>_seconds_count, <base>_seconds_sum, <base>_seconds_max, and (when supported) <base>_active_count
• Counters → <base>_total (monotonic)

The following shows how base metric names expand to Prometheus time series.

Base metric name Exported time series

gen_ai.client.operation

gen_ai_client_operation_seconds_count
gen_ai_client_operation_seconds_sum
gen_ai_client_operation_seconds_max
gen_ai_client_operation_active_count

db.vector.client.operation

db_vector_client_operation_seconds_count
db_vector_client_operation_seconds_sum
db_vector_client_operation_seconds_max
db_vector_client_operation_active_count

References

• OpenTelemetry — Semantic Conventions for Generative AI (overview)
• Micrometer — Naming Meters

Chat Client Metrics

Active vs Completed: active_count shows in-flight calls; the _seconds series reflect only completed calls.

Chat Model Metrics (Model provider execution)

Token Usage

Labels

Vector Store Metrics

Labels

Understanding Active vs Completed

• Active (*_active_count) — instantaneous gauge of in-progress operations (concurrency/load).
• Completed (*_seconds_sum|count|max) — statistics for operations that have finished:
• _seconds_sum / _seconds_count → average latency
• _seconds_max → high-water mark since last scrape (subject to registry behavior)