tianjiqx/dsh-agentobs

dsh-agentobs · DSH Agent 开源可观测解决方案

局域网私有部署的 AI Agent 可观测平台：OpenTelemetry Collector + ClickHouse + Prometheus + Grafana，为 DSH Agent 提供会话日志、GenAI Trace、LLM 指标的全链路观测。

完整叙事与效果截图见 BLOG.md。

约定：本文所有命令与配置文件用  代称运行观测栈的机器（ClickHouse / Collector / Grafana 所在主机），实际使用时替换为你的主机 IP 或 ssh 别名；脚本默认回退到 127.0.0.1（在观测栈本机直接运行）。

注意：本仓库为AI撰写项目，仅提供参考，细节可以交由AI具体参考完善。

效果预览

架构总览

数据流总览

📊 查看交互式架构图（支持缩放、主题切换、搜索、演示模式）

核心指标

| KPI 汇总 | 事件构成 |
|---------|---------|
| KPI | 事件 |

| Token 消耗 | 工具耗时排行 |
|-----------|-------------|
| Token | 工具 |

Grafana 看板

| 鸟瞰看板 | LLM 性能 |
|---------|---------|
| Overview | LLM |

完整看板列表与效果截图见 BLOG.md。

30 分钟上手

1. 起存储栈（ClickHouse + OTel Collector）
docker compose up -d
curl -s localhost:13133/          # collector 健康 → OK

2. DSH 机器：把两段 patch 追加到 ~/.dsh/cordis.patch.yml
configs/dsh-telemetry-cordis-patch.yml       （会话日志，logs）
configs/loongsuite-observability-patch.yml   （GenAI trace/metrics）
⚠ id 必须一字不差；endpoint 别留默认 localhost

3. 部署 ClickHouse 视图 + 导入 Grafana 看板
ssh  'docker exec -i signoz-clickhouse clickhouse-client --multiquery' \
:3000/api/dashboards/db
done

4. 体检
bash scripts/verify.sh

Grafana 侧一次性配置：安装 grafana-clickhouse-datasource 插件，添加 ClickHouse 数据源（http://:18123，库 signoz_logs）。

目录

| 路径 | 内容 |
|---|---|
| docker-compose.yml | ClickHouse + OTel Collector 一键部署 |
| configs/ | collector 配置、DSH 双插件 patch、Prometheus 抓取片段 |
| grafana-dashboards/ | 7 个看板 JSON + 3 个 SQL 视图（看板底座） |
| scripts/ | 端到端体检、历史会话 JSONL 回灌 |
| tools/ | 数据采集 / 图表生成 / 截图脚本（图片再生产工具链） |
| assets/ | BLOG.md 插图（22 张被引用）+ 素材库（单面板源图、matplotlib 后备图表，可自行取用） |
| stats.json | 最近一次聚合统计样例 |

看板清单

| uid | 用途 |
|---|---|
| dsh-agent-overview-ch | 鸟瞰：Token/Turn/错误/重试 + 模型与工具分布 |
| dsh-llm-performance-ch | LLM 逐次调用：TTFT/耗时/吞吐/Token + 慢调用下钻 |
| dsh-tool-analytics-ch | 工具调用次数/耗时 avg·p95/错误明细 |
| dsh-clickhouse-logs | 错误优先日志工作台（错误码/时间线/原始日志） |
| dsh-message-search-ch | 消息全文搜索 + 会话上下文回放 |
| dsh-agent-traces-ch | Trace 选择 + GenAI 瀑布图 + Span 明细 |
| dsh-genai-metrics-prom | Prometheus 侧 GenAI 指标（分位数/速率/告警底座） |

隐私边界

- 平台定位局域网私有部署，数据不出网；ClickHouse TTL 90 天。
- 本目录插图仅含聚合口径面板；会话 ID / 消息文本 / 路径不出现在任何图片中。
- tools/collect_ch_stats.py 只导出 counts/quantiles/sums 聚合值。

关键踩坑（速查）

- Grafana CH 插件：$__timeFilter(列名) 必须带列；桶宽用 $__interval_ms；logs 面板 format:2、traces 面板 format:3。
- ClickHouse：存量表 TTL 要手动 MODIFY TTL + MATERIALIZE TTL；otel_traces 过滤用 toDateTime(Timestamp)。
- DSH 插件：loongsuite-observability id 不可改；endpoint 缺省 localhost 且静默丢弃；TTFT 属性单位是纳秒。

完整踩坑清单（20+ 条，全部实测）见 BLOG.md 第六节。