可观测性追踪 krimvp/dsh-otel

dsh-otel

用于 DeepSeek Harness（dsh）的 OpenTelemetry 插件。

状态：早期开发中。
该插件为 agent 循环、模型调用和工具调用发出追踪（traces）和指标（metrics）。
GenAI 语义约定（semantic conventions）的状态为 Development，因此每个 gen_ai. 名称都可能发生变化。
在 0.1.0 版本之前预计会有破坏性变更。
DeepSeek Harness 也处于开发者预览阶段。

插件发出的内容

追踪（Traces）

| dsh 概念 | Span | Kind |
| Turn | invoke_agent | INTERNAL，追踪的根 |
| Step | dsh.step | INTERNAL，turn 的子级 |
| Model call | chat {model} | CLIENT，step 的子级 |
| Tool call | execute_tool {name} | INTERNAL，step 的子级 |

每个 span 都带有 gen_ai.conversation.id，即 dsh 会话 id。

指标（Metrics）

| 仪器 | 单位 |
| gen_ai.client.token.usage | {token} |
| gen_ai.client.operation.duration | s |
| gen_ai.execute_tool.duration | s |

该插件不发出日志。
harness 已经提供了 @deepseek-ai/dsh-session-telemetry-otel 用于日志。
这两个包可以协同工作。

docs/design.md 给出了完整的属性表。

安装

dsh plugin --profile add dsh-otel

然后在 $DSH_HOME/profiles//cordis.patch.yml 中挂载该插件：

- insert:
- id: dsh-otel
name: dsh-otel
config:
endpoint: http://localhost:4318

insert 会添加一个新条目。
指定了 id 的 patch 会替换该条目的整个配置。

使用 dsh --profile --dump-config 确认挂载。

该插件需要 @deepseek-ai/cordis 和 @opentelemetry/api 作为 peer 依赖。
该插件会自行设置 tracer provider、meter provider 和 OTLP HTTP exporter。
你不需要 @opentelemetry/sdk-node。

配置

配置是扁平的，且恰好有四个选项。

| 选项 | 类型 | 默认值 | 含义 |
| serviceName | string | dsh | 服务名称。OTEL_SERVICE_NAME 优先于此选项。 |
| endpoint | string | http://localhost:4318 | OTLP HTTP 基础 URL。仅当未设置任何 OTLP endpoint 变量时，插件才会使用它。 |
| captureContent | boolean | false | 记录消息内容、工具参数和工具结果。 |
| useGlobalProviders | boolean | false | true 表示使用 @opentelemetry/api 的全局对象。此时插件不会设置任何 SDK。 |

标准环境变量优先于配置选项。

| 变量 | 效果 |
| OTEL_EXPORTER_OTLP_ENDPOINT | 两个信号的基础 URL。此时插件不会向 exporter 传递 URL。 |
| OTEL_EXPORTER_OTLP_TRACES_ENDPOINT、OTEL_EXPORTER_OTLP_METRICS_ENDPOINT | 单个信号的 URL，按原样使用。 |
| OTEL_EXPORTER_OTLP_HEADERS、_TIMEOUT、_COMPRESSION、_CERTIFICATE | 由 exporter 读取。 |
| OTEL_SERVICE_NAME、OTEL_RESOURCE_ATTRIBUTES | 由插件通过环境资源检测器读取。 |
| OTEL_SDK_DISABLED=true | 该插件不执行任何操作。 |
| OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true | 开启内容捕获。 |
| OTEL_BSP_、OTEL_TRACES_SAMPLER | 由 @opentelemetry/sdk-trace-base 读取。 |

内容捕获默认关闭。
消息内容可能包含用户数据和个人数据。

开发

在贡献之前，请阅读 AGENTS.md。
该文件给出了代码、配置和提交的规则。

请对照 otel/ 中的真实本地技术栈验证每一项更改。

docker compose -f otel/docker-compose.yml up -d
npm run build

./e2e/verify.sh 是一条命令完成本地验证的脚本。
该脚本构建插件，针对模拟模型在 dsh 中运行两个任务，然后从 Tempo 读取追踪数据，从 Prometheus 读取指标。
该脚本为每个断言打印一行 PASS 或一行 FAIL。

docker compose -f otel/docker-compose.yml up -d
./e2e/verify.sh

该脚本通过临时补丁挂载来自 ./dist 的全新构建。
该脚本不安装任何内容，也不更改任何配置文件。
脚本头部列出了用于指定 dsh、DSH_HOME 和模拟服务器路径的环境变量。
每个变量都有适用于本地游乐场的默认值。

许可证

MIT