可观测性
Spring AI 基于 Spring 生态系统中的可观测性功能,提供对 AI 相关操作的洞察。它为其核心组件提供指标和追踪能力:ChatClient(包括 Advisor)、ChatModel、EmbeddingModel、ImageModel 和 VectorStore。
请参考 Spring Boot Metrics 和 Spring Boot Tracing 文档,以在您的应用程序中启用 metrics 和 tracing 支持。
低基数 key 将被添加到 metrics 和 traces 中,而高基数 key 仅会被添加到 traces 中。
聊天客户端
当调用 ChatClient 的 call() 或 stream() 操作时,spring.ai.chat.client 观测会被记录。它们会度量执行调用所花费的时间,并传播相关的追踪信息。
表 1. 低基数键
| 名称 | 描述 |
|---|---|
gen_ai.operation.name | 始终为 framework。 |
gen_ai.system | 始终为 spring_ai。 |
spring.ai.chat.client.stream | 聊天模型响应是否为流 - true or false |
spring.ai.kind | Spring AI 中的框架 API 类型:chat_client。 |
表 2. 高基数键
| 名称 | 描述 |
|---|---|
spring.ai.chat.client.advisors | 已配置的 chat client advisors 列表。 |
spring.ai.chat.client.conversation.id | 使用 chat memory 时的 conversation 标识符。 |
spring.ai.chat.client.tool.names | 传递给 chat client 的 tools 名称。 |
Prompt 与 Completion 数据
ChatClient prompt 和 completion 数据通常较大,并且可能包含敏感信息。因此,默认情况下不会导出。
Spring AI 支持记录 prompt 和 completion 数据,以帮助调试和故障排除。
| 属性 | 描述 | 默认值 |
|---|---|---|
spring.ai.chat.client.observations.log-prompt | 是否记录 chat client 的 prompt 内容。 | false |
spring.ai.chat.client.observations.log-completion | 是否记录 chat client 的 completion 内容。 | false |
如果您启用 chat client 的 prompt 和 completion data 日志记录,可能会暴露敏感或私密信息。请谨慎!
Chat Client Advisors
当执行 advisor 时,会记录 spring.ai.advisor 观测。它们用于衡量 advisor 花费的时间(包括内部 advisor 花费的时间),并传播相关的 tracing 信息。
表 3. 低基数键
| 名称 | 描述 |
|---|---|
gen_ai.operation.name | 始终为 framework。 |
gen_ai.system | 始终为 spring_ai。 |
spring.ai.advisor.name | advisor 的名称。 |
spring.ai.kind | Spring AI 中框架 API 的类型:advisor。 |
表 4. 高基数键
| 名称 | 描述 |
|---|---|
spring.ai.advisor.order | Advisor 在 advisor chain 中的顺序。 |
Chat Model
OpenAI 和 Anthropic chat 模型确实会发出 HTTP-layer observations(chat-model 层 + HTTP 层),但针对 streaming 调用存在一个特定限制。HTTP-layer observation 会携带 HTTP method、URI、status code,并在网络传输中向下游服务(AI 网关、代理、OpenAI 兼容的推理服务器)传播 traceparent。
对于同步调用,okhttp.requests span 会正确嵌套在 gen_ai.client.operation span 之下。对于 streaming 调用,HTTP span 会被记录,但不会作为 chat-model span 的子 span —— SDK 的异步 streaming 路径在调用 Spring AI 的 HTTP 客户端之前会跳转到 ForkJoinPool.commonPool(),从而在该边界处丢失调用线程的 observation 上下文。
详情请参见 OpenAI chat 文档 和 Anthropic chat 文档。
gen_ai.client.operation 观测会在调用 ChatModel 的 call 或 stream 方法时记录。它们衡量方法完成所花费的时间,并传播相关的 tracing 信息。
gen_ai.client.token.usage 指标用于衡量单次模型调用所使用的输入和输出 token 数量。
表 5. 低基数键
| 名称 | 描述 |
|---|---|
gen_ai.operation.name | 正在执行的操作名称。 |
gen_ai.system | 由客户端插桩识别的模型提供商。 |
gen_ai.request.model | 请求所使用的模型名称。 |
gen_ai.response.model | 生成响应的模型名称。 |
表 6. 高基数键
对于测量用户 token,前面的表格列出了 observation trace 中存在的值。使用由 ChatModel 提供的指标名称 gen_ai.client.token.usage。
Chat Prompt 和 Completion 数据
chat prompt 和 completion 数据通常较大,并且可能包含敏感信息。因此,默认情况下不会导出这些数据。
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 |
如果你启用对 chat prompt 和 completion 数据的日志记录,可能会暴露敏感或隐私信息。请务必小心!
Tool Calling
spring.ai.tool 观测会在聊天模型交互上下文中执行工具调用时被记录。它们衡量工具调用完成所花费的时间,并传播相关追踪信息。
表 7. 低基数键
| 名称 | 描述 |
|---|---|
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。 |
表 8. High Cardinality Keys
| 名称 | 描述 |
|---|---|
spring.ai.tool.definition.description | 工具的描述。 |
spring.ai.tool.definition.schema | 用于调用工具的参数的 Schema。 |
spring.ai.tool.call.id | 由 chat model 识别的 tool call 的 ID。 |
spring.ai.tool.call.arguments | tool call 的输入参数。(仅在启用时) |
spring.ai.tool.call.result | tool call 执行的结果。(仅在启用时) |
Tool Call 参数和结果数据
工具调用的输入参数和结果默认不会被导出,因为它们可能具有敏感性。
Spring AI 支持将工具调用参数和结果数据导出为 span 属性。
| 属性 | 描述 | 默认值 |
|---|---|---|
spring.ai.tools.observations.include-content | 在 observations 中包含工具调用内容。true 或 false | false |
如果你启用将 tool call 参数和结果包含在 observations 中,可能会有暴露敏感或私有信息的风险。请小心!
EmbeddingModel
可观测性功能目前仅支持以下 AI 模型提供商的 EmbeddingModel 实现:Mistral AI、Ollama 和 OpenAI。未来的版本将支持更多 AI 模型提供商。
gen_ai.client.operation 观测记录在 embedding model 方法调用上。它们衡量方法完成所花费的时间,并传播相关 tracing 信息。
gen_ai.client.token.usage 指标衡量单次模型调用所使用的输入和输出 token 数量。
表 9. 低基数键
| 名称 | 描述 |
|---|---|
gen_ai.operation.name | 正在执行的操作的名称。 |
gen_ai.system | 由客户端插桩识别的模型提供者。 |
gen_ai.request.model | 请求所指向的模型的名称。 |
gen_ai.response.model | 生成响应的模型的名称。 |
表 10. 高基数键
| 名称 | 描述 |
|---|---|
gen_ai.request.embedding.dimensions | 生成的输出 embeddings 的维度数量。 |
gen_ai.usage.input_tokens | 模型输入中使用的 token 数量。 |
gen_ai.usage.total_tokens | 模型交互中使用的 token 总数。 |
对于测量 user tokens,前面的表格列出了 observation trace 中存在的值。请使用由 EmbeddingModel 提供的指标名称 gen_ai.client.token.usage。
图像模型
目前,可观测性功能仅支持来自以下 AI 模型提供商的 ImageModel 实现:OpenAI。未来的版本将支持更多 AI 模型提供商。
gen_ai.client.operation 观测值会在图像模型方法调用时被记录。它们衡量方法完成所花费的时间,并传播相关的 tracing 信息。
表 11. 低基数键
| 名称 | 描述 |
|---|---|
gen_ai.operation.name | 正在执行的操作的名称。 |
gen_ai.system | 由客户端插桩识别的模型提供者。 |
gen_ai.request.model | 请求所指向的模型的名称。 |
表 12. 高基数键
| 名称 | 描述 |
|---|---|
gen_ai.request.image.response_format | 返回生成图像的格式。 |
gen_ai.request.image.size | 要生成的图像尺寸(例如 1024x1024)。 |
gen_ai.request.image.style | 要生成的图像风格。 |
图像提示数据
图像 prompt 数据通常较大,并且可能包含敏感信息。因此,默认不导出。
Spring AI 支持记录图像 prompt 数据,便于故障排查场景。当 tracing 可用时,日志将包含 trace 信息,以便更好地进行关联。
| Property | Description | Default |
|---|---|---|
spring.ai.image.observations.log-prompt | 记录图像 prompt 内容。true 或 false | false |
如果你启用图像 prompt 数据的日志记录,存在暴露敏感或私密信息的风险。请务必小心!
Vector Stores
Spring AI 中的所有 vector store 实现都通过 Micrometer 进行了插桩,以提供指标和分布式追踪数据。
db.vector.client.operation 观测会在与 Vector Store 交互时记录。它们测量 query、add 和 remove 操作所花费的时间,并传播相关追踪信息。
表 13. 低基数键
| 名称 | 描述 |
|---|---|
db.operation.name | 正在执行的操作或命令的名称。取值为 add、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。 |
表 14. 高基数键
| 名称 | 描述 |
|---|---|
db.collection.name | 数据库中 collection(table、container)的名称。 |
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 个最相似向量。 |
响应数据
vector search 响应数据通常较大,并且可能包含敏感信息。出于这些原因,默认情况下不会导出该数据。
Spring AI 支持记录向量搜索响应数据,适用于故障排查场景。当追踪可用时,日志将包含追踪信息,以便更好地进行关联。
| 属性 | 描述 | 默认值 |
|---|---|---|
spring.ai.vectorstore.observations.log-query-response | 记录向量存储查询响应内容。 true 或 false | false |
如果启用 vector search 响应数据的日志记录,可能会有暴露敏感或私密信息的风险。请务必谨慎!
更多 Metrics 参考
本节介绍 Spring AI 组件在 Prometheus 中呈现的指标。
指标命名规范
Spring AI 使用 Micrometer。基础指标名称使用点号(例如 gen_ai.client.operation),Prometheus 导出时会使用下划线和标准后缀:
-
计时器 →
<base>_seconds_count、<base>_seconds_sum、<base>_seconds_max以及(受支持时)<base>_active_count -
计数器 →
<base>_total(单调递增)
以下展示基础指标名称如何展开为 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 命名
聊天客户端指标
| 指标名称 | 类型 | 单位 | 描述 |
|---|---|---|---|
gen_ai_chat_client_operation_seconds_sum | Timer | 秒 | ChatClient 操作(call/stream)的总耗时 |
gen_ai_chat_client_operation_seconds_count | Counter | 次数 | 已完成的 ChatClient 操作数量 |
gen_ai_chat_client_operation_seconds_max | Gauge | 秒 | ChatClient 操作的最大观测时长 |
gen_ai_chat_client_operation_active_count | Gauge | 次数 | 当前正在进行的 ChatClient 操作数量 |
Active 与 Completed:**_active_count_** 显示进行中的调用;_seconds 序列仅反映已完成的调用。
聊天模型指标(模型提供商执行)
| 指标名称 | 类型 | 单位 | 描述 |
|---|---|---|---|
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 | 当前正在进行的聊天模型操作数量 |
Token 使用量
| 指标名称 | 类型 | 单位 | 描述 |
|---|---|---|---|
gen_ai_client_token_usage_total | Counter | tokens | 消耗的总 tokens 数,按 token 类型标记 |
标签
| 标签 | 含义 |
|---|---|
gen_ai_token_type=input | 发送给模型的 Prompt tokens |
gen_ai_token_type=output | 模型返回的 Completion tokens |
gen_ai_token_type=total | 输入 + 输出 |
向量存储指标
| Metric Name | Type | Unit | Description |
|---|---|---|---|
db_vector_client_operation_seconds_sum | Timer | 秒 | 向量存储操作 (add/delete/query) 花费的总时间 |
db_vector_client_operation_seconds_count | Counter | 计数 | 已完成的向量存储操作数量 |
db_vector_client_operation_seconds_max | Gauge | 秒 | 观察到的向量存储操作最大持续时间 |
db_vector_client_operation_active_count | Gauge | 计数 | 当前正在进行的向量存储操作数量 |
标签
| 标签 | 含义 |
|---|---|
db_operation_name | 操作类型 (add, delete, query) |
db_system | 向量 DB/提供商 (redis, chroma, pgvector, …) |
spring_ai_kind | vector_store |
理解 Active 与 Completed
-
Active (
*_active_count) — 进行中操作的瞬时 gauge(并发/负载)。 -
Completed (
*_seconds_sum|count|max) — 已完成操作的统计信息: -
_seconds_sum / _seconds_count→ 平均延迟 -
_seconds_max→ 自上次 scrape 以来的最高值(取决于 registry 行为)