当你的 AI Coding Agent 在生产环境跑了三天，突然开始大量失败——你能快速定位是模型问题、工具问题还是任务设计问题吗？如果答案不确定，说明你缺的不是更多的 Prompt 调优，而是一套可观测性基础设施。
大多数关于 AI Coding Agent 的讨论集中在”怎么用”——如何写 Prompt、如何设计 Agent 架构、如何做自修正。但当你真正把 Agent 部署到生产环境一段时间后，会发现一个更根本的问题：你看不见它里面发生了什么。
传统软件的监控方案——日志、指标、链路追踪——对于确定性系统很有效。但 AI Coding Agent 的执行过程是动态的思维链推理，每一步都可能选择不同的工具、走向不同的路径。传统的 APM（应用性能监控）工具不知道如何描述这个过程。
本文整理了我在生产级 AI Agent 项目中建立可观测性系统的完整方案，涵盖 Trace 结构设计、Structured Logging 生产实践、指标体系、告警规则和监控面板。
一、为什么 AI Coding Agent 特别需要可观测性
1.1 传统软件 vs AI Agent 的可观测性差异
传统软件的执行路径是确定性的：
用户请求 → 已知路径的代码逻辑 → 返回结果
日志：输入参数、关键节点状态、输出结果、耗时
异常：堆栈跟踪明确指向故障位置
AI Coding Agent 的执行路径是动态生成的：
用户任务 → 思维链推理 → 工具选择 → 工具执行 → 结果评估 → 继续或停止
日志：推理过程、选择原因、工具参数、工具结果、评估结论
异常：可能是推理路径错误，也可能是工具执行失败，也可能是任务设计本身有问题
关键差异：传统软件的异常有明确的堆栈定位；AI Agent 的”异常”可能是一次不当的推理跳跃，一个选错了的工具，或一个不合理的假设前提。这些都不是代码 bug，而是决策质量问题。
1.2 可观测性缺失的典型症状
我在多个项目里见过这些场景：
症状 A：「Agent 三天前还好好的，今天突然开始失败」
→ 没有实时指标，无法判断是新任务问题、模型问题还是工具问题
症状 B：「这个任务跑了 200 步才完成，Token 消耗破表」
→ 没有步骤级 Trace，不知道 Agent 在哪一步卡住了
症状 C：「用户反映 Agent 给的代码有问题，但复现不出来」
→ 没有完整的决策记录，不知道 Agent 当时的推理路径
症状 D：「Claude Code 和 Cursor 哪个更适合我们团队？」
→ 没有统一的评估数据，所有判断都是主观的
这些问题都在说同一件事：你需要一个能看到 Agent 内部状态的系统。
二、AI Coding Agent 的 Trace 结构设计
2.1 四层 Trace 模型
我把 AI Coding Agent 的 Trace 设计为四个层级，每个层级捕捉不同粒度的信息：
┌─────────────────────────────────────────┐
│ Task Trace（任务级） │
│ 完整任务的生命周期，顶级视图 │
├─────────────────────────────────────────┤
│ Step Traces（步骤级） │
│ 思维链 + 工具调用的组合单元 │
├─────────────────────────────────────────┤
│ Tool Call Traces（工具调用级） │
│ 单个工具的输入、输出、状态 │
├─────────────────────────────────────────┤
│ Decision Traces（决策级） │
│ 关键决策点的选项、推理、确认状态 │
└─────────────────────────────────────────┘
2.2 Task Trace 的标准结构
Task Trace 是整个 Trace 树的根节点，记录一个完整任务的生命周期：
{
"trace_id": "trace-2026-04-18-7f3a2c",
"task_id": "task-8841",
"session_id": "sess-abc123",
"agent_id": "claude-code-primary",
"timestamp_start": "2026-04-18T10:00:00Z",
"timestamp_end": "2026-04-18T10:08:42Z",
"task": {
"description": "将用户认证模块从单体应用拆分为独立微服务",
"type": "refactoring",
"scope": "large",
"files_affected": ["auth.py", "middleware.py", "models.py", "config.py"],
"user_id": "engineer-001"
},
"outcome": {
"status": "completed_with_warnings",
"steps_taken": 23,
"steps_successful": 21,
"steps_failed": 2,
"self_corrections": 3,
"user_interventions": 1,
"issues_flagged": ["test_coverage_incomplete", "error_handling_missing_in_2_places"]
},
"cost": {
"input_tokens": 89450,
"output_tokens": 31280,
"total_tokens": 120730,
"estimated_cost_usd": 0.48
},
"latency": {
"total_ms": 522000,
"avg_step_ms": 22782,
"p50_step_ms": 15200,
"p95_step_ms": 58000,
"p99_step_ms": 120000
}
}
2.3 Step Trace 的标准结构
Step Trace 记录 Agent 的每一步推理和工具调用组合：
{
"trace_id": "trace-2026-04-18-7f3a2c",
"step_id": "step-008",
"step_number": 8,
"timestamp": "2026-04-18T10:03:45Z",
"reasoning": {
"thinking": "当前用户认证逻辑分散在三个文件中，需要先梳理完整的调用关系图。\
有两个方案：(A) 逐步拆分，每次改一个文件；(B) 先建新服务框架，再迁移代码。\
考虑到风险控制和可回滚性，选择方案 A。",
"confidence": 0.85,
"uncertainty_noted": "不确定是否有其他文件间接依赖认证逻辑"
},
"tool_calls": [
{
"tool": "grep",
"args": {"pattern": "def.*auth.*\\(", "path": "./src"},
"status": "success",
"result_summary": "找到 12 个认证相关函数"
},
{
"tool": "read",
"args": {"files": ["auth.py", "middleware.py"]},
"status": "success"
}
],
"decision": {
"description": "选择方案 A（逐步拆分）而非方案 B（新服务框架）",
"alternatives": ["方案B：新服务框架", "方案C：引入认证中间件"],
"reasoning": "风险最低，支持小步提交和快速回滚",
"user_confirmed": false,
"assumptions": ["调用关系图准确", "没有隐藏的循环依赖"]
},
"outcome": {
"status": "success",
"tools_used": ["grep", "read"],
"tokens_consumed": 4520,
"step_duration_ms": 8500
}
}
2.4 Decision Trace 的标准结构
Decision Trace 专门记录关键决策点，是后续复盘和优化的核心数据：
{
"trace_id": "trace-2026-04-18-7f3a2c",
"decision_id": "dec-004",
"step_number": 8,
"timestamp": "2026-04-18T10:03:50Z",
"decision_point": "认证模块重构策略选择",
"alternatives_considered": [
{
"option": "A - 逐步拆分",
"pros": ["风险低", "可回滚", "每次改动小"],
"cons": ["耗时长", "需要多次集成"],
"estimated_steps": 15
},
{
"option": "B - 新服务框架",
"pros": ["干净", "独立部署"],
"cons": ["风险高", "需要迁移所有调用方"],
"estimated_steps": 8
}
],
"selected": "A - 逐步拆分",
"reasoning": "考虑到这是生产系统的核心认证模块，选择风险最低的方案。\
新服务框架虽然架构更干净，但迁移成本和集成测试成本不可控。\
逐步拆分虽然慢，但每一步都可以验证和回滚。",
"assumptions": [
"调用关系图完整",
"测试覆盖率足够发现迁移问题"
],
"assumptions_validated": false,
"validation_method": null,
"user_confirmed": false,
"auto_proceed_reason": "单文件小范围改动，属于 L2 决策权限"
}
Decision Trace 的实战价值：
- 当任务失败时，可以回溯到具体的决策点
- 当某个决策模式反复出现，可以抽象为团队规范
- 可以量化 Agent 的决策质量趋势
三、Structured Logging 的生产实践
3.1 面向 AI Agent 的日志级别
传统日志级别不足以描述 AI Agent 的运行状态。我扩展了标准级别：
TRACE - 思维链完整推理过程（仅本地调试，不进入日志收集系统）
DEBUG - 步骤详情、工具参数（开发环境）
INFO - 步骤完成、工具调用结果、关键决策
WARNING - 工具调用失败但已恢复、假设前提不满足、Token 消耗异常
ERROR - 工具调用失败且无法恢复、关键路径异常
CRITICAL- 灾难性故障：数据损坏、安全突破、系统不可用
关键原则：AI Agent 的 ERROR 日志必须包含完整的推理上下文。Agent 的错误和传统软件的错误不同——它可能是推理路径错误，而不是代码执行错误。
3.2 统一日志格式
{
"timestamp": "2026-04-18T10:05:32.421Z",
"level": "INFO",
"trace_id": "trace-2026-04-18-7f3a2c",
"step_id": "step-012",
"agent_id": "claude-code-primary",
"service": "ai-coding-agent",
"message": "Tool execution completed",
"tool": "exec",
"tool_args": {
"command": "pytest tests/auth/ -v",
"cwd": "/project"
},
"tool_result": {
"status": "failed",
"exit_code": 1,
"stdout": "...2 passed, 1 failed...",
"stderr": "ERROR: test_auth_token_expiry"
},
"recovery": {
"attempted": true,
"strategy": "retry_with_debug",
"result": "recovered"
},
"tokens": {
"input": 3240,
"output": 890,
"total": 4130
}
}
所有日志使用统一格式，便于后续结构化查询和聚合分析。
3.3 敏感信息过滤
AI Coding Agent 的日志会记录工具参数和输出，其中可能包含敏感信息。必须在日志写入前完成过滤：
import re
import logging
SENSITIVE_PATTERNS = [
(r'password\s*[=:]\s*["\']([^"\']{1,50})["\']', 'password=***'),
(r'api[_-]?key\s*[=:]\s*["\']([^"\']{1,80})["\']', 'api_key=***'),
(r'secret[_-]?token\s*[=:]\s*["\']([^"\']{1,80})["\']', 'secret_token=***'),
(r'bearer\s+([A-Za-z0-9\-_.]{10,})', 'bearer ***'),
(r'-----BEGIN.*?-----[\s\S]*?-----END.*?-----', '[PRIVATE KEY REDACTED]'),
(r'eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+', '[JWT REDACTED]'),
]
def sanitize_for_logging(content: str) -> str:
"""Remove sensitive information from log content."""
if not isinstance(content, str):
return content
result = content
for pattern, replacement in SENSITIVE_PATTERNS:
result = re.sub(pattern, replacement, result, flags=re.IGNORECASE)
return result
class SensitiveFilter(logging.Filter):
def filter(self, record):
if isinstance(record.msg, dict):
record.msg = {k: sanitize_for_logging(str(v)) for k, v in record.msg.items()}
elif isinstance(record.msg, str):
record.msg = sanitize_for_logging(record.msg)
return True
3.4 Trace ID 跨系统传播
当 Agent 调用外部 MCP Server 时，Trace 必须跨越系统边界：
Agent 进程
trace_id: trace-001
├── MCP Server A (span: span-A1, trace_id: trace-001)
│ └── Tool X 执行 (trace_id: trace-001, span: span-A1-x)
└── MCP Server B (span: span-B1, trace_id: trace-001)
└── Tool Y 执行 (trace_id: trace-001, span: span-B1-y)
实现方式：在 MCP 工具调用参数中注入 trace_id，或在 HTTP 场景下通过 header 传播。
四、生产级指标体系
4.1 三层指标模型
┌─────────────────────────────────────────────────────────┐
│ 任务层指标（Task-level） │
│ 面向业务：任务完成率、耗时分布、成本 │
├─────────────────────────────────────────────────────────┤
│ 步骤层指标（Step-level） │
│ 面向执行效率：步数分布、自修正率、Token密度 │
├─────────────────────────────────────────────────────────┤
│ 工具层指标（Tool-level） │
│ 面向可靠性：工具调用成功率、平均耗时、失败类型分布 │
└─────────────────────────────────────────────────────────┘
4.2 核心指标定义
# 任务层
task_completion_rate:
description: "任务完成率"
warning_threshold: < 85%
critical_threshold: < 70%
task_completion_time_p95:
description: "P95 任务完成时间"
warning_threshold: > 10min
critical_threshold: > 30min
cost_per_task:
description: "每任务平均成本"
tracking: "日环比、周环比、月环比"
# 步骤层
avg_steps_per_task:
description: "每任务平均步数"
warning_threshold: > 2x baseline
healthy_range: "5-20 steps for typical tasks"
self_correction_rate:
description: "自修正频率（每任务平均修正次数）"
warning_threshold: > 3 per task
trend_tracking: true
# 工具层
tool_call_success_rate:
description: "工具调用成功率"
warning_threshold: < 95%
critical_threshold: < 90%
tool_avg_latency_ms:
description: "各工具平均耗时"
per_tool_breakdown: true
4.3 告警规则设计
alerts:
p1_immediate:
- name: "灾难性失败率上升"
condition: "task_failure_rate > 5% in 5min"
action: "立即通知 on-call，暂停新任务启动"
- name: "成本异常飙升"
condition: "cost_per_minute > 10x hourly_baseline"
action: "立即通知，触发任务暂停审查"
- name: "CRITICAL 日志出现"
condition: "log_level=CRITICAL count > 0"
action: "立即通知 on-call"
p2_30min:
- name: "任务完成率下降"
condition: "task_completion_rate < 80% in 15min"
action: "通知团队，开始根因分析"
- name: "推理效率下降"
condition: "avg_steps_per_task > 2x weekly_baseline"
action: "通知团队，可能需要检查 Prompt 或工具可用性"
- name: "用户中断率异常"
condition: "user_abort_rate > 20% in 15min"
action: "通知产品团队，可能存在 UX 问题"
p3_daily:
- name: "Token 消耗趋势上升"
condition: "tokens_per_task 环比增长 > 30%"
action: "纳入每日 review，优化 Prompt 或添加示例"
- name: "自修正率趋势上升"
condition: "self_correction_rate 环比增长 > 50%"
action: "纳入每周分析，可能需要改进任务分解策略"
五、监控面板设计
生产级监控面板应该覆盖三个视角：概览、实时、历史趋势。
5.1 概览仪表板（给 Manager 和 On-call）
┌────────────────────────────────────────────────────────────┐
│ AI Coding Agent 健康概览 [时间范围: 最近24小时] │
├────────────────────────────────────────────────────────────┤
│ ✅ 任务总数: 847 | ✅ 完成率: 91.2% | ⚠️ 失败率: 4.1% │
│ 💰 总Token: 4.2M | 💰 成本: $18.30 | ⏱️ P95耗时: 8m │
├──────────────────┬──────────────────┬──────────────────────┤
│ 任务完成趋势 │ Token消耗趋势 │ 工具成功率 │
│ [折线图] │ [面积图] │ [仪表盘] │
│ │ │ Overall: 97.3% │
├──────────────────┴──────────────────┴──────────────────────┤
│ ⚠️ 最近告警 (3) [查看全部 →] │
│ • 10:23 - Token消耗环比+32%，建议审查 Prompt │
│ • 09:15 - avg_steps异常 (+89%)，已自动恢复 │
│ • 昨日 - 自修正率环比+41%，建议优化任务分解 │
└────────────────────────────────────────────────────────────┘
5.2 实时诊断面板（给 On-call 和 SRE）
┌────────────────────────────────────────────────────────────┐
│ 实时诊断视图 [自动刷新: 10s] │
├──────────────────────────────┬────────────────────────────┤
│ 当前运行任务 (7) │ 工具健康状态 │
│ ├ task-8841 [进行中 3m] │ ✅ exec: 98.1% (1.2k) │
│ ├ task-8842 [进行中 1m] │ ✅ read: 99.8% (3.4k) │
│ └ task-8843 [等待中] │ ⚠️ web_search: 87.2% (89) │
├──────────────────────────────┴────────────────────────────┤
│ 最近 20 条 ERROR/WARNING 日志 │
│ ─────────────────────────────────────────────────────── │
│ 10:24:42 [ERROR] task-8839 step-5 exec: timeout 30s │
│ 10:24:15 [WARN] task-8838 step-2 assumption unmet │
│ 10:23:58 [ERROR] task-8837 step-8 tool_auth failed │
│ 10:23:41 [WARN] task-8835 step-3 high_token: 15k/step │
└────────────────────────────────────────────────────────────┘
六、与相关话题的关系
可观测性 vs 故障诊断
可观测性解决的是”看见问题”——建立数据采集基础设施。 故障诊断解决的是”分析问题”——在可观测性数据之上做根因分析。
没有可观测性，故障诊断只能靠猜测。有了可观测性，故障诊断才能从”我觉得是…“变成”数据明确显示…“。
可观测性 vs 自修正
自修正是 Agent 的内建能力——在执行过程中发现错误后自主纠正。 可观测性是外部观察能力——让运维人员看到 Agent 在做什么。
两者的关系：可观测性提供”发现异常”的信号，自修正负责”处理异常”。如果自修正率异常升高（通过可观测性数据发现），说明任务设计或 Agent 策略需要优化。
可观测性 vs 评估框架
评估框架回答的是”长期趋势”——Agent 是否在变好、哪个维度在变好。 可观测性回答的是”实时状态”——现在 Agent 健康吗、有没有问题。
两者都需要 Trace 数据，但使用场景不同：可观测性是实时的、运营驱动的；评估框架是离线的、分析驱动的。
总结
AI Coding Agent 的可观测性不是”锦上添花”，而是生产级系统的必备能力。当你的 Agent 系统开始面临以下问题：
- 任务失败不知道是模型问题还是工具问题
- Token 消耗无法预测和控制
- Agent 行为无法复现和复盘
- 多 Agent 协作时无法追踪链路
这个时候，答案是不是调优 Prompt，而是建立可观测性。
核心建设路径：
- 从 Trace 结构设计开始：定义清楚四层模型（Task/Step/Tool/Decision）
- 统一日志格式：所有日志使用结构化 JSON，统一敏感信息过滤
- 建立核心指标：任务完成率、Token 消耗、工具成功率、告警触发
- 配置告警规则：分 P1/P2/P3 三级，不同级别不同响应
- 搭建监控面板：给不同角色（Manager/On-call/SRE）提供不同视图
一旦这套基础设施就位，你会发现很多之前”玄学”的问题变得清晰可见——Agent 行为从黑盒变成了灰盒，你终于可以基于数据而不是猜测来做优化决策。