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）。

目录

路径	内容
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 第六节。