AI API 监控与可观测性建设指南：日志、追踪、告警完整体系设计

生产环境里，AI API 的失控方式比你想象的多：一个 prompt 模板改动导致 token 消耗翻倍，某个模型节点 P99 延迟突然从 2s 跳到 18s，计费账单月底才发现超出预算 3 倍——这些问题的共同根源是 AI API 监控与可观测性缺失。传统 HTTP 服务的监控思路套不进来，因为 AI 调用多了几个独特维度：prompt 内容、token 用量、模型版本、采样参数，每一个都可能是问题源头。这篇文章给出一套从日志到告警的完整设计方案。

结构化日志：prompt 与 response 的正确记录方式

最常见的错误是只记录 HTTP 状态码。AI API 的日志必须在结构化字段里捕获以下信息：

{
  "trace_id": "abc-123",
  "timestamp": "2026-06-15T10:23:01Z",
  "model": "claude-opus-4.8",
  "provider": "anthropic",
  "prompt_tokens": 842,
  "completion_tokens": 317,
  "total_tokens": 1159,
  "latency_ms": 2340,
  "status": "success",
  "finish_reason": "stop",
  "prompt_hash": "sha256:e3b0c4...",
  "user_id": "u_9912",
  "feature": "doc_summarizer"
}

几个设计决策值得说明：

prompt 内容不要明文存日志。原始 prompt 可能含用户 PII，存进 Elasticsearch 或 CloudWatch 是合规雷区。正确做法是存 prompt_hash（SHA-256 前 16 位足够做去重分析），完整 prompt 单独加密落到对象存储，按需检索。

feature 字段是成本归因的核心。同一个 GPT-5.4 调用，来自"文档摘要"还是"客服回复"，成本归属完全不同。没有这个字段，月底账单只是一个数字，无法拆解。

finish_reason 必须记录。length（触发 maxtokens 截断）出现频率超过 5% 通常意味着 prompt 设计有问题或 maxtokens 设置过低，这个指标只有日志层才能采集到。

日志框架选型上，Python 项目用 structlog + JSON handler，Node.js 用 pino，两者都能直接对接 Datadog / Grafana Loki。采样策略建议：正常流量 10% 采样，status=error 的请求 100% 保留。

分布式追踪：跨模型、跨服务的调用链路

单次用户请求往往触发多个 AI API 调用——RAG 先查向量库，再拼 prompt 调 Claude Sonnet 4.6 生成，最后可能再调 GPT-5.4-mini 做质量打分。这条链路如果没有 trace，出问题时根本不知道延迟在哪一段。

OpenTelemetry（OTel）是当前唯一值得押注的标准。核心配置：

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter

provider = TracerProvider()
provider.add_span_processor(
    BatchSpanProcessor(OTLPSpanExporter(endpoint="http://otel-collector:4317"))
)
trace.set_tracer_provider(provider)

tracer = trace.get_tracer("ai-service")

with tracer.start_as_current_span("llm_call") as span:
    span.set_attribute("llm.model", "claude-opus-4.8")
    span.set_attribute("llm.prompt_tokens", 842)
    span.set_attribute("llm.provider", "anthropic")
    response = client.messages.create(...)
    span.set_attribute("llm.completion_tokens", response.usage.output_tokens)

Span 属性命名建议遵循 OpenTelemetry Semantic Conventions for LLM 草案，字段前缀统一用 gen_ai.*，方便后续工具链自动识别。

追踪后端：自建可选 Jaeger + Tempo 组合；商业方案 Datadog APM 和 Honeycomb 对 LLM span 支持最成熟，Honeycomb 的 BubbleUp 功能能自动找出高延迟请求的共同属性，排查 prompt 模式问题特别有效。

核心 Metrics：延迟、Token、成功率的监控指标体系

以下是需要采集的指标清单，以及建议的聚合方式：

