可观测性

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-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 观测数据。 它们测量执行调用所花费的时间并传播相关的追踪信息。

Table 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。
Table 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.include-input 属性已弃用，由 spring.ai.chat.client.observations.log-prompt 取代。请参阅 _prompt_content。

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

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

属性 描述 默认值

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

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

false

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

聊天客户端顾问

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

Table 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。
Table 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 指标测量单个模型调用使用的输入和输出令牌数量。

Table 5. 低基数键
名称 描述

gen_ai.operation.name

正在执行的操作的名称。

gen_ai.system

由客户端仪表识别的模型提供商。

gen_ai.request.model

发出请求的模型名称。

gen_ai.response.model

生成响应的模型名称。
Table 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

false

spring.ai.chat.observations.log-completion

记录完成内容。true 或 false

false

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

在观测中包含错误日志。true 或 false

false

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

工具调用

spring.ai.tool 观测数据在聊天模型交互的上下文中执行工具调用时记录。它们测量工具调用完成所花费的时间并传播相关的追踪信息。

Table 7. 低基数键
名称 描述

gen_ai.operation.name

正在执行的操作的名称。始终为 framework。

gen_ai.system

负责操作的提供商。始终为 spring_ai。

spring.ai.kind

Spring AI 执行的操作类型。始终为 tool_call。

spring.ai.tool.definition.name

工具的名称。
Table 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

false

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

嵌入模型

可观测性功能目前仅支持来自以下 AI 模型提供商的 EmbeddingModel 实现： Azure OpenAI、Mistral AI、Ollama 和 OpenAI。 未来的版本将支持更多的 AI 模型提供商。

当调用嵌入模型的 gen_ai.client.operation 方法时，会记录观测数据。 它们测量方法完成所花费的时间并传播相关的追踪信息。

gen_ai.client.token.usage 指标测量单个模型调用使用的输入和输出令牌数量。

Table 9. 低基数键
名称 描述

gen_ai.operation.name

正在执行的操作的名称。

gen_ai.system

由客户端仪表识别的模型提供商。

gen_ai.request.model

发出请求的模型名称。

gen_ai.response.model

生成响应的模型名称。
Table 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 指标测量单个模型调用使用的输入和输出令牌数量。

Table 11. 低基数键
名称 描述

gen_ai.operation.name

正在执行的操作的名称。

gen_ai.system

由客户端仪表识别的模型提供商。

gen_ai.request.model

发出请求的模型名称。
Table 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

false

如果您启用图像提示数据的日志记录，则存在暴露敏感或私人信息的风险。请务必小心！

向量存储

Spring AI 中的所有向量存储实现都已进行仪表化，以通过 Micrometer 提供指标和分布式追踪数据。

当与向量存储交互时，会记录 db.vector.client.operation 观测数据。 它们测量 query、add 和 remove 操作所花费的时间并传播相关的追踪信息。

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

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 操作（调用/流）的总耗时

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

计时器

秒

向量存储操作（添加/删除/查询）的总耗时

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 → 自上次抓取以来的最高水位标记（取决于注册表行为）