前言¶
DSH 的插件生态围绕「一切皆插件」展开：一个能力可以由插件接入 harness 的公开 seam。对于 agent session，dsh-observability 提供的是 traces 视角：把 session 中的 turn、model step、tool call 折成 OTLP span tree，再发到接受 OTLP/HTTP 的 collector。
它是社区插件，不是 DeepSeek 官方仓库的一部分，也不要把它理解为官方应用商店。
这是什么¶
dsh-observability 是 CodePrometheus 维护的社区插件，许可证为 MIT，带 dsh-plugin topic。它的定位是 DeepSeek Harness telemetry seam 的 OpenTelemetry traces backend：将 agent session events 折叠成 OTLP span tree。
插件实现 harness 的公开 telemetry Service Definition，作为 official provider 之外的第二个 Service Provider 工作。它只观察 session stream，不参与模型请求。
核心能力¶
- 将每个 agent session 导出为 OTLP span tree：turn 对应 trace，model step 对应该 trace 的 child span，tool call 对应该 step 的 child span。
- 增加 GenAI semantic-convention attributes。
- 支持
FULL、FEEDBACK_ONLY、DISABLED三种模式。 - 发送到任意接受 OTLP/HTTP 的 collector。
- 随插件包附带
cordis.patch.yml，可作为 profile bundle 安装；也可以挂载为显式cordis.ymlrow。 - 只通过 telemetry Service Definition 观察 session stream，不会给模型请求贡献内容。
安装与启用¶
先以 profile bundle 方式安装插件，然后设置运行模式和 OTLP endpoint。endpoint 必须是完整的 traces 路径。
dsh plugin --profile web add dsh-observability
export DSH_OBSERVABILITY_MODE=FULL
export DSH_OBSERVABILITY_OTLP_URL=http://127.0.0.1:4318/v1/traces
如果需要在 cordis.yml 中显式挂载，可以使用类似下面的配置行。下面示例只列已核实字段；processor 为空对象时表示不额外覆盖 processor 配置。
- id: session-telemetry-otlp-traces
name: dsh-observability
config:
mode: FULL
exporter:
url: http://127.0.0.1:4318/v1/traces
processor: {}
shutdownTimeoutMillis: 3000
maxAttributeChars: 32768
主要配置项如下：
| 字段 | 说明 |
|---|---|
mode |
可取 FULL、FEEDBACK_ONLY、DISABLED；默认 DISABLED |
exporter.url |
非 DISABLED 时必填，且必须是完整 traces 路径（.../v1/traces） |
processor |
用于配置 processor 参数 |
shutdownTimeoutMillis |
关闭超时 |
maxAttributeChars |
span attribute 序列化上限 |
DISABLED 下不构造传输，也没有数据离开进程。配置错误会在插件加载阶段失败，发生在任何 transport 构造之前。
典型用法¶
启用上传模式¶
在本地或受控环境中，可以先把模式设为 FULL，再把 endpoint 指向接受 OTLP/HTTP 的 collector。
export DSH_OBSERVABILITY_MODE=FULL
export DSH_OBSERVABILITY_OTLP_URL=http://127.0.0.1:4318/v1/traces
运行测试¶
插件提供单元测试和 real-composition e2e。测试会验证配置、折叠逻辑，以及构建产物在 mock collector 上的实际组合。
npm test
npm run build && npm run test:e2e
npm test 运行单元测试；npm run build && npm run test:e2e 在构建后运行 e2e，目标是 mock collector。
适用场景与注意¶
适合：
- 想把 DSH agent session 放进 trace 后端，按 turn、model step、tool call 查看会话的开发者。
- 已有接受 OTLP/HTTP 的 collector，需要把 dsh session events 接入 OpenTelemetry traces 的团队。
- 希望在不改动模型请求路径的情况下增加观测能力的场景。
注意：
- 插件以当前 dsh 进程权限运行。安装前应检查源码、依赖和 MIT 许可证。
DISABLED是默认模式，不构造任何东西，也没有数据离开进程。- 在上传模式下，span attributes 可能携带 user 和 assistant message content、tool arguments 和 results、model 和 usage metadata、session cwd。
- 插件不提供 redaction rules；如果导出到信任边界之外，部署侧需要自行挂载规则。
- 每个 span attribute 的序列化内容按
maxAttributeChars截断；canonical session log 保留完整 bytes。 - Provider API keys 在结构上不会进入 telemetry，因为 adapter credentials 是 constructor parameters，不是 session events。
- DeepSeek Harness 处于 developer preview，没有兼容性承诺；该插件会 pin 精确的
@deepseek-ai/dsh-*versions。 - 文档把 best-effort delivery 列为 Known Limitations；是否满足生产要求，应结合自身 collector 和可靠性要求评估。
链接¶
GitHub：https://github.com/CodePrometheus/dsh-observability
