Observability（可观测性）
Spring AI 建立在 Spring 生态系统的可观测性功能之上，为 AI 相关操作提供洞察。Spring AI 为其核心组件提供指标和跟踪功能：ChatClient（包括 Advisor）、ChatModel、EmbeddingModel、ImageModel 和 VectorStore。低基数键将被添加到指标和跟踪中，而高基数键仅添加到跟踪中。
1.0.0-RC1 破坏性变更
以下配置属性已重命名，以更好地反映其用途：
spring.ai.chat.client.observations.include-prompt→spring.ai.chat.client.observations.log-promptspring.ai.chat.observations.include-prompt→spring.ai.chat.observations.log-promptspring.ai.chat.observations.include-completion→spring.ai.chat.observations.log-completionspring.ai.image.observations.include-prompt→spring.ai.image.observations.log-promptspring.ai.vectorstore.observations.include-query-response→spring.ai.vectorstore.observations.log-query-response
Chat Client（聊天客户端）
当调用 spring.ai.chat.client observations 时会记录 ChatClient call() 或 stream() 操作。它们测量执行调用所花费的时间并传播相关的跟踪信息。
低基数键
| 名称 | 描述 |
|---|---|
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 |
高基数键
| 名称 | 描述 |
|---|---|
gen_ai.prompt | 通过聊天客户端发送的提示内容。可选。 |
spring.ai.chat.client.advisor.params（已弃用） | Advisor 参数映射。对话 ID 现在包含在 spring.ai.chat.client.conversation.id 中。 |
spring.ai.chat.client.advisors | 配置的聊天客户端顾问列表。 |
spring.ai.chat.client.conversation.id | 使用聊天内存时对话的标识符。 |
spring.ai.chat.client.system.params（已弃用） | 聊天客户端系统参数。可选。已被 gen_ai.prompt 取代。 |
spring.ai.chat.client.system.text（已弃用） | 聊天客户端系统文本。可选。已被 gen_ai.prompt 取代。 |
spring.ai.chat.client.tool.function.names（已弃用） | 启用的工具函数名称。已被 spring.ai.chat.client.tool.names 取代。 |
spring.ai.chat.client.tool.function.callbacks（已弃用） | 配置的聊天客户端函数回调列表。已被 spring.ai.chat.client.tool.names 取代。 |
spring.ai.chat.client.tool.names | 传递给聊天客户端的工具名称。 |
spring.ai.chat.client.user.params（已弃用） | 聊天客户端用户参数。可选。已被 gen_ai.prompt 取代。 |
spring.ai.chat.client.user.text（已弃用） | 聊天客户端用户文本。可选。已被 gen_ai.prompt 取代。 |
提示内容
ChatClient 提示内容通常很大，可能包含敏感信息。由于这些原因，默认情况下不会导出。Spring AI 支持记录聊天客户端提示内容以帮助调试和故障排除。
| 属性 | 描述 | 默认值 |
|---|---|---|
spring.ai.chat.client.observations.log-prompt | 是否记录聊天客户端提示内容 | false |
如果您启用聊天客户端提示内容的记录，存在暴露敏感或私人信息的风险。请谨慎！
输入数据（已弃用）
spring.ai.chat.client.observations.include-input 属性已弃用，由 spring.ai.chat.client.observations.log-prompt 替换。请参见提示内容。
ChatClient 输入数据通常很大，可能包含敏感信息。由于这些原因，默认情况下不会导出。Spring AI 支持记录输入数据以帮助调试和故障排除。
| 属性 | 描述 | 默认值 |
|---|---|---|
spring.ai.chat.client.observations.include-input | 是否在观察中包含输入内容 | false |
如果您启用在观察中包含输入内容，存在暴露敏感或私人信息的风险。请谨慎！
Chat Client Advisors（聊天客户端顾问）
当执行顾问时会记录 spring.ai.advisor observations。它们测量在顾问中花费的时间（包括在内部顾问上花费的时间）并传播相关的跟踪信息。
低基数键
| 名称 | 描述 |
|---|---|
gen_ai.operation.name | 始终为 framework |
gen_ai.system | 始终为 spring_ai |
spring.ai.advisor.type（已弃用） | 顾问在请求处理中应用其逻辑的位置，BEFORE、AFTER 或 AROUND 之一。此区别不再适用，因为所有顾问始终是相同的类型。 |
spring.ai.kind | Spring AI 中框架 API 的类型：advisor |
高基数键
| 名称 | 描述 |
|---|---|
spring.ai.advisor.name | 顾问的名称。 |
spring.ai.advisor.order | 顾问链中的顾问顺序。 |
Chat Model（聊天模型）
可观测性功能目前仅支持以下 AI 模型提供商的 ChatModel 实现：Anthropic、Azure OpenAI、Mistral AI、Ollama、OpenAI、Vertex AI、MiniMax、Moonshot、QianFan、ZhiPu AI。未来的版本将支持更多 AI 模型提供商。
当调用 ChatModel 的 call 或 stream 方法时会记录 gen_ai.client.operation observations。它们测量方法完成所花费的时间并传播相关的跟踪信息。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.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.input_tokens | 模型输入（提示）中使用的令牌数 |
gen_ai.usage.output_tokens | 模型输出（完成）中使用的令牌数 |
gen_ai.usage.total_tokens | 模型交换中使用的总令牌数 |
gen_ai.prompt | 发送给模型的完整提示。可选。 |
gen_ai.completion | 从模型接收的完整响应。可选。 |
spring.ai.model.request.tool.names | 在请求中提供给模型的工具定义列表。 |
对于测量用户令牌，上表列出了观察跟踪中存在的值。使用由 ChatModel 提供的指标名称 gen_ai.client.token.usage。
聊天提示和完成数据
聊天提示和完成数据通常很大，可能包含敏感信息。由于这些原因，默认情况下不会导出。Spring AI 支持记录聊天提示和完成数据，这对于故障排除场景很有用。当跟踪可用时，日志将包含跟踪信息以更好地进行关联。
| 属性 | 描述 | 默认值 |
|---|---|---|
spring.ai.chat.observations.log-prompt | 记录提示内容 | false |
spring.ai.chat.observations.log-completion | 记录完成内容 | false |
spring.ai.chat.observations.include-error-logging | 在观察中包含错误日志记录 | false |
如果您启用聊天提示和完成数据的记录，存在暴露敏感或私人信息的风险。请谨慎！
Tool Calling（工具调用）
在聊天模型交互的上下文中执行工具调用时会记录 spring.ai.tool observations。它们测量工具调用完成所花费的时间并传播相关的跟踪信息。
低基数键
| 名称 | 描述 |
|---|---|
gen_ai.operation.name | 正在执行的操作名称。始终为 framework |
gen_ai.system | 负责操作的提供商。始终为 spring_ai |
spring.ai.kind | Spring AI 执行的操作类型。始终为 tool_call |
spring.ai.tool.definition.name | 工具的名称 |
高基数键
| 名称 | 描述 |
|---|---|
spring.ai.tool.definition.description | 工具的描述。 |
spring.ai.tool.definition.schema | 用于调用工具的参数架构。 |
spring.ai.tool.call.arguments | 工具调用的输入参数。（仅在启用时） |
spring.ai.tool.call.result | 用于调用工具的参数架构。（仅在启用时） |
工具调用参数和结果数据
工具调用的输入参数和结果默认情况下不会导出，因为它们可能是敏感的。Spring AI 支持将工具调用参数和结果数据作为 span 属性导出。
| 属性 | 描述 | 默认值 |
|---|---|---|
spring.ai.tools.observations.include-content | 在观察中包含工具调用内容 | false |
如果您启用在观察中包含工具调用参数和结果，存在暴露敏感或私人信息的风险。请谨慎！
EmbeddingModel（嵌入模型）
可观测性功能目前仅支持以下 AI 模型提供商的 EmbeddingModel 实现：Azure OpenAI、Mistral AI、Ollama 和 OpenAI。未来的版本将支持更多 AI 模型提供商。
在嵌入模型方法调用时会记录 gen_ai.client.operation observations。它们测量方法完成所花费的时间并传播相关的跟踪信息。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 | 模型交换中使用的总令牌数 |
对于测量用户令牌，上表列出了观察跟踪中存在的值。使用由 EmbeddingModel 提供的指标名称 gen_ai.client.token.usage。
Image Model（图像模型）
可观测性功能目前仅支持以下 AI 模型提供商的 ImageModel 实现：OpenAI。未来的版本将支持更多 AI 模型提供商。
在图像模型方法调用时会记录 gen_ai.client.operation observations。它们测量方法完成所花费的时间并传播相关的跟踪信息。gen_ai.client.token.usage 指标测量单个模型调用使用的输入和输出令牌数量。
低基数键
| 名称 | 描述 |
|---|---|
gen_ai.operation.name | 正在执行的操作的名称 |
gen_ai.system | 由客户端工具识别的模型提供商 |
gen_ai.request.model | 正在发出请求的模型名称 |
高基数键
| 名称 | 描述 |
|---|---|
gen_ai.request.image.response_format | 返回生成图像的格式 |
gen_ai.request.image.size | 要生成的图像大小 |
gen_ai.request.image.style | 要生成的图像样式 |
gen_ai.response.id | AI 响应的唯一标识符 |
gen_ai.response.model | 生成响应的模型名称 |
gen_ai.usage.input_tokens | 模型输入（提示）中使用的令牌数 |
gen_ai.usage.output_tokens | 模型输出（生成）中使用的令牌数 |
gen_ai.usage.total_tokens | 模型交换中使用的总令牌数 |
gen_ai.prompt | 发送给模型的完整提示。可选。 |
对于测量用户令牌，上表列出了观察跟踪中存在的值。使用由 ImageModel 提供的指标名称 gen_ai.client.token.usage。
图像提示数据
图像提示数据通常很大，可能包含敏感信息。由于这些原因，默认情况下不会导出。Spring AI 支持记录图像提示数据，这对于故障排除场景很有用。当跟踪可用时，日志将包含跟踪信息以更好地进行关联。
| 属性 | 描述 | 默认值 |
|---|---|---|
spring.ai.image.observations.log-prompt | 记录图像提示内容 | false |
如果您启用图像提示数据的记录，存在暴露敏感或私人信息的风险。请谨慎！
Vector Stores（向量存储）
Spring AI 中的所有向量存储实现都通过 Micrometer 进行工具化，以提供指标和分布式跟踪数据。
在与向量存储交互时会记录 db.vector.client.operation observations。它们测量查询、添加和删除操作所花费的时间并传播相关的跟踪信息。
低基数键
| 名称 | 描述 |
|---|---|
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、hana、simple 之一。 |
spring.ai.kind | Spring AI 中框架 API 的类型：vector_store。 |
高基数键
| 名称 | 描述 |
|---|---|
db.collection.name | 数据库中集合（表、容器）的名称。 |
db.namespace | 数据库名称，在服务器地址和端口内完全限定。 |
db.record.id | 记录标识符（如果存在）。 |
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 | 查询返回的最相似的向量数量。 |
响应数据
向量搜索响应数据通常很大，可能包含敏感信息。由于这些原因，默认情况下不会导出。Spring AI 支持记录向量搜索响应数据，这对于故障排除场景很有用。当跟踪可用时，日志将包含跟踪信息以更好地进行关联。
| 属性 | 描述 | 默认值 |
|---|---|---|
spring.ai.vectorstore.observations.log-query-response | 记录向量存储查询响应内容 | false |
如果您启用向量搜索响应数据的记录，存在暴露敏感或私人信息的风险。请谨慎！
更多指标参考
本节记录了 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 |
Chat Client 指标
| 指标名称 | 类型 | 单位 | 描述 |
|---|---|---|---|
gen_ai_chat_client_operation_seconds_sum | Timer | seconds | ChatClient 操作（调用/流）中花费的总时间 |
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 操作数量 |
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 | 输入 + 输出 |
Vector Store 指标
| 指标名称 | 类型 | 单位 | 描述 |
|---|---|---|---|
db_vector_client_operation_seconds_sum | Timer | seconds | 向量存储操作（添加/删除/查询）中花费的总时间 |
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、delete、query） |
db_system | 向量数据库/提供商（redis、chroma、pgvector、…） |
spring_ai_kind | vector_store |
理解 Active 与 Completed
- Active（
*_active_count） — 进行中操作的瞬时仪表（并发性/负载） - Completed（
*_seconds_sum|count|max） — 已完成操作的统计数据：_seconds_sum / _seconds_count→ 平均延迟_seconds_max→ 自上次刮取以来的高水位标记（受注册表行为影响）
