主题
可观测性
Spring AI 建立在 Spring 生态的可观测性能力之上，为 AI 相关操作提供洞察。它为核心组件提供指标与链路追踪能力：ChatClient（含 Advisor）、ChatModel、EmbeddingModel、ImageModel 和 VectorStore。
参阅 Spring Boot Metrics 和 Spring Boot Tracing 文档，在你的应用中启用指标与追踪支持。
NOTE
低基数（Low-cardinality）键会被添加到指标和追踪中，而高基数（High-cardinality）键只会添加到追踪中。
Chat Client
当 ChatClient 的 call() 或 stream() 操作被调用时，会记录 spring.ai.chat.client 观测。它们度量执行该调用所花的时间，并传播相关的追踪信息。
.低基数键
| 名称 | 描述 |
|---|---|
gen_ai.operation.name | 恒为 framework。 |
gen_ai.system | 恒为 spring_ai。 |
spring.ai.chat.client.stream | 聊天模型的响应是否为流式 - true 或 false |
spring.ai.kind | Spring AI 中框架 API 的类别：chat_client。 |
.高基数键
| 名称 | 描述 |
|---|---|
spring.ai.chat.client.advisors | 已配置的聊天客户端顾问列表。 |
spring.ai.chat.client.conversation.id | 使用聊天记忆时的对话标识符。 |
spring.ai.chat.client.tool.names | 传给聊天客户端的工具名称。 |
提示词与补全数据
ChatClient 的提示词与补全数据通常很大，且可能包含敏感信息。 出于这些原因，默认不导出。
Spring AI 支持记录提示词与补全数据，以辅助调试与排障。
| 属性 | 描述 | 默认值 |
|---|---|---|
spring.ai.chat.client.observations.log-prompt | 是否记录聊天客户端的提示词内容。 | false |
spring.ai.chat.client.observations.log-completion | 是否记录聊天客户端的补全内容。 | false |
DANGER
如果你启用对聊天客户端提示词与补全数据的记录，存在泄露敏感或私密信息的风险。请务必小心！
聊天客户端顾问
当某个顾问被执行时会记录 spring.ai.advisor 观测。它们度量在该顾问内部所花的时间（含内层顾问的时间），并传播相关的追踪信息。
.低基数键
| 名称 | 描述 |
|---|---|
gen_ai.operation.name | 恒为 framework。 |
gen_ai.system | 恒为 spring_ai。 |
spring.ai.advisor.name | 顾问的名称。 |
spring.ai.kind | Spring AI 中框架 API 的类别：advisor。 |
.高基数键
| 名称 | 描述 |
|---|---|
spring.ai.advisor.order | 顾问在顾问链中的顺序。 |
Chat Model
NOTE
OpenAI 和 Anthropic 聊天模型都会发出 HTTP 层的观测（chat-model 层 + HTTP 层），仅有一项流式调用特有的限制。 HTTP 层观测携带 HTTP 方法、URI、状态码，并在线路上向下游服务（AI 网关、代理、OpenAI 兼容推理服务器）传播 traceparent。
对于同步调用，okhttp.requests span 会正确地嵌套在 gen_ai.client.operation span 之下。 对于流式调用，HTTP span 会被记录，但不会作为 chat-model span 的子级——SDK 的异步流式路径在调用 Spring AI 的 HTTP 客户端前会跳到 ForkJoinPool.commonPool()，从而在该边界丢弃调用线程的观测上下文。
细节参见 OpenAI 聊天文档 和 Anthropic 聊天文档。
调用 ChatModel 的 call 或 stream 方法时会记录 gen_ai.client.operation 观测。它们度量方法完成所花的时间，并传播相关的追踪信息。
WARNING
gen_ai.client.token.usage 指标度量的是单次模型调用所使用的输入与输出令牌数。
.低基数键
| 名称 | 描述 |
|---|---|
gen_ai.operation.name | 正在执行的操作名称。 |
gen_ai.system | 由客户端插桩识别的模型服务商。 |
gen_ai.request.model | 正在向其发起请求的模型名称。 |
gen_ai.response.model | 生成该响应的模型名称。 |
.高基数键
| 名称 | 描述 |
|---|---|
gen_ai.request.frequency_penalty | 模型请求的频率惩罚设置。 |
gen_ai.request.max_tokens | 模型为一次请求生成的最大令牌数。 |
gen_ai.request.presence_penalty | 模型请求的存在惩罚设置。 |
gen_ai.request.stop_sequences | 模型用于停止进一步生成令牌的序列列表。 |
gen_ai.request.stream | 请求是否以流式模式发起。仅在为 true 时出现。 |
gen_ai.request.temperature | 模型请求的温度设置。 |
gen_ai.request.top_k | 模型请求的 top_k 采样设置。 |
gen_ai.request.top_p | 模型请求的 top_p 采样设置。 |
gen_ai.response.finish_reasons | 模型停止生成令牌的原因，对应于收到的每次生成。 |
gen_ai.response.id | AI 响应的唯一标识符。 |
gen_ai.usage.cache_creation.input_tokens | 写入服务商托管缓存的输入令牌数。 |
gen_ai.usage.cache_read.input_tokens | 由服务商托管缓存命中的输入令牌数。 |
gen_ai.usage.input_tokens | 模型输入（提示词）中使用的令牌数。 |
gen_ai.usage.output_tokens | 模型输出（补全）中使用的令牌数。 |
gen_ai.usage.total_tokens | 该模型交互中使用的令牌总数。 |
spring.ai.model.request.tool.names | 请求中提供给模型的工具定义列表。 |
NOTE
对于度量用户令牌，上表列出了观测追踪中呈现的值。
使用由 ChatModel 提供的指标名 gen_ai.client.token.usage。
聊天提示词与补全数据
聊天提示词与补全数据通常很大，且可能包含敏感信息。 出于这些原因，默认不导出。
Spring AI 支持记录聊天提示词与补全数据，适用于排障场景。当有追踪可用时，日志会包含追踪信息以便更好的关联。
| 属性 | 描述 | 默认值 |
|---|---|---|
spring.ai.chat.observations.log-prompt | 记录提示词内容。true 或 false | false |
spring.ai.chat.observations.log-completion | 记录补全内容。true 或 false | false |
spring.ai.chat.observations.include-error-logging | 在观测中包含错误日志。true 或 false | false |
DANGER
如果你启用对聊天提示词与补全数据的记录，存在泄露敏感或私密信息的风险。请务必小心！
工具调用
在聊天模型交互的上下文中执行工具调用时，会记录 spring.ai.tool 观测。它们度量工具调用完成所花的时间，并传播相关的追踪信息。
.低基数键
| 名称 | 描述 |
|---|---|
gen_ai.operation.name | 正在执行的操作名称。恒为 execute_tool。 |
gen_ai.system | 负责该操作的服务商。恒为 spring_ai。 |
spring.ai.kind | Spring AI 所执行操作的类别。恒为 tool_call。 |
spring.ai.tool.definition.name | 工具的名称。 |
spring.ai.tool.type | 工具的类型。默认为 function。 |
.高基数键
| 名称 | 描述 |
|---|---|
spring.ai.tool.definition.description | 工具的描述。 |
spring.ai.tool.definition.schema | 用于调用工具的参数模式。 |
spring.ai.tool.call.id | 由聊天模型标识的工具调用 ID。 |
spring.ai.tool.call.arguments | 工具调用的输入参数。（仅在启用时） |
spring.ai.tool.call.result | 工具调用执行的结果。（仅在启用时） |
工具调用参数与结果数据
工具调用的输入参数与结果默认不导出，因为它们可能涉及敏感信息。
Spring AI 支持把工具调用的参数与结果数据作为 span 属性导出。
| 属性 | 描述 | 默认值 |
|---|---|---|
spring.ai.tools.observations.include-content | 在观测中包含工具调用内容。true 或 false | false |
DANGER
如果你启用在观测中包含工具调用的参数与结果，存在泄露敏感或私密信息的风险。请务必小心！
EmbeddingModel
NOTE
可观测性特性目前仅对以下
AI 模型服务商的 EmbeddingModel 实现提供支持：Mistral AI、Ollama 和 OpenAI。 更多 AI 模型服务商将在未来版本中获得支持。
在嵌入模型方法调用时会记录 gen_ai.client.operation 观测。 它们度量方法完成所花的时间，并传播相关的追踪信息。
WARNING
gen_ai.client.token.usage 指标度量的是单次模型调用所使用的输入与输出令牌数。
.低基数键
| 名称 | 描述 |
|---|---|
gen_ai.operation.name | 正在执行的操作名称。 |
gen_ai.system | 由客户端插桩识别的模型服务商。 |
gen_ai.request.model | 正在向其发起请求的模型名称。 |
gen_ai.response.model | 生成该响应的模型名称。 |
.高基数键
| 名称 | 描述 |
|---|---|
gen_ai.request.embedding.dimensions | 所生成输出嵌入具有的维度数。 |
gen_ai.usage.input_tokens | 模型输入中使用的令牌数。 |
gen_ai.usage.total_tokens | 该模型交互中使用的令牌总数。 |
NOTE
对于度量用户令牌，上表列出了观测追踪中呈现的值。
使用由 EmbeddingModel 提供的指标名 gen_ai.client.token.usage。
Image Model
NOTE
可观测性特性目前仅对以下 AI 模型服务商的 ImageModel 实现提供支持：OpenAI。更多 AI 模型服务商将在未来版本中获得支持。
在图像模型方法调用时会记录 gen_ai.client.operation 观测。 它们度量方法完成所花的时间，并传播相关的追踪信息。
.低基数键
| 名称 | 描述 |
|---|---|
gen_ai.operation.name | 正在执行的操作名称。 |
gen_ai.system | 由客户端插桩识别的模型服务商。 |
gen_ai.request.model | 正在向其发起请求的模型名称。 |
.高基数键
| 名称 | 描述 |
|---|---|
gen_ai.request.image.response_format | 返回生成图像所用的格式。 |
gen_ai.request.image.size | 要生成图像的尺寸（例如 1024x1024）。 |
gen_ai.request.image.style | 要生成图像的风格。 |
图像提示词数据
图像提示词数据通常很大，且可能包含敏感信息。 出于这些原因，默认不导出。
Spring AI 支持记录图像提示词数据，适用于排障场景。当有追踪可用时，日志会包含追踪信息以便更好的关联。
| 属性 | 描述 | 默认值 |
|---|---|---|
spring.ai.image.observations.log-prompt | 记录图像提示词内容。true 或 false | false |
DANGER
如果你启用对图像提示词数据的记录，存在泄露敏感或私密信息的风险。请务必小心！
向量库
Spring AI 中所有的向量库实现都经过插桩，以通过 Micrometer 提供指标与分布式追踪数据。
与向量库交互时会记录 db.vector.client.operation 观测。 它们度量 query、add、upsert 和 delete 操作所花的时间，并传播相关的追踪信息。
.低基数键
| 名称 | 描述 |
|---|---|
db.operation.name | 正在执行的操作或命令名称。取值为 add、upsert、delete 或 query 之一。 |
db.system | 由客户端插桩识别的数据库管理系统（DBMS）产品。取值为 pg_vector、azure、cassandra、chroma、elasticsearch、milvus、neo4j、opensearch、qdrant、redis、typesense、weaviate、pinecone、oracle、mongodb、gemfire、simple 之一。 |
spring.ai.kind | Spring AI 中框架 API 的类别：vector_store。 |
.高基数键
| 名称 | 描述 |
|---|---|
db.collection.name | 数据库内一个集合（表、容器）的名称。 |
db.namespace | 数据库的名称，在服务地址和端口内完全限定。 |
db.search.similarity_metric | 相似度搜索所使用的度量。 |
db.vector.dimension_count | 向量的维度。 |
db.vector.field_name | 作为向量之用的字段名（例如某个字段名）。 |
db.vector.query.content | 正在执行的搜索查询内容。 |
db.vector.query.filter | 搜索查询中使用的元数据过滤器。 |
db.vector.query.response.documents | 一次相似度搜索查询返回的文档。可选。 |
db.vector.query.similarity_threshold | 接受所有搜索分数的相似度阈值。阈值 0.0 表示接受任意相似度，或禁用相似度阈值过滤。阈值 1.0 表示需要精确匹配。 |
db.vector.query.top_k | 查询返回的最相似的 top-k 个向量。 |
响应数据
向量搜索响应数据通常很大，且可能包含敏感信息。 出于这些原因，默认不导出。
Spring AI 支持记录向量搜索响应数据，适用于排障场景。当有追踪可用时，日志会包含追踪信息以便更好的关联。
| 属性 | 描述 | 默认值 |
|---|---|---|
spring.ai.vectorstore.observations.log-query-response | 记录向量库查询响应内容。true 或 false | false |
DANGER
如果你启用对向量搜索响应数据的记录，存在泄露敏感或私密信息的风险。请务必小心！
更多指标参考
本节记录 Spring AI 各组件在 Prometheus 中呈现时所发出的指标。
指标命名约定
Spring AI 使用 Micrometer。基础指标名使用点号（例如 gen_ai.client.operation），Prometheus 会以下划线和标准后缀导出：
- 计时器（Timers） →
<base>_seconds_count、<base>_seconds_sum、<base>_seconds_max，以及（在支持时）<base>_active_count - 计数器（Counters） →
<base>_total（单调递增）
NOTE
下面展示基础指标名如何展开为 Prometheus 时间序列。
| 基础指标名 | 导出的时间序列 |
|---|---|
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 |
参考
- OpenTelemetry — 生成式 AI 的语义约定（概览）
- Micrometer — 命名 Meter
Chat Client 指标
| 指标名 | 类型 | 单位 | 描述 |
|---|---|---|---|
gen_ai_chat_client_operation_seconds_sum | Timer | seconds | ChatClient 操作（call/stream）所花的总时间 |
gen_ai_chat_client_operation_seconds_count | Counter | count | 已完成的 ChatClient 操作数 |
gen_ai_chat_client_operation_seconds_max | Gauge | seconds | ChatClient 操作观测到的最大时长 |
gen_ai_chat_client_operation_active_count | Gauge | count | 当前在途的 ChatClient 操作数 |
在途 vs 已完成：*_active_count 显示在途的调用；_seconds_* 系列只反映已完成的调用。
Chat Model 指标（模型服务商执行）
| 指标名 | 类型 | 单位 | 描述 |
|---|---|---|---|
gen_ai_client_operation_seconds_sum | Timer | seconds | 执行聊天模型操作所花的总时间 |
gen_ai_client_operation_seconds_count | Counter | count | 已完成的聊天模型操作数 |
gen_ai_client_operation_seconds_max | Gauge | seconds | 聊天模型操作观测到的最大时长 |
gen_ai_client_operation_active_count | Gauge | count | 当前在途的聊天模型操作数 |
令牌用量
| 指标名 | 类型 | 单位 | 描述 |
|---|---|---|---|
gen_ai_client_token_usage_total | Counter | tokens | 消耗的令牌总数，按令牌类型打标签 |
标签
| 标签 | 含义 |
|---|---|
gen_ai_token_type=input | 发送给模型的提示词令牌 |
gen_ai_token_type=output | 模型返回的补全令牌 |
gen_ai_token_type=total | 输入 + 输出 |
向量库指标
| 指标名 | 类型 | 单位 | 描述 |
|---|---|---|---|
db_vector_client_operation_seconds_sum | Timer | seconds | 向量库操作（add/upsert/delete/query）所花的总时间 |
db_vector_client_operation_seconds_count | Counter | count | 已完成的向量库操作数 |
db_vector_client_operation_seconds_max | Gauge | seconds | 向量库操作观测到的最大时长 |
db_vector_client_operation_active_count | Gauge | count | 当前在途的向量库操作数 |
标签
| 标签 | 含义 |
|---|---|
db_operation_name | 操作类型（add、upsert、delete、query） |
db_system | 向量数据库/服务商（redis、chroma、pgvector，…） |
spring_ai_kind | vector_store |
理解在途 vs 已完成
- 在途（
*_active_count） —— 进行中的操作的瞬时 gauge（并发/负载）。 - 已完成（
*_seconds_sum|count|max） —— 针对已结束操作的统计： _seconds_sum / _seconds_count→ 平均延迟_seconds_max→ 自上次抓取以来的高水位（受注册表行为影响）