Agent 可观测性仪表盘 📊

为 OpenClaw 智能体提供统一的可观测性解决方案 —— 涵盖指标、追踪与性能洞察。

功能概述

OpenClaw 智能体需要生产级的可见性。虽然存在多个平台（Langfuse、Langsmith、AgentOps），但缺乏统一的视图。

Agent 可观测性仪表盘提供：
- 指标追踪 — 延迟、成功率、令牌使用量、错误计数
- 追踪可视化 — 工具链、决策流程、会话时间线
- 跨智能体聚合 — 对比多个智能体/会话的性能
- 可导出报告 — 支持 JSON、CSV、Markdown 格式，便于人工审查
- 告警阈值 — 指标超出限制时发送通知

解决的问题

• 缺乏 OpenClaw 智能体性能的集中视图
• 难以跨多个工具调用进行调试
• 无法对比智能体性能或追踪性能退化
• 生产环境监控是企业级的；智能体也需要同等级别的监控

使用方法

# 启动仪表盘服务器
python3 scripts/observability.py --dashboard

# 记录会话指标
python3 scripts/observability.py --record --session agent:main --latency 1.5 --success true

# 查看会话追踪
python3 scripts/observability.py --trace --session agent:main:12345

# 获取性能报告
python3 scripts/observability.py --report --period 24h

# 导出为 CSV
python3 scripts/observability.py --export metrics.csv

# 设置告警阈值
python3 scripts/observability.py --alert --metric latency --threshold 5.0

追踪指标

追踪格式

每个工具调用都会记录以下信息：
- 时间戳
- 智能体会话 ID
- 工具名称 + 参数
- 延迟
- 成功/失败状态
- 令牌使用量
- 错误详情（如果失败）

追踪示例：

{
  "session_id": "agent:main:12345",
  "trace": [
    {
      "timestamp": "2026-01-31T14:00:00Z",
      "tool": "web_search",
      "params": {"query": "agent observability"},
      "latency_ms": 1234,
      "success": true,
      "tokens_used": 150
    },
    {
      "timestamp": "2026-01-31T14:00:02Z",
      "tool": "memory_write",
      "params": {"content": "..."},
      "latency_ms": 45,
      "success": true,
      "tokens_used": 0
    }
  ]
}

架构

┌─────────────────┐
│  数据采集层     │  ← 从 OpenClaw 日志自动捕获
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  指标存储层     │  ← 使用 SQLite/InfluxDB 存储时间序列数据
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  分析引擎       │  ← 聚合、趋势分析、异常检测
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  仪表盘 UI      │  ← Web 界面（基于 Flask/FastAPI）
└─────────────────┘

环境要求

• Python 3.9+
• flask（用于仪表盘 Web UI）
• pandas（用于数据分析）
• influxdb-client（可选，用于生产环境存储）

安装步骤

# 克隆仓库
git clone https://github.com/orosha-ai/agent-observability-dashboard

# 安装依赖
pip install flask pandas influxdb-client

# 运行仪表盘
python3 scripts/observability.py --dashboard
# 打开 http://localhost:5000

灵感来源

• Dynatrace AI 可观测性应用 — 企业级统一可观测性
• Langfuse 与 AgentOps 基准测试 — 平台对比
• Microsoft .NET 追踪指南 — 实用实现模式
• OpenLLMetry — 面向 LLM 的 OpenTelemetry 集成

本地化承诺

• 指标存储在本地（SQLite/InfluxDB）
• 仪表盘在本地运行
• 不向外部服务发送任何数据

版本历史

• v0.1 — 最小可行产品：指标追踪、追踪可视化、仪表盘 UI
• 路线图：InfluxDB 集成、异常检测、多智能体对比