Spring AI可观测性实战：Metrics指标与Tracing链路追踪配置指南

本节目标：搞懂 Spring AI 的指标与链路追踪体系，学会用 Actuator、Micrometer、OpenTelemetry 观察 token 用量、延迟和错误，配置开箱即用的观测。

39.1 可观测性是什么

AI 应用上线后是黑盒。回答慢了、token 烧得快、调用报错，都看不到。可观测性就是给应用装仪表盘。

传统三件套：指标（Metrics）、链路追踪（Tracing）、日志（Logging）。

Spring AI 直接复用 Spring 生态的观测能力。核心组件全部埋点：ChatClient、Advisor、ChatModel、EmbeddingModel、ImageModel、VectorStore。底层是 Micrometer，追踪遵循 OpenTelemetry 规范。

埋点是自动的。组件接上调用链，观测就有，不用自己写拦截器。要做的只有两件事：加依赖、开端点。

39.2 先开启观测

观测不是默认全开的，要先加依赖。指标用 Actuator：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

追踪用 Micrometer Tracing 桥接 OpenTelemetry：

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-tracing-bridge-otel</artifactId>
</dependency>

再配置导出和端点暴露：

management.endpoints.web.exposure.include=health,metrics,prometheus
management.otlp.tracing.endpoint=http://localhost:4318/v1/traces

Tip

本地没有追踪后端，可以先看 /actuator/metrics。等部署 Prometheus 时，再加 prometheus 端点采集。

端点开好就能查了：

curl http://localhost:8080/actuator/metrics/gen_ai_client_token_usage_total

返回 JSON 里是按标签分组的计数。加 ?tag=gen_ai_token_type:output 只看输出 token。

39.3 指标长什么样

先认识两个概念：Timer 和 Counter。Timer 记耗时和次数，Counter 只累加。token 用量是 Counter，调用耗时是 Timer。分清楚再看指标名，不会乱。

Spring AI 的指标分几组，名字有规律。

ChatClient 层，记录每次 call/stream 的耗时：

指标	含义
`gen_ai_chat_client_operation_seconds_sum`	总耗时
`gen_ai_chat_client_operation_seconds_count`	调用次数
`gen_ai_chat_client_operation_seconds_max`	最大耗时
`gen_ai_chat_client_operation_active_count`	正在执行的调用数

ChatModel 层，指标名是 gen_ai_client_operation_*，标签带模型名、temperature 等参数。

Token 用量，看 gen_ai_client_token_usage_total，按 gen_ai_token_type 标签区分 input、output、total。

向量库层，指标名是 db_vector_client_operation_*，标签 db_operation_name 区分 add、delete、query。

命名规则：Micrometer 基础名用点，比如 gen_ai.client.operation。Prometheus 导出时换成下划线加后缀。Timer 带 _seconds_count、_seconds_sum、_seconds_max、_active_count，Counter 带 _total。

延迟怎么算

平均延迟 = _seconds_sum ÷ _seconds_count。_seconds_max 是两次采集之间的最大值。

_active_count 是瞬时值，反映当前并发。它和已完成的统计互补：一个是进行中，一个是已完成。

39.4 追踪：一次请求的全过程

指标回答”有多慢”，追踪回答”慢在哪一环”。一次问答请求，追踪里能看到：

ChatClient 调用（spring.ai.kind=chat_client）
Advisor 执行（spring.ai.kind=advisor，带 advisor 名称和 order）
模型调用（gen_ai.client.operation，带模型名、token 数）
工具调用（spring.ai.kind=tool_call）
向量库查询（spring.ai.kind=vector_store）

每个 span 都带标准属性。请求属性如 gen_ai.request.model、gen_ai.request.temperature，响应属性如 gen_ai.response.id、gen_ai.usage.total_tokens。

打开追踪后端，选中一条 trace，能看到从 ChatClient 到模型调用的完整瀑布图。哪一环耗时多少一目了然。工具调用、向量库查询都是独立 span，慢在哪一步立刻定位。

RAG 应用的链路尤其值得看。检索、增强、生成通常表现为多个 advisor span，回答慢的时候，能直接看出是检索慢还是模型慢。

Advisor 的执行也单独记观测，指标名在 spring.ai.advisor 下，带 advisor 名称和 order。自定义 advisor 不用额外埋点，接入调用链就自动有观测。

