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

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

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

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

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

效果预览

架构总览

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

核心指标

KPI 汇总	事件构成

Token 消耗	工具耗时排行

Grafana 看板

鸟瞰看板	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 <server> 'docker exec -i signoz-clickhouse clickhouse-client --multiquery' \
  < grafana-dashboards/clickhouse-views.sql
for f in grafana-dashboards/dsh-*.json; do
  curl -u admin:admin -H "Content-Type: application/json" \
    -d "{\"dashboard\":$(cat $f),\"overwrite\":true}" \
    http://<server>:3000/api/dashboards/db
done

# 4. 体检
bash scripts/verify.sh <server>

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

目录

看板清单

隐私边界

• 平台定位局域网私有部署，数据不出网；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 第六节。