可观测性

约 3337 字大约 11 分钟

2026-09-15

📌 原文地址：https://docs.spring.io/java-ai/reference/observability/index.html 📌 原文版本：Java AI 2.0.1

Java AI 构建于 Spring 生态系统的可观测性功能之上，用于提供对 AI 相关操作的洞察。它为核心组件提供指标（metrics）和链路追踪（tracing）能力：ChatClient（包括 Advisor）、ChatModel、EmbeddingModel、ImageModel 和 VectorStore。

请参考 Spring Boot Metrics 和 Spring Boot Tracing 文档以在你的应用程序中启用指标和追踪支持。

白话解读

指标（Metrics） 回答"现在/过去一段时间发生了什么"——比如每秒调用多少、平均延迟多少、token 用了多少；适合做监控和告警。 链路追踪（Tracing） 回答"一次请求在系统内部怎么流转"——比如一次 Chat 调用经过了哪几个 Advisor、用时分布；适合排查具体慢调用。

低基数 vs 高基数

低基数（low-cardinality）的键会同时出现在指标和追踪中（比如 gen_ai.system 取值只有几个），适合作为指标维度；高基数（high-cardinality）的键（如 db.vector.query.content 等可能因每次请求都不同的字段）只出现在追踪中，避免指标维度爆炸。

Chat Client（聊天客户端）

调用 ChatClient 的 call() 或 stream() 操作时，会记录 spring.ai.chat.client 观测（observations）。它们测量执行调用所花费的时间，并传播相关的追踪信息。

表 1. 低基数键（Low Cardinality Keys）

Name	Description
`gen_ai.operation.name`	始终为 `framework`
`gen_ai.system`	始终为 `spring_ai`
`spring.ai.chat.client.stream`	聊天模型响应是否为流式（`true` 或 `false`）
`spring.ai.kind`	Java AI 中的框架 API 类型：`chat_client`

表 2. 高基数键（High Cardinality Keys）

Name	Description
`spring.ai.chat.client.advisors`	已配置的聊天客户端 advisor 列表
`spring.ai.chat.client.conversation.id`	使用聊天记忆时的会话标识符
`spring.ai.chat.client.tool.names`	传递给聊天客户端的工具名称

提示词与完成数据（Prompt and Completion Data）

ChatClient 的提示词（prompt）和完成（completion）数据通常很大，并且可能包含敏感信息。因此，默认情况下不会导出它们。

Java AI 支持记录提示词和完成数据，以帮助调试和故障排除：

属性	描述	默认值
`spring.ai.chat.client.observations.log-prompt`	是否记录聊天客户端的提示词内容	`false`
`spring.ai.chat.client.observations.log-completion`	是否记录聊天客户端的完成内容	`false`

谨慎启用

如果启用了聊天客户端提示词和完成数据的记录，会存在暴露敏感或私密信息的风险，请务必谨慎！

Chat Client Advisors（聊天客户端 Advisor）

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

表 3. 低基数键（Low Cardinality Keys）

Name	Description
`gen_ai.operation.name`	始终为 `framework`
`gen_ai.system`	始终为 `spring_ai`
`spring.ai.advisor.name`	Advisor 的名称
`spring.ai.kind`	Java AI 中的框架 API 类型：`advisor`

表 4. 高基数键（High Cardinality Keys）

Name	Description
`spring.ai.advisor.order`	Advisor 链中的 Advisor 顺序

Chat Model（聊天模型）

OpenAI 和 Anthropic 聊天模型都会发出 HTTP 层观测（聊天模型层 + HTTP 层），但对于流式调用存在一个特定的限制。HTTP 层观测携带 HTTP 方法、URI、状态码，并在网络中向下游服务（AI 网关、代理、OpenAI 兼容的推理服务器）传递 traceparent。

对于同步调用，okhttp.requests span 正确嵌套在 gen_ai.client.operation span 之下。对于流式调用，HTTP span 会被记录，但不会作为聊天模型 span 的子 span —— SDK 的异步流式路径在调用 Java AI 的 HTTP 客户端之前会跳转到 ForkJoinPool.commonPool()，从而在那个边界丢弃了调用线程的观测上下文。

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

