可观测性
Spring AI基于Spring生态系统中的可观测性功能，为AI相关操作提供洞察力。
要启用可观测性，需要 spring-boot-actuator 模块。请在项目的 Maven pom.xml 构建文件中添加 Spring Boot Actuator 依赖：
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
或将其添加到你的Gradle build.gradle 构建文件中。
dependencies {
implementation 'org.springframework.boot:spring-boot-starter-actuator'
}
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
聊天客户端
当调用 ChatClient 的 call() 或 stream() 操作时，会记录 spring.ai.chat.client 观测信息。这些观测记录了执行调用的耗时并传播相关的追踪信息。
表 1. 低基数键
| 名称 | 描述 |
|---|---|
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。 |
表 2. 高基数键
| 名称 | 描述 |
|---|---|
gen_ai.prompt | 通过聊天客户端发送的提示内容。可选。 |
spring.ai.chat.client.advisor.params (已弃用) | 顾问参数映射。对话 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.log-completion | 是否记录聊天客户端完成内容。 | false |
若启用聊天客户端提示与完成数据的日志记录，可能会暴露敏感或隐私信息。请务必谨慎操作！
输入数据（已弃用）
spring.ai.chat.client.observations.include-input 属性已弃用，由 spring.ai.chat.client.observations.log-prompt 替代。请参阅 Prompt 内容。
ChatClient 的输入数据通常较大，且可能包含敏感信息。出于这些原因，默认情况下不会导出这些数据。
Spring AI 支持记录输入数据，以帮助进行调试和故障排除。
| Property | Description | Default |
|---|---|---|
spring.ai.chat.client.observations.include-input | 是否在观测数据中包含输入内容。 | false |
若启用输入内容包含在观测记录中，存在暴露敏感或隐私信息的风险。请务必谨慎操作！
聊天客户端顾问
spring.ai.advisor 观察点会在顾问执行时记录。它们测量在顾问中花费的时间（包括内部顾问所消耗的时间），并传播相关的追踪信息。
表 3. 低基数键
| 名称 | 描述 |
|---|---|
gen_ai.operation.name | 总是 framework. |
gen_ai.system | 总是 spring_ai. |
spring.ai.advisor.type (已弃用) | 指示 advisor 在请求处理中应用其逻辑的位置，取值为 BEFORE、AFTER 或 AROUND 之一。由于所有 Advisor 现在始终是同一类型，此区分不再适用。 |
spring.ai.kind | Spring AI 中框架 API 的类型：advisor. |
表 4. 高基数键
| 名称 | 描述 |
|---|---|
spring.ai.advisor.name | Advisor 的名称。 |
spring.ai.advisor.order | Advisor 在 Advisor 链中的顺序。 |
聊天模型
目前，可观测性功能仅支持来自以下 AI 模型提供商的 ChatModel 实现：Anthropic、Azure OpenAI、Mistral AI、Ollama、OpenAI、Vertex AI、MiniMax、Moonshot、QianFan、智谱 AI。未来版本将支持更多 AI 模型提供商。
gen_ai.client.operation 观测记录在调用 ChatModel 的 call 或 stream 方法时生成。它们测量方法完成所花费的时间，并传播相关的追踪信息。
gen_ai.client.token.usage 指标用于衡量单次模型调用所使用的输入和输出令牌数量。
表 5. 低基数键
| 名称 | 描述 |
|---|---|
gen_ai.operation.name | 正在执行的操作的名称。 |
gen_ai.system | 由客户端检测识别的模型提供商。 |
gen_ai.request.model | 请求所指向的模型名称。 |
gen_ai.response.model | 生成响应的模型名称。 |
表 6. 高基数键
| 名称 | 描述 |
|---|---|
gen_ai.request.frequency_penalty | 模型请求的频率惩罚设置。 |
gen_ai.request.max_tokens | 模型为一次请求生成的最大 token 数量。 |
gen_ai.request.presence_penalty | 模型请求的存在惩罚设置。 |
gen_ai.request.stop_sequences | 模型将用于停止生成后续 token 的序列列表。 |
gen_ai.request.temperature | 模型请求的温度设置。 |
gen_ai.request.top_k | 模型请求的 top_k 采样设置。 |
gen_ai.request.top_p | 模型请求的 top_p 采样设置。 |
gen_ai.response.finish_reasons | 模型停止生成 token 的原因，与收到的每个生成结果相对应。 |
gen_ai.response.id | AI 响应的唯一标识符。 |
gen_ai.usage.input_tokens | 模型输入（提示）中使用的 token 数量。 |
gen_ai.usage.output_tokens | 模型输出（补全）中使用的 token 数量。 |
gen_ai.usage.total_tokens | 模型交互中使用的 token 总数。 |
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 | 记录提示内容。true 或 false | false |
spring.ai.chat.observations.log-completion | 记录完成内容。true 或 false | false |
spring.ai.chat.observations.include-error-logging | 在观察记录中包含错误日志。true 或 false | false |
:::警告
如果启用聊天提示和完成数据的日志记录，存在暴露敏感或私人信息的风险。请务必谨慎处理！
:::
工具调用
spring.ai.tool 观测数据在聊天模型交互环境下执行工具调用时被记录。它们用于衡量完成工具调用所花费的时间，并传递相关的追踪信息。
表 7. 低基数键
| 名称 | 描述 |
|---|---|
gen_ai.operation.name | 正在执行的操作名称。其值始终为 framework。 |
gen_ai.system | 负责该操作的提供者。其值始终为 spring_ai。 |
spring.ai.kind | Spring AI 执行的操作类型。其值始终为 tool_call。 |
spring.ai.tool.definition.name | 工具的名称。 |
表8. 高基数键
| 名称 | 描述 |
|---|---|
spring.ai.tool.definition.description | 工具的描述。 |
spring.ai.tool.definition.schema | 调用工具时所用参数的 schema。 |
spring.ai.tool.call.arguments | 工具调用的输入参数。（仅在启用时可用） |
spring.ai.tool.call.result | 调用工具时所用参数的 schema。（仅在启用时可用） |
工具调用参数与结果数据
默认情况下，工具调用的输入参数和结果不会导出，因为它们可能包含敏感信息。
Spring AI 支持将工具调用参数和结果数据导出为跨度属性。
| 属性 | 描述 | 默认值 |
|---|---|---|
spring.ai.tools.observations.include-content | 是否在观测数据中包括工具调用内容。true 或 false | false |
:::警告
若启用工具调用参数及结果在观测中的包含功能，将存在暴露敏感或私有信息的风险。请务必谨慎操作！
:::
EmbeddingModel
目前，仅以下 AI 模型提供商的 EmbeddingModel 实现支持可观测性功能：Azure OpenAI、Mistral AI、Ollama 和 OpenAI。未来版本将支持更多 AI 模型提供商。
gen_ai.client.operation 观测记录在嵌入模型方法调用时生成。它们测量方法完成所花费的时间，并传播相关的追踪信息。
:::重要
gen_ai.client.token.usage 指标用于衡量单个模型调用所使用的输入和输出令牌数量。
:::
表9. 低基数键
| 名称 | 描述 |
|---|---|
gen_ai.operation.name | 正在执行的操作的名称。 |
gen_ai.system | 由客户端检测工具识别的模型提供商。 |
gen_ai.request.model | 请求所针对的模型名称。 |
gen_ai.response.model | 生成响应的模型名称。 |
表 10. 高基数键
| 名称 | 描述 |
|---|---|
gen_ai.request.embedding.dimensions | 生成输出嵌入向量的维度数量。 |
gen_ai.usage.input_tokens | 模型输入中使用的令牌数量。 |
gen_ai.usage.total_tokens | 模型交互中使用的令牌总数。 |
在测量用户令牌时，上表列出了观察追踪中存在的数值。请使用由 EmbeddingModel 提供的指标名称 gen_ai.client.token.usage。
图像模型
目前，可观测性功能仅支持以下 AI 模型提供商的 ImageModel 实现：OpenAI。未来版本中将支持更多 AI 模型提供商。
gen_ai.client.operation 观测记录在图像模型方法调用上。它们测量方法完成所花费的时间并传播相关的追踪信息。
:::重要
gen_ai.client.token.usage 指标用于衡量单次模型调用所使用的输入和输出令牌数量。
:::
表 11. 低基数键
| 名称 | 描述 |
|---|---|
gen_ai.operation.name | 正在执行的操作的名称。 |
gen_ai.system | 由客户端插桩识别的模型提供商。 |
gen_ai.request.model | 请求所指向的模型的名称。 |
表 12. 高基数键
| 名称 | 描述 |
|---|---|
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 | 模型输入（提示词）中使用的 token 数量。 |
gen_ai.usage.output_tokens | 模型输出（生成内容）中使用的 token 数量。 |
gen_ai.usage.total_tokens | 模型交互中使用的 token 总数。 |
gen_ai.prompt | 发送给模型的完整提示词。可选。 |
对于用户令牌的计量，之前的表格列出了观测追踪记录中包含的值。请使用由 ImageModel 提供的指标名称 gen_ai.client.token.usage。
图像提示数据
图像提示数据通常较大，且可能包含敏感信息。因此，默认情况下不会导出这些数据。
Spring AI 支持记录图像提示数据，这在故障排除场景中非常有用。当启用追踪功能时，日志将包含追踪信息，以便更好地进行关联分析。
| 属性 | 描述 | 默认值 |
|---|---|---|
spring.ai.image.observations.log-prompt | 是否记录图像提示内容。true 或 false | false |
若启用图像提示数据记录功能，存在暴露敏感或隐私信息的风险。请务必谨慎操作！
向量存储
Spring AI 中的所有向量存储实现都已配置为通过 Micrometer 提供指标和分布式追踪数据。
db.vector.client.operation 观测指标在与向量存储交互时被记录。它用于测量 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、hana、simple。 |
spring.ai.kind | Spring AI 中框架 API 的类型：vector_store。 |
表 14. 高基数键
| 名称 | 描述 |
|---|---|
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 | 查询返回的前 k 个最相似向量。 |
响应数据
向量搜索响应数据通常较大，且可能包含敏感信息。基于这些原因，默认情况下不导出该数据。
Spring AI 支持记录向量搜索响应数据，有助于排查问题场景。当启用追踪功能时，日志将包含追踪信息以实现更好的关联分析。
| 属性 | 描述 | 默认值 |
|---|---|---|
spring.ai.vectorstore.observations.log-query-response | 记录向量存储查询响应的内容。true 或 false | 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 |
参考文献
-
OpenTelemetry — 生成式人工智能语义约定（概述）
-
Micrometer — 命名计量器
聊天客户端指标
| 指标名称 | 类型 | 单位 | 描述 |
|---|---|---|---|
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 操作数量 |
活动与已完成：**_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 | 当前正在进行的聊天模型操作数量 |
令牌使用
| 指标名称 | 类型 | 单位 | 描述 |
|---|---|---|---|
gen_ai_client_token_usage_total | Counter | tokens | 已消耗的总 token 数，按 token 类型标记 |
标签
| Label | Meaning |
|---|---|
gen_ai_token_type=input | 发送到模型的提示词元 |
gen_ai_token_type=output | 模型返回的完成词元 |
gen_ai_token_type=total | 输入 + 输出 |
Vector Store 指标
| 指标名称 | 类型 | 单位 | 描述 |
|---|---|---|---|
db_vector_client_operation_seconds_sum | Timer | 秒 | 向量存储操作（添加/删除/查询）花费的总时间 |
db_vector_client_operation_seconds_count | Counter | 计数 | 已完成的向量存储操作数量 |
db_vector_client_operation_seconds_max | Gauge | 秒 | 观测到的向量存储操作最大持续时间 |
db_vector_client_operation_active_count | Gauge | 计数 | 当前正在进行中的向量存储操作数量 |
标签
| Label | 含义 |
|---|---|
db_operation_name | 操作类型 (add, delete, query) |
db_system | 向量数据库/提供商 (redis, chroma, pgvector, …) |
spring_ai_kind | vector_store |
理解 Active 与 Completed 状态
-
活动状态（
*_active_count） — 衡量正在进行的操作的瞬时指标（并发/负载量）。 -
已完成（
*_seconds_sum|count|max） — 针对已结束操作的统计信息： -
_seconds_sum / _seconds_count→ 平均延迟 -
_seconds_max→ 自上次数据采集以来的最高水位线（受注册表行为影响）