dsh-prometheus

English | 中文

面向 DeepSeek Harness 的 Prometheus 指标插件与可直接导入的 Grafana Dashboard。插件只观察 DSH 的公开生命周期扩展点，在导出前限制指标序列基数，并避免输出对话或工具载荷。

发布状态：0.1.0 是首个 Developer Preview 版本，已针对 DSH 0.1.0-rc.6 完成测试。

监控范围

• 活跃 Session；Agent turn、step、error 及耗时直方图
• LLM 请求速率、终止状态、延迟，以及互不重叠的输入/输出/推理/缓存 token 计数
• Tool 调用速率、规范化成功/失败状态及延迟
• Approval 请求和固定结果计数
• Subagent 启动、结果及耗时
• 后台 job 的活跃/启动/完成/终止/失败数量及耗时
• 进程启动时间和标签溢出诊断

完整指标名、标签和语义见 docs/metrics.md。

兼容性

| 组件 | 已测试版本 | |---|---| | DeepSeek Harness npm packages | 0.1.0-rc.6 | | 官方源码基线 | 47f943859bef60e4160492346772ded9b24f765a（2026-08-13） | | Cordis | ^4.0.1 | | Node.js | ^22.19.0 || >=24.0.0 | | prom-client | 15.1.3 |

DeepSeek Harness 当前仍是 Developer Preview。每次升级 DSH 都应视为一次兼容性变更，并执行完整测试与发布清单。

安装

将 npm package 安装到 DSH profile，并检查 bundle layer：

dsh plugin --profile monitoring add dsh-prometheus
dsh --profile monitoring --dump-config

Bundle 会插入 id 为 prometheus 的一行。启动 profile 前，请确认 dump 中出现 dsh-prometheus layer。

Endpoint 选择

默认 mode: auto 会在插件激活时做一次选择：

1. 如果公开的 DSH webServer 已激活且绑定安全，则注册精确的 /metrics 路由；
2. 否则在 127.0.0.1:9464 启动独立 endpoint。

仓库内的 Docker 示例需要固定 target，建议在 profile 的 cordis.patch.yml 中强制 standalone。后应用的 patch 会替换整段 config：

- id: prometheus
  config:
    enabled: true
    mode: standalone
    host: 127.0.0.1
    port: 9464
    path: /metrics
    allowRemote: false
    maxLabelValues: 64
    maxLabelValueLength: 80

配置项

| 字段 | 默认值 | 说明 | |---|---:|---| | enabled | true | 不删除 row 的情况下禁用全部 collector 与 endpoint。 | | mode | auto | auto、webserver 或 standalone。 | | host | 127.0.0.1 | 独立服务绑定地址：loopback 或 0.0.0.0。 | | port | 9464 | 独立服务端口；0 仅建议用于测试。 | | path | /metrics | 精确路由；必须以 / 开头且不能以 / 结尾。 | | allowRemote | false | 绑定 0.0.0.0 或复用对外 WebServer 时必须显式确认。 | | maxLabelValues | 64 | 每个动态标签键允许的不同值数量。 | | maxLabelValueLength | 80 | 动态标签值最大长度。 |

远程暴露没有内置认证或 TLS。启用前请阅读 SECURITY.md。

快速抓取

curl --fail --silent http://127.0.0.1:9464/metrics

Endpoint 支持 GET/HEAD；其他方法返回 405；响应禁止缓存并使用 prom-client 的 Prometheus/OpenMetrics 兼容 Content-Type。

Prometheus 与 Grafana

仓库提供完整本地监控栈：

docker compose -f examples/docker-compose.yml up -d

Prometheus 地址为 http://127.0.0.1:9090，Grafana 地址为 http://127.0.0.1:3000（本地默认 admin / admin，非本地环境必须修改）。Datasource 和 DeepSeek Harness / Overview Dashboard 会自动 provision。

可独立使用的资产位于 examples/prometheus.yml 与 grafana/dsh-overview.json。安全、兼容性和验证证据分别见 docs/security.md、docs/compatibility.md 和 docs/verification-report.md。

常用查询：

# Turn 吞吐
sum(rate(dsh_agent_turns_total[5m]))

# Turn 失败率
sum(rate(dsh_agent_turns_total{status=~"error|blocked|aborted"}[5m]))
/
clamp_min(sum(rate(dsh_agent_turns_total[5m])), 0.000001)

# 按 provider/model 的 P95 LLM 延迟
histogram_quantile(0.95,
  sum by (le, provider, model) (rate(dsh_llm_request_duration_seconds_bucket[5m])))

# 按 tool 的失败速率
sum by (tool) (rate(dsh_tool_calls_total{status!="success"}[5m]))

初始告警规则见 examples/prometheus/alerts.yml。请按实际负载调阈值；没有任务时吞吐为零是正常现象。

隐私与基数控制

Collector 不会导出 prompt、用户/助手消息、system prompt、tool 参数或结果、错误文本、文件路径、工作目录、任意 metadata，也不会导出 session/agent/call/job/subagent id。

只有四类运行时动态标签：provider、model、tool 和 job kind。值必须匹配 [A-Za-z0-9][A-Za-z0-9_.:/-]*，长度不得超限，并受每个键的数量上限约束。非法或超量值统一映射为 __other__；dsh_metrics_label_overflow_total 只记录发生次数，不记录原值。

provider/model/tool/kind 名称仍属于运维 metadata，请勿把客户标识或秘密放入这些名称。

生命周期

所有 listener、job observer、路由、socket 和 registry 都属于插件的 Cordis fiber。热重载或卸载时，Web 路由会注销；独立服务器会停止接受连接并关闭剩余 socket。Registry 是实例私有的，重载不会与进程全局 collector 冲突。

已有 live session 和 job 只用于初始化 gauge；不会回放历史事件填充 counter。进程重启或热重载造成 counter reset 属于正常 Prometheus 语义。

升级、降级与卸载

# 获取新版本 tarball 后升级
dsh plugin --profile monitoring add ./dsh-prometheus-NEW.tgz
dsh --profile monitoring --dump-config

# 删除依赖和 bundle layer
dsh plugin --profile monitoring remove dsh-prometheus

降级前请比较 CHANGELOG.md 中的指标和配置契约。卸载插件不会删除 Prometheus 已保存的数据。

开发

pnpm install --frozen-lockfile
pnpm check
pnpm test:coverage
pnpm pack

测试覆盖配置/基数、隐私、LLM/tool waterfall、endpoint 方法、远程暴露门禁、WebServer 路由卸载、独立 socket 卸载、job/subagent 生命周期，以及真实 rc.6 AgentLoop turn。参见 CONTRIBUTING.md、docs/architecture.md 和 docs/release-checklist.md。

排障与限制

参见 docs/troubleshooting.md 和 docs/known-limitations.md。

许可证

MIT