gen_ai.client.token.usage 指标衡量单次模型调用所使用的输入和输出 token 数量。

表 5. 低基数键（Low Cardinality Keys）

Name	Description
`gen_ai.operation.name`	正在执行的操作的名称
`gen_ai.system`	由客户端检测识别的模型提供者
`gen_ai.request.model`	正在发出请求的模型的名称
`gen_ai.response.model`	生成响应的模型的名称

表 6. 高基数键（High Cardinality Keys）

Name	Description
`gen_ai.request.frequency_penalty`	模型请求的 frequency_penalty 设置
`gen_ai.request.max_tokens`	模型为请求生成的最大 token 数
`gen_ai.request.presence_penalty`	模型请求的 presence_penalty 设置
`gen_ai.request.stop_sequences`	模型将使用以停止生成更多 token 的序列列表
`gen_ai.request.stream`	请求是否以流模式发出（仅在为 `true` 时出现）
`gen_ai.request.temperature`	模型请求的 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.cache_creation.input_tokens`	写入到提供者管理缓存的输入 token 数
`gen_ai.usage.cache_read.input_tokens`	从提供者管理缓存中提供的输入 token 数
`gen_ai.usage.input_tokens`	模型输入（提示词）中使用的 token 数
`gen_ai.usage.output_tokens`	模型输出（完成）中使用的 token 数
`gen_ai.usage.total_tokens`	模型交互中使用的总 token 数
`spring.ai.model.request.tool.names`	请求中提供给模型的工具定义列表

为衡量用户 token，前述表格列出了观测追踪中出现的值。请使用由 ChatModel 提供的指标名称 gen_ai.client.token.usage。

聊天提示词与完成数据（Chat Prompt and Completion Data）

聊天提示词和完成数据通常很大，并且可能包含敏感信息。因此，默认情况下不会导出它们。

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

谨慎启用

如果启用了聊天提示词和完成数据的记录，会存在暴露敏感或私密信息的风险，请务必谨慎！

Tool Calling（工具调用）

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

表 7. 低基数键（Low Cardinality Keys）

Name	Description
`gen_ai.operation.name`	正在执行的操作的名称，始终为 `execute_tool`
`gen_ai.system`	负责该操作的提供者，始终为 `spring_ai`
`spring.ai.kind`	由 Java AI 执行的操作类型，始终为 `tool_call`
`spring.ai.tool.definition.name`	工具的名称
`spring.ai.tool.type`	工具的类型（默认 `function`）

表 8. 高基数键（High Cardinality Keys）

Name	Description
`spring.ai.tool.definition.description`	工具的描述
`spring.ai.tool.definition.schema`	用于调用工具的参数 schema
`spring.ai.tool.call.id`	工具调用的 ID，由聊天模型识别
`spring.ai.tool.call.arguments`	工具调用的输入参数（仅在启用时）
`spring.ai.tool.call.result`	工具调用执行的结果（仅在启用时）

工具调用参数和结果数据

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

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

属性	描述	默认值
`spring.ai.tools.observations.include-content`	在观测中包含工具调用内容（`true` / `false`）	`false`

谨慎启用

启用后可能暴露敏感或私密信息，请务必谨慎！

EmbeddingModel（嵌入模型）

当前支持范围

目前仅来自以下 AI 模型提供者的 EmbeddingModel 实现支持可观测性功能：Mistral AI、Ollama 和 OpenAI。其他 AI 模型提供者将在未来版本中得到支持。

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

gen_ai.client.token.usage 指标衡量单次模型调用所使用的输入和输出 token 数量。

表 9. 低基数键（Low Cardinality Keys）

Name	Description
`gen_ai.operation.name`	正在执行的操作的名称
`gen_ai.system`	由客户端检测识别的模型提供者
`gen_ai.request.model`	正在发出请求的模型的名称
`gen_ai.response.model`	生成响应的模型的名称

表 10. 高基数键（High Cardinality Keys）

Name	Description
`gen_ai.request.embedding.dimensions`	结果输出 embeddings 具有的维度数
`gen_ai.usage.input_tokens`	模型输入中使用的 token 数
`gen_ai.usage.total_tokens`	模型交互中使用的总 token 数

Image Model（图像模型）

当前支持范围

目前仅来自以下 AI 模型提供者的 ImageModel 实现支持可观测性功能：OpenAI。其他 AI 模型提供者将在未来版本中得到支持。

在图像模型方法调用上记录 gen_ai.client.operation 观测。它们测量方法完成所花费的时间，并传播相关的追踪信息。

表 11. 低基数键（Low Cardinality Keys）

Name	Description
`gen_ai.operation.name`	正在执行的操作的名称
`gen_ai.system`	由客户端检测识别的模型提供者
`gen_ai.request.model`	正在发出请求的模型的名称

表 12. 高基数键（High Cardinality Keys）

Name	Description
`gen_ai.request.image.response_format`	返回的生成图像的格式
`gen_ai.request.image.size`	要生成的图像的大小（例如 1024x1024）
`gen_ai.request.image.style`	要生成的图像的风格

图像提示词数据（Image Prompt Data）

图像提示词数据通常很大，并且可能包含敏感信息，因此默认不导出。

Java AI 支持记录图像提示词数据，可用于故障排除场景：

属性	描述	默认值
`spring.ai.image.observations.log-prompt`	记录图像提示词内容（`true` / `false`）	`false`

谨慎启用

启用后可能暴露敏感或私密信息，请务必谨慎！

Vector Stores（向量存储）

Java AI 中的所有向量存储实现均已加入检测（instrumentation），以通过 Micrometer 提供指标和分布式追踪数据。

在与向量存储交互时记录 db.vector.client.operation 观测。它们测量查询、添加和移除操作所花费的时间，并传播相关的追踪信息。

表 13. 低基数键（Low Cardinality Keys）

Name	Description
`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`	Java AI 中的框架 API 类型：`vector_store`

表 14. 高基数键（High Cardinality Keys）

Name	Description
`db.collection.name`	数据库中集合（表、容器）的名称
`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 最相似向量

