dsh-o11y-plugin
已验证dsh-o11y-plugin · v0.1.0 · MIT
Unified observability (trace/log/metric) for deepseek-harness plugins: hooks dsh session telemetry where available, maintains OTel signals where not, and exports via standard OTLP.
安装
dsh plugin add dsh-o11y-plugin 用 dsh --profile default --dump-config 确认 layer 已生效 —— 参见安装指南。
源码
标签
作者
说明文档
dsh-o11y-plugin
deepseek-harness (dsh) 的统一 插件维度可观测（trace / log / metric）插件。
English | 中文
概述
dsh 自带会话级 OTel 遥测，但未向插件暴露 metric 或插件维度的可观测能力。
dsh-o11y-plugin 收敛该缺口：注册全局 OpenTelemetry providers，使任何使用标准
@opentelemetry/api 的插件都能经由单一、统一配置的管线导出 trace / metric /
log，并将 dsh 会话遥测桥接为 OTel log。面向希望获得标准、社区兼容可观测性而
不愿各自实现 OTel 的插件作者。
兼容性
| 项 | 值 |
|---|---|
| DSH 兼容性 | @deepseek-ai/dsh 0.1.0-rc.6–rc.8（可选桥接钩子未变；无 dsh 服务依赖） |
| 运行时依赖 | 仅 @deepseek-ai/cordis 4.0.1 |
| 最后验证 | 2026-08-20（基于 @deepseek-ai/cordis 4.0.1 的单元测试） |
| Node | ^22.19 || >=24 |
| 适用 profile | headless、web |
基于官方 OpenTelemetry Node.js SDK，与 dsh session-telemetry-otel 同依赖族。
安装 / 卸载
# 安装
dsh plugin --profile web add github:fly3366/dsh-o11y-plugin
# 从某 profile 移除
dsh plugin --profile web remove dsh-o11y-plugin
# 或运行时禁用：enabled=false
插件无状态，移除无需数据清理。
快速开始
dsh plugin --profile headless add github:fly3366/dsh-o11y-plugin
# 可选：指向 collector（无 collector 时静默丢弃）
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 dsh --profile headless "say hi"
任何插件经 @opentelemetry/api 调用 trace.getTracer(...) /
metrics.getMeter(...) / logs.getLogger(...) 即自动导出。
deepjit 为参考使用方，上报管线计数器与
GenAI（gen_ai.*）LLM span。
配置
同样的配置项以 o11y 命名空间暴露在 dsh Web 设置界面（经
@deepseek-ai/dsh-settings），可查看/编辑并持久化，下次 dsh 启动生效；
在无 settings 服务的旧版 dsh 上自动跳过。
| 配置 | 默认 | 说明 |
|---|---|---|
enabled |
true |
总开关 |
serviceName |
''（→ OTEL_SERVICE_NAME → dsh-plugin） |
OTel resource service.name |
endpoint |
''（→ OTEL_EXPORTER_OTLP_ENDPOINT → http://localhost:4318） |
OTLP/HTTP endpoint |
enableTraces / enableMetrics / enableLogs |
true |
按信号开关 |
metricExportIntervalMs |
60000 |
metric 周期导出间隔 |
bridgeSessionTelemetry |
true |
是否桥接 dsh 会话遥测到 OTel log |
敏感项：不读取、不存储凭据；仅可选的 OTLP endpoint 涉及网络。
权限与数据
- 文件：不写任何文件；遥测导出前均在内存。
- 网络：仅向配置的 endpoint 发 OTLP/HTTP；无 collector 时静默丢弃。
- 凭据：无。
- 用户数据：桥接时在内存观察 session-telemetry record 并转为 OTel log； 本插件不做任何持久化。
故障排查
- endpoint 无 collector → batch 静默丢弃（预期行为）。
- 导出错误 → 经 OTel diag 暴露；检查
endpoint与 collector 可用性。 - 回滚：
dsh plugin --profile <p> remove dsh-o11y-plugin或enabled=false。
开发
npm install
npm run typecheck
npm test
npm run build
欢迎贡献；请保持 OTel SDK 依赖族与 dsh session-telemetry-otel 对齐，以利社区兼容。
许可与安全
MIT。安全问题请按 SECURITY.md 私下报告。