指标	类型	建议聚合	告警参考阈值
llm_request_duration_ms	Histogram	P50/P90/P99	P99 > 10s 触发 Warning
llm_tokens_total	Counter	by model, feature	日环比 > 50% 触发 Warning
llm_request_errors_total	Counter	by error_type	5min 错误率 > 2% 触发 Critical
llm_cost_usd	Counter	by model, feature	小时消费 > 预算 80% 触发 Warning
llm_finish_reason_length	Counter	占比	占比 > 5% 触发 Info
llm_context_utilization	Gauge	已用/最大 context	> 90% 触发 Warning

延迟监控有个常见陷阱：把首 token 延迟（TTFT，Time to First Token）和总延迟混为一谈。对于流式输出场景，用户感知的是 TTFT，而不是完整响应时间。GPT-5.5 和 Claude Opus 4.8 在高并发时 TTFT 差异可以达到 3-5 倍，只看总延迟会掩盖这个问题。Prometheus 采集 TTFT 需要在流式回调里打点，不能依赖 SDK 的默认计时。

成本指标的计算：各模型 token 单价不同，需要在 metrics 层做换算而不是在报表层。建议在 OTel Collector 的 processor 里注入一个 token→USD 的转换规则，这样 Grafana dashboard 直接显示美元成本，不需要每次查定价表。

告警策略：避免噪音与漏报的分级设计

告警设计最大的失败是所有问题都发 PagerDuty，两周后团队完全忽略告警。分级原则：

Critical（立即响应）：错误率 5 分钟内超 5%；API 完全不可用（连续 3 次健康检查失败）；单小时成本超过日预算上限。

Warning（工作时间处理）：P99 延迟连续 10 分钟超 10s；token 日消耗环比增长超 50%；finish_reason=length 占比超 5%。

Info（周期性回顾）：context 利用率趋势；新模型版本性能对比；各 feature 成本分布变化。

告警路由建议用 Alertmanager 的 route 树，Critical 走 PagerDuty + Slack，Warning 只发 Slack，Info 聚合进周报。告警消息里必须带 trace_id 或直接链到 Grafana 面板的查询 URL，否则 on-call 工程师收到告警第一件事是手动拼查询，效率极低。

一个容易忽视的告警：模型降级检测。当你同时接入 Claude Opus 4.8 和 Sonnet 4.6 做成本优化路由时，需要监控路由到低配模型的比例是否异常上升——这通常意味着旗舰模型节点出现问题，但错误率指标不一定会触发，因为请求本身是成功的。

工具链推荐与落地路径

完整的可观测性栈不需要一次性搭齐。推荐的落地顺序：

1. 第一周：接入结构化日志（structlog/pino），把 model、tokens、latency_ms、feature 四个字段覆盖所有 AI 调用。
2. 第二周：在日志基础上建 Grafana dashboard，先看延迟分布和 token 趋势，找到最贵的 feature。
3. 第三周：接入 OTel tracing，重点覆盖多步骤 AI 工作流。
4. 第四周：基于已有数据设定告警阈值，上线 Critical 级告警，并为团队做一次告警响应演练。

工具选型参考：日志存储用 Loki（成本低，适合中小规模）或 Elasticsearch（查询能力强，适合大规模）；metrics 用 Prometheus + Thanos（长期存储）；traces 用 Tempo 或 Jaeger；前端统一用 Grafana。如果预算允许且团队规模超过 10 人，Datadog 的一体化方案可以节省大量运维成本，其 LLM Observability 模块对 OpenAI 和 Anthropic SDK 有开箱即用的自动埋点。

---

在搭建这套体系时，API 的稳定性和成本可控性是两个绕不开的前提。我自己团队用的是 XycAi 词元平台——一个 OpenAI 兼容接口接入 200+ 模型，GPT-5.5、Claude Opus 4.8、Gemini 3 全系都有，官方价格的 1.4 折起，而且支持 Claude Code / Codex / Gemini CLI 直接接入，不用改工具链配置。持大模型算法备案号、可开全球发票，合规这块不用操心。监控做好了之后，成本控制的下一步其实就是选一个定价合理的 API 聚合入口。