Spring AI参考可观测性Spring AI 构建于 Spring 生态系统的可观测性特性之上以提供对 AI 相关操作的洞察。它为其核心组件提供指标和追踪能力ChatClient包括 Advisor、ChatModel、EmbeddingModel、ImageModel 和 VectorStore。请参阅 Spring Boot 指标和 Spring Boot 追踪文档以在您的应用中启用指标和追踪支持。低基数键将被添加到指标和追踪中而高基数键将仅被添加到追踪中。Chat Client当调用ChatClient的call()或stream()操作时会记录spring.ai.chat.client观测数据。它们测量执行调用所花费的时间并传播相关的追踪信息。表 1. 低基数键名称描述gen_ai.operation.name始终为framework。gen_ai.system始终为spring_ai。spring.ai.chat.client.stream聊天模型响应是否为流式 -true或falsespring.ai.kindSpring AI 中的框架 API 类型chat_client。表 2. 高基数键名称描述spring.ai.chat.client.advisors已配置的聊天客户端顾问列表。spring.ai.chat.client.conversation.id使用聊天记忆时的会话标识符。spring.ai.chat.client.tool.names传递给聊天客户端的工具名称。提示和补全数据ChatClient 的提示和补全数据通常较大且可能包含敏感信息。因此默认情况下不会导出。Spring AI 支持记录提示和补全数据以帮助调试和故障排查。属性描述默认值spring.ai.chat.client.observations.log-prompt是否记录聊天客户端的提示内容。falsespring.ai.chat.client.observations.log-completion是否记录聊天客户端的补全内容。false如果启用聊天客户端提示和补全数据的日志记录存在暴露敏感或私人信息的风险。请谨慎操作Chat Client Advisors当执行 advisor 时会记录spring.ai.advisor观测数据。它们测量在 advisor 中花费的时间包括在内部 advisor 上花费的时间并传播相关的追踪信息。表 3. 低基数键名称描述gen_ai.operation.name始终为framework。gen_ai.system始终为spring_ai。spring.ai.advisor.nameAdvisor 的名称。spring.ai.kindSpring AI 中的框架 API 类型advisor。表 4. 高基数键名称描述spring.ai.advisor.orderAdvisor 在顾问链中的顺序。Chat ModelOpenAI 和 Anthropic 聊天模型都会发出 HTTP 层观测数据chat-model 层 HTTP 层但流式调用有一个限制。HTTP 层观测数据携带 HTTP 方法、URI、状态码并将traceparent通过线路传播到下游服务AI 网关、代理、兼容 OpenAI 的推理服务器。对于同步调用okhttp.requestsspan 正确地嵌套在gen_ai.client.operationspan 下。对于流式调用HTTP span 会被记录但不会作为 chat-model span 的父级——SDK 的异步流式路径在调用 Spring AI 的 HTTP 客户端之前会跳转到ForkJoinPool.commonPool()从而在该边界丢失调用线程的观测上下文。有关详细信息请参阅 OpenAI 聊天文档和 Anthropic 聊天文档。当调用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.stream请求是否以流式模式发出。仅当为true时存在。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.idAI 响应的唯一标识符。gen_ai.usage.cache_creation.input_tokens写入提供商管理缓存的输入令牌数。gen_ai.usage.cache_read.input_tokens从提供商管理缓存提供的输入令牌数。gen_ai.usage.input_tokens模型输入提示中使用的令牌数。gen_ai.usage.output_tokens模型输出补全中使用的令牌数。gen_ai.usage.total_tokens模型交换中使用的总令牌数。spring.ai.model.request.tool.names请求中提供给模型的工具定义列表。对于测量用户令牌上表列出了观测追踪中存在的值。使用由 ChatModel 提供的指标名称gen_ai.client.token.usage。聊天提示和补全数据聊天提示和补全数据通常较大且可能包含敏感信息。因此默认情况下不会导出。Spring AI 支持记录聊天提示和补全数据对故障排查场景很有用。当追踪可用时日志将包含追踪信息以便更好地关联。属性描述默认值spring.ai.chat.observations.log-prompt记录提示内容。true或falsefalsespring.ai.chat.observations.log-completion记录补全内容。true或falsefalsespring.ai.chat.observations.include-error-logging在观测中包含错误日志记录。true或falsefalse如果启用聊天提示和补全数据的日志记录存在暴露敏感或私人信息的风险。请谨慎操作Tool Calling在聊天模型交互的上下文中执行工具调用时会记录spring.ai.tool观测数据。它们测量工具调用完成所花费的时间并传播相关的追踪信息。表 7. 低基数键名称描述gen_ai.operation.name正在执行的操作的名称。始终为execute_tool。gen_ai.system负责该操作的提供商。始终为spring_ai。spring.ai.kindSpring AI 执行的操作类型。始终为tool_call。spring.ai.tool.definition.name工具的名称。spring.ai.tool.type工具的类型。默认情况下为function。表 8. 高基数键名称描述spring.ai.tool.definition.description工具的描述。spring.ai.tool.definition.schema用于调用工具的参数的架构。spring.ai.tool.call.id由聊天模型标识的工具调用 ID。spring.ai.tool.call.arguments工具调用的输入参数。仅在启用时spring.ai.tool.call.result工具调用执行的结果。仅在启用时工具调用参数和结果数据默认情况下不会导出工具调用的输入参数和结果因为它们可能具有潜在的敏感性。Spring AI 支持将工具调用参数和结果数据导出为 span 属性。属性描述默认值spring.ai.tools.observations.include-content在观测中包含工具调用内容。true或falsefalse如果启用在观测中包含工具调用参数和结果存在暴露敏感或私人信息的风险。请谨慎操作EmbeddingModel可观测性特性目前仅支持来自以下 AI 模型提供商的 EmbeddingModel 实现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。Image Model可观测性特性目前仅支持来自以下 AI 模型提供商的 ImageModel 实现OpenAI。其他 AI 模型提供商将在未来版本中得到支持。在图像模型方法调用时会记录gen_ai.client.operation观测数据。它们测量方法完成所花费的时间并传播相关的追踪信息。表 11. 低基数键名称描述gen_ai.operation.name正在执行的操作的名称。gen_ai.system由客户端仪表化标识的模型提供商。gen_ai.request.model请求所指向的模型名称。表 12. 高基数键名称描述gen_ai.request.image.response_format返回生成图像的格式。gen_ai.request.image.size要生成的图像大小例如 1024x1024。gen_ai.request.image.style要生成的图像风格。图像提示数据图像提示数据通常较大且可能包含敏感信息。因此默认情况下不会导出。Spring AI 支持记录图像提示数据对故障排查场景很有用。当追踪可用时日志将包含追踪信息以便更好地关联。属性描述默认值spring.ai.image.observations.log-prompt记录图像提示内容。true或falsefalse如果启用图像提示数据的日志记录存在暴露敏感或私人信息的风险。请谨慎操作Vector StoresSpring AI 中的所有向量存储实现都通过 Micrometer 进行了仪表化以提供指标和分布式追踪数据。在与向量存储交互时会记录db.vector.client.operation观测数据。它们测量查询、添加和删除操作所花费的时间并传播相关的追踪信息。表 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、simple。spring.ai.kindSpring AI 中的框架 API 类型vector_store。表 14. 高基数键名称描述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 个向量。响应数据默认情况下不会导出向量搜索响应数据因为它通常较大且可能包含敏感信息。Spring AI 支持记录向量搜索响应数据对故障排查场景很有用。当追踪可用时日志将包含追踪信息以便更好地关联。属性描述默认值spring.ai.vectorstore.observations.log-query-response记录向量存储查询响应内容。true或falsefalse如果启用向量搜索响应数据的日志记录存在暴露敏感或私人信息的风险。请谨慎操作更多指标参考本节记录了 Spring AI 组件在 Prometheus 中出现的指标。指标命名约定Spring AI 使用 Micrometer。基础指标名称使用点号例如gen_ai.client.operationPrometheus 导出时使用下划线和标准后缀计时器 →base_seconds_count、base_seconds_sum、base_seconds_max以及当支持时base_active_count计数器 →base_total单调递增下表显示了基础指标名称如何扩展为 Prometheus 时间序列。基础指标名称导出的时间序列gen_ai.client.operationgen_ai_client_operation_seconds_countgen_ai_client_operation_seconds_sumgen_ai_client_operation_seconds_maxgen_ai_client_operation_active_countdb.vector.client.operationdb_vector_client_operation_seconds_countdb_vector_client_operation_seconds_sumdb_vector_client_operation_seconds_maxdb_vector_client_operation_active_count参考OpenTelemetry — 生成式 AI 语义约定概述Micrometer — 指标命名Chat Client 指标指标名称类型单位描述gen_ai_chat_client_operation_seconds_sumTimer秒ChatClient 操作call/stream花费的总时间gen_ai_chat_client_operation_seconds_countCounter计数已完成的 ChatClient 操作数gen_ai_chat_client_operation_seconds_maxGauge秒ChatClient 操作的最大观测持续时间gen_ai_chat_client_operation_active_countGauge计数当前正在进行的 ChatClient 操作数活跃与已完成active_count显示正在进行的调用_seconds系列仅反映已完成的调用。Chat Model 指标模型提供商执行指标名称类型单位描述gen_ai_client_operation_seconds_sumTimer秒执行聊天模型操作的总时间gen_ai_client_operation_seconds_countCounter计数已完成的聊天模型操作数gen_ai_client_operation_seconds_maxGauge秒聊天模型操作的最大观测持续时间gen_ai_client_operation_active_countGauge计数当前正在进行的聊天模型操作数Token 用量指标名称类型单位描述gen_ai_client_token_usage_totalCounter令牌消耗的总令牌数按令牌类型标记标签标签含义gen_ai_token_typeinput发送给模型的提示令牌gen_ai_token_typeoutput模型返回的补全令牌gen_ai_token_typetotal输入 输出Vector Store 指标指标名称类型单位描述db_vector_client_operation_seconds_sumTimer秒向量存储操作add/delete/query花费的总时间db_vector_client_operation_seconds_countCounter计数已完成的向量存储操作数db_vector_client_operation_seconds_maxGauge秒向量存储操作的最大观测持续时间db_vector_client_operation_active_countGauge计数当前正在进行的向量存储操作数标签标签含义db_operation_name操作类型add、delete、querydb_system向量数据库/提供商redis、chroma、pgvector 等spring_ai_kindvector_store理解活跃与已完成活跃*_active_count—— 正在进行中的操作的瞬时仪表化并发/负载。已完成*_seconds_sum|count|max—— 已结束操作的统计信息_seconds_sum / _seconds_count→ 平均延迟_seconds_max→ 自上次抓取以来的最高水位线受注册表行为影响
