前言¶

DSH 的理念是“一切皆插件”。對 dsh 插件作者來說，dsh 已有會話級 OTel 遙測，但插件維度的 trace、log、metric 往往需要自行處理 OpenTelemetry providers、導出器和配置。dsh-o11y-plugin 的目標是把這部分能力收斂到插件層：註冊全局 OpenTelemetry providers，讓使用標準 @opentelemetry/api 的插件導出 traces、metrics、logs，並將 dsh 會話遙測橋接爲 OTel logs。

這是什麼¶

dsh-o11y-plugin 是爲 deepseek-harness（dsh）提供統一插件維度可觀測性的 dsh 插件。倉庫 owner 是 fly3366，許可證爲 MIT。它適合希望使用標準 @opentelemetry/api 輸出遙測、而不是每個插件各自實現 OTel 導出的插件作者。

核心功能¶

• 爲 dsh 插件提供統一的 trace、log、metric 可觀測性。
• 註冊全局 OpenTelemetry providers，使標準 @opentelemetry/api 插件能夠導出 traces、metrics、logs。
• 將 dsh 會話遙測橋接爲 OTel logs。
• 通過 OTLP/HTTP endpoint 導出遙測；未配置或 endpoint 不可達時靜默丟棄。
• 支持 headless 與 web profile。
• 插件無狀態，移除後不需要數據清理。
• 不寫文件，不讀取或存儲憑據；遙測在導出前保持在內存中。
• 可在 dsh Web settings UI 以 o11y namespace 查看和編輯配置；在缺少 settings service 的 dsh 版本上無操作。

兼容環境¶

• DSH 兼容：@deepseek-ai/dsh 0.1.0-rc.6–rc.8。
• 運行時依賴：@deepseek-ai/cordis 4.0.1。
• Node：^22.19 || >=24。
• Profiles：headless、web。

安裝與啓用¶

從 npm 安裝到 web profile：

dsh plugin --profile web add dsh-o11y-plugin

從 git 倉庫安裝到 web profile：

dsh plugin --profile web add github:fly3366/dsh-o11y-plugin

在 headless profile 安裝：

dsh plugin --profile headless add github:fly3366/dsh-o11y-plugin

從 web profile 移除：

dsh plugin --profile web remove dsh-o11y-plugin

插件無狀態，移除時不需要額外數據清理。

典型用法¶

安裝後，將 OTLP endpoint 指向 collector，再運行 dsh：

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 dsh --profile headless "say hi"

如果插件調用 @opentelemetry/api 的 trace.getTracer(...)、metrics.getMeter(...) 或 logs.getLogger(...)，這些 signals 會經過該插件註冊的全局 OpenTelemetry pipeline 導出。未配置 endpoint 或 collector 不可達時，遙測會靜默丟棄。

適用場景與注意¶

適合在 dsh 插件中使用標準 @opentelemetry/api，並希望在 headless 與 web profile 下使用統一 OTLP/HTTP 導出路徑的場景。

使用注意：

• 插件以當前 dsh 進程權限運行；安裝前應檢查源碼與許可證。
• 網絡訪問僅面向配置的 OTLP/HTTP endpoint；沒有 collector 可達時靜默丟棄。
• 插件不寫文件、不讀取或存儲憑據；遙測在導出前保持在內存中。
• dsh Web settings UI 的 o11y namespace 可在缺少 settings service 的 dsh 版本上無操作。Web settings card 在 wip/settings-ui 分支開發，未隨 main 發佈；dsh 尚未允許外部 bundle 注入 web client composition。

結尾¶

dsh-o11y-plugin 提供了一套統一的 dsh 插件可觀測性路徑：全局 OpenTelemetry providers、OTLP/HTTP 導出、dsh 會話遙測到 OTel logs 的橋接，以及無狀態移除。

GitHub：https://github.com/fly3366/dsh-o11y-plugin