可观测性：Tracing/日志/指标，定位为什么这次没跑通

可观测性要回答的三个问题

当一个 Skill/Agent 上线后，你迟早会遇到：

• 失败了：卡在哪一步？谁触发的？能否重试？
• 变贵了：哪一步调用次数暴涨？哪段上下文膨胀？
• 变慢了：是外部工具慢还是模型慢？是缓存 miss 还是限流？

可观测性就是把这些问题变成“看日志就能回答”。

Trace 的最小字段集（建议全链路一致）

建议你至少在每次请求/每次工具调用/每次模型调用里带这些字段：

• task_id：一次业务任务的唯一 ID
• run_id：一次执行实例（重试会不同）
• step_id：第几步
• skill_name / skill_version
• tool_name / tool_call_id
• user_id（如有）
• tenant_id（如有）
• budget_tokens / budget_cost
• latency_ms
• ok / error_type

这些字段决定了你是否能聚合统计与定位问题。

结构化日志：别写“自由文本”

日志建议输出 JSON（或等价结构），例如：

{
  "task_id": "t_123",
  "run_id": "r_456",
  "step_id": "s_03",
  "event": "tool_call",
  "tool_name": "github.get_pull_request",
  "latency_ms": 231,
  "ok": true
}

错误日志：

{
  "task_id": "t_123",
  "run_id": "r_456",
  "event": "tool_error",
  "tool_name": "github.get_pull_request",
  "ok": false,
  "error_type": "TOOL_RATE_LIMIT",
  "retryable": true
}

指标：先做 6 个就够用

上线初期，先把 6 个指标做出来：

• 成功率（per skill）
• 失败类型分布（INVALID_INPUT/TOOL_TIMEOUT/…）
• P50/P95 延迟（per skill、per tool）
• 平均调用次数（模型调用次数、工具调用次数）
• 平均成本（tokens/cost）
• 缓存命中率（如果有缓存）

这些指标能覆盖大部分运营与优化决策。

动手做：用“事件流”还原一次执行

建议你把一次执行拆成事件流：

• task_start
• model_call（可选：planning/generation）
• tool_call
• tool_result
• task_end

任何排障都能通过按 task_id 聚合事件流来回放发生了什么。

工程化清单

• trace 字段全链路一致（请求/模型/工具）
• 日志结构化（可聚合查询）
• 指标最小集合齐全（成功率、延迟、成本、调用次数）
• error_type 枚举化（便于统计与告警）

常见坑

• 只打“文本日志”：无法聚合统计，也很难回放
• tool_call 不记录参数与摘要：排障时无法复现（注意脱敏）
• 没有预算字段：成本失控后无法回溯原因

下一篇：安全与护栏：越权、注入、数据泄漏。