一个原则：低基数属性进指标和追踪，高基数属性只进追踪。模型名可以当指标标签，prompt 内容只能进追踪。

以 OpenAI、Anthropic 为例，模型调用还会产生 HTTP 层观测，携带请求方法、URI 和状态码。同步调用时，HTTP span 正确嵌套在模型 span 下面；流式调用时两者不嵌套，排查流式问题要留意。

开启追踪后，Spring AI 会在模型调用的 HTTP 请求上传播 traceparent 头。下游的 AI 网关、代理、推理服务都能串进同一条链路。排查”是模型服务端慢还是客户端慢”，就靠这个头。

39.5 观测覆盖范围

各组件不是都能观测的。EmbeddingModel 目前只有 Mistral AI、Ollama、OpenAI 三家支持；ImageModel 目前只有 OpenAI。

ChatModel 覆盖面广，主流厂商都已支持。选型前先确认自己的模型在不在支持列表里，省得接了没数据。

39.6 日志：第三件套

日志是传统三件套的最后一件。Spring AI 各层都有日志，配合追踪能带上 traceId，日志和链路能对上。

开启 log-prompt 后，请求内容会进日志。排查”模型为什么这么答”时，回看当时的提示词和上下文，比猜有效得多。

Note

日志里的提示词是排障利器，也是隐私风险。脱敏、限时保留、只对测试环境开，三选一至少做一样。

39.7 敏感内容默认不记录

prompt、回答、工具参数可能含敏感信息，默认不导出。排查问题需要时，按层开启：

spring.ai.chat.client.observations.log-prompt=true
spring.ai.chat.client.observations.log-completion=true
spring.ai.chat.observations.log-prompt=true
spring.ai.chat.observations.log-completion=true
spring.ai.tools.observations.include-content=true
spring.ai.vectorstore.observations.log-query-response=true

Note

开启内容记录有泄露风险。生产环境谨慎开启，最好只对测试环境开。

各层开关相互独立，需要排查哪层就开哪层。别图省事全开，数据量大，敏感内容也多。

错误排查开 spring.ai.chat.observations.include-error-logging=true，观测里会带上错误日志。配合追踪，一次调用从入口到出口的每一环都能回看。

39.8 关键指标怎么用

Token 用量。 gen_ai_client_token_usage_total 按 input/output 分开统计，乘以单价就是成本。RAG 应用重点看 input：检索上下文越长，输入 token 涨得越快。

工具调用。 工具调用的观测在 spring.ai.tool 下，gen_ai.operation.name 固定是 execute_tool。默认只记工具名和类型，参数和结果要开 include-content 才记录。

延迟。 看分位数，别只看平均。模型层延迟波动大，一次长生成会拉高整体。_seconds_sum ÷ _seconds_count 是平均，_seconds_max 看最坏情况。

错误率。 模型调用失败，从 HTTP 层观测的状态码统计。应用层错误开 include-error-logging 记录。错误率 = 错误次数 ÷ 总调用次数，分子来自日志或追踪，分母用 _seconds_count。

指标配好之后，就可以设告警：token 用量突增、延迟超阈值、错误率超过 1%，都值得盯。阈值先放宽松，观察一周再收紧。宁可漏报，不要误报刷屏。

39.9 完整配置示例

把上面散落的配置汇总成一份 application.yml：

spring:
  ai:
    chat:
      observations:
        log-prompt: false
        log-completion: false
management:
  endpoints:
    web:
      exposure:
        include: health,metrics,prometheus
  tracing:
    sampling:
      probability: 1.0
  otlp:
    tracing:
      endpoint: http://localhost:4318/v1/traces

指标走 Actuator 暴露，追踪走 OTLP 导出。采样率按流量调：生产流量大，probability 降到 0.1 就够，追踪成本可控。

怎么验证配置生效？改完重启应用，调一次问答，去 /actuator/metrics 看 gen_ai_client_operation_seconds_count 有没有加一。这是最快的验证方式。

39.10 小结

可观测性三件套：指标看性能、追踪看链路、日志看细节。Spring AI 对核心组件全部埋点，token 用量、延迟、错误都能查。敏感内容默认不记录，需要时按层开启。上线前把观测配好，排查问题能省一半时间。