前言¶

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.yml row。
• 只通過 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

主要配置項如下：

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