可观测性

Spring AI 构建于 Spring 生态系统中的可观测性功能之上，以提供对 AI 相关操作的洞察。

启用可观测性需要 spring-boot-actuator 模块。将 Spring Boot Actuator 依赖项添加到您项目的 Maven pom.xml 构建文件中

<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-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

聊天客户端

当调用 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

是否记录聊天客户端提示内容。

假

spring.ai.chat.client.observations.log-completion

是否记录聊天客户端完成内容。

假
如果您启用聊天客户端提示和完成数据的记录，存在暴露敏感或私人信息的风险。请务必小心！

输入数据 (已弃用)

spring.ai.chat.client.observations.include-input 属性已弃用，由 spring.ai.chat.client.observations.log-prompt 取代。请参阅 提示内容。

ChatClient 输入数据通常很大，可能包含敏感信息。因此，默认情况下不导出。

Spring AI 支持记录输入数据，以帮助调试和故障排除。

财产 描述 默认值

spring.ai.chat.client.observations.include-input

是否在观测中包含输入内容。

假
如果您在观测中启用输入内容的包含，存在暴露敏感或私人信息的风险。请务必小心！

聊天客户端顾问

当执行顾问时，会记录 spring.ai.advisor 观测。它们测量在顾问中花费的时间（包括在内部顾问中花费的时间）并传播相关的跟踪信息。

表 3. 低基数键
名称 描述

gen_ai.operation.name

始终为 framework。

gen_ai.system

始终为 spring_ai。

spring.ai.advisor.type (已弃用)

顾问在请求处理中应用其逻辑的位置，可以是 BEFORE、AFTER 或 AROUND 之一。此区别不再适用，因为所有顾问始终是相同类型。

spring.ai.kind

Spring AI 中框架 API 的类型：advisor。
表 4. 高基数键
名称 描述

spring.ai.advisor.name

顾问的名称。

spring.ai.advisor.order

顾问链中的顾问顺序。

聊天模型

目前仅支持以下 AI 模型提供商的 ChatModel 实现的可观测性功能：Anthropic、Azure OpenAI、Mistral AI、Ollama、OpenAI、Vertex AI、MiniMax、Moonshot、QianFan、Zhipu AI。未来的版本将支持更多的 AI 模型提供商。

当调用 ChatModel 的 call 或 stream 方法时，会记录 gen_ai.client.operation 观测。它们测量方法完成所花费的时间并传播相关的跟踪信息。

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

模型为请求生成的最大令牌数量。

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

记录提示内容。true 或 false

假

spring.ai.chat.observations.log-completion

记录完成内容。true 或 false

假

spring.ai.chat.observations.include-error-logging

在观测中包含错误日志记录。true 或 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

用于调用工具的参数模式。

spring.ai.tool.call.arguments

工具调用的输入参数。（仅在启用时）

spring.ai.tool.call.result

用于调用工具的参数模式。（仅在启用时）

工具调用参数和结果数据

工具调用的输入参数和结果默认情况下不导出，因为它们可能包含敏感信息。

Spring AI 支持将工具调用参数和结果数据导出为 span 属性。

财产 描述 默认值

spring.ai.tools.observations.include-content

在观测中包含工具调用内容。true 或 false

假
如果您在观测中启用工具调用参数和结果的包含，存在暴露敏感或私人信息的风险。请务必小心！

嵌入模型

目前仅支持以下 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

模型输入（提示）中使用的令牌数量。

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

记录图像提示内容。true 或 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

查询返回的 top-k 最相似向量。

响应数据

向量搜索响应数据通常很大，可能包含敏感信息。因此，默认情况下不导出。

Spring AI 支持记录向量搜索响应数据，这对于故障排除场景很有用。当跟踪可用时，日志将包含跟踪信息，以便更好地进行关联。

财产 描述 默认值

spring.ai.vectorstore.observations.log-query-response

记录向量存储查询响应内容。true 或 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

参考资料

聊天客户端指标

指标名称 类型 单位 描述

gen_ai_chat_client_operation_seconds_sum

计时器

秒

ChatClient 操作（call/stream）中花费的总时间

gen_ai_chat_client_operation_seconds_count

计数器

计数

完成的 ChatClient 操作数量

gen_ai_chat_client_operation_seconds_max

量规

秒

ChatClient 操作的最大观测持续时间

gen_ai_chat_client_operation_active_count

量规

计数

当前正在进行的 ChatClient 操作数量

活动与完成: active_count 显示正在进行的调用；_seconds 系列仅反映已完成的调用。

聊天模型指标（模型提供商执行）

指标名称 类型 单位 描述

gen_ai_client_operation_seconds_sum

计时器

秒

执行聊天模型操作的总时间

gen_ai_client_operation_seconds_count

计数器

计数

完成的聊天模型操作数量

gen_ai_client_operation_seconds_max

量规

秒

聊天模型操作的最大观测持续时间

gen_ai_client_operation_active_count

量规

计数

当前正在进行的聊天模型操作数量

令牌使用

指标名称 类型 单位 描述

gen_ai_client_token_usage_total

计数器

令牌

消耗的总令牌数，按令牌类型标记

标签

标签 含义

gen_ai_token_type=input

发送到模型的提示令牌

gen_ai_token_type=output

模型返回的完成令牌

gen_ai_token_type=total

输入 + 输出

向量存储指标

指标名称 类型 单位 描述

db_vector_client_operation_seconds_sum

计时器

秒

向量存储操作（add/delete/query）中花费的总时间

db_vector_client_operation_seconds_count

计数器

计数

完成的向量存储操作数量

db_vector_client_operation_seconds_max

量规

秒

向量存储操作的最大观测持续时间

db_vector_client_operation_active_count

量规

计数

当前正在进行的向量存储操作数量

标签

标签 含义

db_operation_name

操作类型（add、delete、query）

db_system

向量数据库/提供商（redis、chroma、pgvector 等）

spring_ai_kind

vector_store

理解活动与完成

  • 活动 (*_active_count) — 正在进行的操作的瞬时量规（并发/负载）。

  • 已完成 (*_seconds_sum|count|max) — 已完成操作的统计数据

  • _seconds_sum / _seconds_count → 平均延迟

  • _seconds_max → 自上次抓取以来的最高水位线（受注册表行为影响）

© . This site is unofficial and not affiliated with VMware.