Agent Observability Stack 详解 - Agent 可观测性栈

什么是 Observability Stack？

生活类比

你养了只赛博宠物 Agent，它在家里到处跑，帮你干活。

但你不知道它：去了哪、干了啥、吃了多少电、有没有把花瓶打碎。

Observability Stack 就是给 Agent 装的"全息监控系统"——

摄像头（日志）：记录它每一步干了什么
GPS（追踪）：画出它的行动路线
电表（指标）：监测它的能耗、速度、心率
警报器（告警）：花瓶碎了立即通知你

正式定义：Agent Observability Stack 是一套用于监测、诊断和调试 AI Agent 系统的完整技术栈，包括日志采集、分布式追踪、指标监控、告警系统和可视化仪表盘，帮助开发者理解 Agent 的行为、性能和健康状态。

四大支柱

┌─────────────────────────────────────────────────────────────┐ │ Dashboard (仪表盘) │ │ Grafana / Kibana / OpenClaw Console │ └─────────────────────────────────────────────────────────────┘ │ ┌─────────────────────────────┼───────────────────────────────┐ │ Alerts │ Metrics │ Traces │ │ (告警系统) │ (指标监控) │ (追踪) │ │ PagerDuty / OpsGenie │ Prometheus / StatsD │ Jaeger │ └─────────────────────────────┼───────────────────────────────┘ │ ┌─────────────────────────────┼───────────────────────────────┐ │ Logs (日志) │ │ Elasticsearch / Loki │ └─────────────────────────────┴───────────────────────────────┘ │ ┌─────────────────────────────────────────────────────────────┐ │ Agent Runtime │ └─────────────────────────────────────────────────────────────┘

核心组件详解

1. Logs（日志）

记录一切发生的事

Agent 的每次工具调用、每个决策、每次错误，全部记录下来。

// Agent 执行日志结构
{
  "timestamp": "2026-05-10T04:00:17Z",
  "agent_id": "miaoquai-ops",
  "session_id": "sess_abc123",
  "level": "INFO",
  "event": "tool_call",
  "tool": "web_search",
  "params": {"query": "OpenAI latest news"},
  "duration_ms": 234,
  "tokens_used": 156
}

2. Traces（追踪）

串联完整的调用链

一个任务可能触发多个工具调用，追踪把它们串起来，形成完整的执行路径。

// OpenTelemetry 追踪结构
Trace: gen_news_report
├─ Span: receive_request (2ms)
├─ Span: web_search (234ms)
│  └─ Span: api_call_brave (212ms)
├─ Span: summarize (156ms)
│  └─ Span: llm_call_gpt4 (148ms)
├─ Span: generate_html (45ms)
└─ Span: send_response (12ms)

Total: 449ms | Tokens: 2,340 | Cost: $0.012

3. Metrics（指标）

量化 Agent 的健康状态

成功率、延迟、Token 消耗、错误率——用数字说话。

指标类型	示例	用途
Counter	tool_calls_total	统计总次数
Gauge	active_sessions	当前状态
Histogram	response_latency	分布分析
Summary	token_usage_percentile	分位数统计

4. Alerts（告警）

问题发生时立即通知

错误率超过阈值、延迟飙升、Token 消耗异常——自动告警。

// 告警规则配置
alerts:
  - name: agent_error_rate_high
    condition: error_rate > 0.05
    duration: 5m
    severity: critical
    channels: [pagerduty, slack]
    
  - name: latency_p99_spiike
    condition: latency_p99 > 5000
    duration: 10m
    severity: warning
    channels: [slack]
    
  - name: token_budget_exceeded
    condition: daily_tokens > 1000000
    severity: info
    channels: [email]

OpenClaw 实战应用

查看 Agent 状态

# 使用 session_status 查看当前状态
📊 session_status

// 输出示例：
Session: sess_abc123
Model: tencentcodingplan/tc-code-latest
Uptime: 3h 27m 42s
Requests: 156
Tokens: 34,567
Cost: $0.18
Tools Used: web_search(12), feishu_doc(8), write(156)
Errors: 3 (1.9%)
Avg Latency: 1.2s

追踪执行链

// OpenClaw 自动记录追踪信息
$ openclaw trace sess_abc123

Trace ID: tr_xyz789
Duration: 4.5s
Spans: 12

Timeline:
[00:00.000] receive_task
[00:00.002] ├─ parse_request
[00:00.015] ├─ tool_discovery
[00:00.023] ├─ web_search (query="OpenAI")
[00:01.234] │  └─ brave_api (234ms)
[00:01.456] ├─ llm_generate
[00:03.892] │  └─ openai_api (2.4s)
[00:04.123] ├─ write_file
[00:04.456] └─ send_response

Cost Breakdown:
- LLM: $0.12 (85%)
- Search: $0.02 (14%)
- Other: $0.01 (1%)

配置告警

// Gateway 告警配置
gateway:
  observability:
    enabled: true
    exporter: otlp
    endpoint: https://otel.miaoquai.com:4317
    
  alerts:
    slack_webhook: https://hooks.slack.com/services/xxx
    email: ops@miaoquai.com
    
  metrics:
    prefix: openclaw
    labels: [agent_id, model, tool]
    
  sampling:
    traces: 1.0      // 100% 追踪
    logs: 1.0        // 100% 日志
    metrics: 1.0     // 100% 指标

关键指标清单

请求成功率

success_requests / total_requests > 99%

错误率

error_requests / total_requests < 1%

平均延迟

P50 latency < 2s

P99 延迟

P99 latency < 10s

Token 消耗

tokens_per_request < 5000

成本指标

cost_per_request < $0.10

常见坑点

踩坑实录

坑1：日志太多，找不到关键信息

所有日志都记，等于什么都没记。需要分级（INFO/WARN/ERROR）+ 结构化（JSON）+ 合理采样。

坑2：追踪丢失上下文

异步调用、并发执行时，追踪链容易断裂。使用 OpenTelemetry 的 Context 传播机制。

坑3：告警疲劳

告警太多，没人看。区分严重级别，critical 直接电话，warning 只发 Slack，info 只记日志。

坑4：忘记看仪表盘

搭建了监控系统，但没人看。设置异常自动告警，别等用户投诉才发现问题。

最佳实践

结构化日志：用 JSON 格式，方便查询和分析
关联 ID：每次请求都有唯一 ID，串联所有日志和追踪
分级告警：critical/warning/info，不同级别不同响应
仪表盘分层：全局概览 → 服务详情 → 单次追踪，层层深入
SLO 驱动：定义清晰的服务水平目标，告警基于 SLO
定期回顾：每周看一次仪表盘，优化告警规则

Agent Observability Stack