插件可观测套件 fly3366/dsh-o11y-plugin

dsh-o11y-plugin

deepseek-harness (dsh) 的统一
插件维度可观测（trace / log / metric）插件。

概述

dsh 自带会话级 OTel 遥测，但未向插件暴露 metric 或插件维度的可观测能力。
dsh-o11y-plugin 收敛该缺口：注册全局 OpenTelemetry providers，使任何使用标准 @opentelemetry/api 的插件都能经由单一、统一配置的管线导出 trace / metric / log，并将 dsh 会话遥测桥接为 OTel log。面向希望获得标准、社区兼容可观测性而不愿各自实现 OTel 的插件作者。

兼容性

| 项 | 值 |
| DSH 兼容性 | @deepseek-ai/dsh 0.2.0-rc.2（已确认 session-telemetry/record 桥接事件仍存在；无 dsh 服务依赖） |
| 运行时依赖 | 仅 @deepseek-ai/cordis 4.0.4 |
| 最后验证 | 基于 @deepseek-ai/cordis 4.0.4 / @deepseek-ai/dsh-settings 0.2.0-rc.2 的单元测试 |
| Node | ^22.19 \|\| >=24 |
| 适用 profile | headless、web |

基于官方 OpenTelemetry Node.js SDK，与 dsh session-telemetry-otel 同依赖族。

安装 / 卸载

从 npm 安装
dsh plugin --profile web add dsh-o11y-plugin

或 git 直装
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。

配置

当宿主 dsh 提供 settings 命名空间 API（@deepseek-ai/dsh-settings 的 installSettingsSection / settingsNamespace）时，同样的配置项会以 o11y 命名空间注册到 dsh Web 设置界面，可查看/编辑并持久化，下次 dsh 启动生效。

dsh 0.1.5 移除了 installSettingsSection，0.2.0-rc.2 仍未恢复，因此在该等版本上
插件会探测此 API 并优雅地空操作——配置仍由文件/环境变量驱动。若未来 dsh 恢复该 API，集成会自动重新生效。

参考用的 Web 设置卡片（客户端部分）停在 wip/settings-ui 分支。它早于 dsh 官方的 client-plugin 机制（dsh.client 声明 + /plugins 提供 bundle + ctx.slots.register， 0.1.7 线已发布），重启时需按该契约重做；未随 main 发布。

| 配置 | 默认 | 说明 |
| 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 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 私下报告。