响应数据（Response Data）

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

Java AI 支持记录向量搜索响应数据，可用于故障排除场景：

属性	描述	默认值
`spring.ai.vectorstore.observations.log-query-response`	记录向量存储查询响应内容（`true` / `false`）	`false`

谨慎启用

启用后可能暴露敏感或私密信息，请务必谨慎！

更多指标参考（More Metrics Reference）

本节按 Prometheus 中的呈现方式记录 Java AI 组件发出的指标。

指标命名约定（Metric Naming Conventions）

Java AI 使用 Micrometer。基础指标名称使用点（例如 gen_ai.client.operation），Prometheus 导出时使用下划线和标准后缀：

Timers（计时器） → <base>_seconds_count、<base>_seconds_sum、<base>_seconds_max，以及（在受支持时）<base>_active_count
Counters（计数器） → <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 操作（call/stream）中花费的总时间
`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 vs Completed：active_count 显示正在进行的调用；_seconds 系列仅反映已完成的调用。

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	当前正在进行的聊天模型操作数

Token 使用情况（Token Usage）

指标名称	类型	单位	描述
`gen_ai_client_token_usage_total`	Counter	tokens	消耗的总 token 数，按 token 类型标记

标签（Labels）

Label	含义
`gen_ai_token_type=input`	发送到模型的提示词 token
`gen_ai_token_type=output`	模型返回的完成 token
`gen_ai_token_type=total`	输入 + 输出

Vector Store 指标

指标名称	类型	单位	描述
`db_vector_client_operation_seconds_sum`	Timer	seconds	向量存储操作（add/delete/query）中花费的总时间
`db_vector_client_operation_seconds_count`	Counter	count	已完成的向量存储操作数
`db_vector_client_operation_seconds_max`	Gauge	seconds	向量存储操作观察到的最大持续时间
`db_vector_client_operation_active_count`	Gauge	count	当前正在进行的向量存储操作数

标签（Labels）

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

Observability 章节只有一个长页面，无独立子页面。

版权所有

版权归属：今朝· Liushigong · Relax Box

许可证：署名-非商业性 4.0 国际 (CC-BY-NC-4.0)