dsh-plugin

一句话定位

这是 LoongSuite 出品的 DSH 独立可观测插件。它在 DSH 进程内监听原生会话、Agent 循环、LLM 流和工具调用，把每一次对话转换成符合 OpenTelemetry GenAI 语义约定的 trace 与 metric，再通过标准 OTLP/HTTP protobuf 发往任意兼容后端（Jaeger、Langfuse、自建 Collector 等）。

核心能力

• 把每一次 DSH 对话转换为一条 OpenTelemetry trace，结构为 ENTRY → AGENT → STEP → LLM/TOOL，重试会以多个 LLM span 形式保留在同一 STEP 下
• 上报 OpenTelemetry 标准的 GenAI 时延与 token 用量指标，覆盖输入、输出、缓存命中、缓存写入与推理 token
• 通过 DSH 原生的 session/created、session/event、session/disposed、llm/stream 钩子接入，错误、中止、不完整流和插件卸载都会以错误状态正确关闭 span
• 支持多 Profile 同时安装（web、headless 等），并通过 DSH 事件时间戳构造结构性 span、用单调时钟计量首字延迟
• 启用正文采集时把提示词、回复、工具定义与参数、工具结果写入 span 属性，并自动按字符上限截断；默认关闭以保护隐私
• Subagent 会话生成独立 trace 并携带父会话与委派层级属性，便于在 trace 后端区分嵌套调用

技术实现

• 语言: TypeScript（ESM，编译到 ES2022）
• 关键依赖: @opentelemetry/api、@opentelemetry/sdk-trace-base、@opentelemetry/sdk-metrics、@loongsuite/otel-util-genai、@deepseek-ai/schemastery
• 架构模式: Cordis 插件 + 私有 OTLP Pipeline —— 通过 cordis.patch.yml 注册 bundle 行，由 apply(ctx) 监听 DSH 生命周期事件，内部创建独立的 TracerProvider 与 MeterProvider（不注册全局）并通过 BatchSpanProcessor 批量上报
• 入口文件: src/index.ts

适用场景

当用户希望把 DSH 的对话过程接入现有的 OpenTelemetry 后端做链路追踪、性能分析或成本核算时安装此插件。典型用户是已经在用 Jaeger、Langfuse、Datadog APM 或自建 OTel Collector 的运维/平台团队，需要把每次 DSH 对话的耗时、模型、token、工具调用可视化而无需改造 DSH 本身。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:loongsuite/dsh-plugin

配置项

支持的 OpenTelemetry 标准环境变量：OTEL_EXPORTER_OTLP_ENDPOINT、OTEL_EXPORTER_OTLP_TRACES_ENDPOINT、OTEL_EXPORTER_OTLP_METRICS_ENDPOINT、OTEL_EXPORTER_OTLP_HEADERS、OTEL_EXPORTER_OTLP_TRACES_HEADERS、OTEL_EXPORTER_OTLP_METRICS_HEADERS、OTEL_SERVICE_NAME、OTEL_RESOURCE_ATTRIBUTES、OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT（SPAN_ONLY / SPAN_AND_EVENT）、OTEL_METRICS_EXPORTER（设为 none 可关掉指标）。Header 与 Resource 值使用标准的 key=value 逗号分隔、百分号编码格式。

常见问题

Q: 安装后还需要额外配置吗？

A: 不需要。装上即用，未配置 OTLP endpoint 时使用 OpenTelemetry 默认地址；不设置 OTEL_SERVICE_NAME 时上报的服务名默认为 deepseek-harness。

Q: 需要额外安装 LoongSuite Pilot 或本地 sidecar 吗？

A: 不需要。插件自带私有 OTLP pipeline，直接把数据发到任意兼容后端，不依赖 Pilot、不读取本地 JSONL 日志。

Q: 默认会采集提示词、回复和工具参数吗？

A: 不会。默认 captureContent=false，仅上报结构化元数据与 token 用量；需要采集正文时显式设置 captureContent: true 或把环境变量 OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT 设为 SPAN_ONLY / SPAN_AND_EVENT。启用前请先确认后端的留存与访问控制策略。

Q: 会替换 DSH 或其他库的全局 OTel Provider 吗？

A: 不会。插件创建的是私有 TracerProvider 与 MeterProvider，不会干扰宿主或其他依赖的全局 Provider；卸载插件时会自动 flush 并 shutdown 内部管道。

Q: 能不卸载就临时关掉吗？

A: 能。把插件配置中的 enabled 设为 false，bundle 仍在但不再采集任何 span 与 metric，DSH 与其他依赖不受影响。

Q: 怎样禁用指标上报以适配只支持 trace 的后端？

A: 设置 exportMetrics: false，或在环境变量里把 OTEL_METRICS_EXPORTER 设为 none；后者是 OpenTelemetry 标准写法，跨实现通用。

Q: HMR 重载或热重启会产生重复 trace 吗？

A: 不会。插件只接管已存在 session 的身份，并从下一次原生 turn/start 开始采集，不会重放历史事件，HMR 后不会出现重复 span。

Q: 能直接对接 Langfuse 吗？

A: 能。把 endpoint 设为 https://cloud.langfuse.com/api/public/otel（自建版用 http://localhost:3000/api/public/otel），并在 headers 里加入 Authorization: Basic <base64(pk:sk)> 与 x-langfuse-ingestion-version: 4，同时把 OTEL_METRICS_EXPORTER 设为 none（Langfuse 的 OTLP 入口只接受 trace）。

上手难度

入门 — 安装命令一行即可开启；常用场景只需设置 OTEL_EXPORTER_OTLP_ENDPOINT 与 OTEL_SERVICE_NAME 两个环境变量，不涉及 DSH 内部概念。

已知问题与限制

• 启用正文采集时，提示词、回复、工具定义、参数与结果会原样进入 span；当 contentMaxChars 触顶时被替换为截断标记对象（包含原始字符数与上限），下游后端需识别此结构
• 仅支持标准 OTLP/HTTP protobuf 上报，不导出 OpenTelemetry Log；如需日志请与独立的 DSH 日志导出插件搭配使用
• 仅在 DSH 0.1.0-rc.6 的 headless 与 web profile 上完成完整运行时验证；早于 0.1.0-rc.6 的 RC 版本不在支持范围内
• 依赖上游 SDK @loongsuite/otel-util-genai 对 OpenTelemetry 2.x 的支持；曾出现过 unmet peer @opentelemetry/sdk-trace-base 警告，已在 SDK 0.1.1 中将 peer 范围拓宽为 ^1.30.0 || ^2.10.0
• maxExportBatchSize 必须不大于 maxQueueSize，否则启动时直接抛出错误
• 隐私敏感场景应在 profile 中显式配置 captureContent: false，确保不会被进程级环境变量覆盖

English | 简体中文

@loongsuite/dsh-plugin is a standalone, open-source observability plugin for DeepSeek Harness (dsh). It observes DSH's native session, agent loop, LLM stream, and tool lifecycle, converts them into OpenTelemetry GenAI traces and metrics, and exports standard OTLP/HTTP protobuf to any compatible backend.

LoongSuite is an open-source observability collection ecosystem built on OpenTelemetry. This repository is its native DSH integration. The plugin does not depend on or require LoongSuite Pilot, a sidecar, a local JSONL tap, or any particular vendor's backend.

Status: stable 0.1.x release. Install @loongsuite/dsh-plugin from npm or the DSH plugin market.

One DSH turn exported over OTLP into self-hosted Langfuse: four react steps, per-call latency and token counts, a failed web_search followed by bash fallbacks, and the ENTRY span's GenAI attributes. Content capture was enabled for this capture; it is off by default.

Data model

DSH session/event + llm/stream
                │
                ▼
      lifecycle coordinator
                │
                ▼
   LoongSuite GenAI OTel utility
                │
                ▼
 private TracerProvider + MeterProvider
                │  OTLP/HTTP protobuf
                ▼
  any OpenTelemetry-compatible backend

One DSH turn produces a single trace with this shape:

ENTRY
└── AGENT
    └── STEP
        ├── LLM
        └── TOOL

Each real LLM attempt gets its own LLM span, so retries remain visible under the same step. Tool calls are correlated with their results by DSH call ID. Errors, aborts, incomplete streams, and plugin shutdown close live spans with an error status instead of leaving them open. Subagent sessions create their own trace and carry DSH parent-session and delegation attributes.

When content capture is enabled, ENTRY and AGENT input messages contain only the turn's direct source.kind=user input. Synthetic DSH context such as runtime snapshots, agent instructions, skill catalogs, goals, and coordinator relays remains visible on the LLM span as part of the complete request actually sent to the model, but is not presented as the user's original input.

The plugin also exports the standard gen_ai.client.operation.duration and gen_ai.client.token.usage metrics. It does not export OpenTelemetry logs; it can coexist with a separate DSH log exporter.

GenAI invocation construction and semantic attributes are powered by the @loongsuite/otel-util-genai SDK.

Compatibility

DSH release candidates older than 0.1.0-rc.6 are not supported. Each plugin release is tested against the latest published DSH version rather than treating successful bundle composition alone as full runtime compatibility.

Install and run

If you have no OTLP backend yet, examples/quickstart starts a local Jaeger backend and gets you a trace in three commands.

Add the plugin to every DSH profile you want to observe:

dsh plugin --profile web add @loongsuite/dsh-plugin
dsh plugin --profile headless add @loongsuite/dsh-plugin

For local development, replace the package name with the checkout path:

dsh plugin --profile web add /absolute/path/to/dsh-plugin

Set a service name and an OTLP/HTTP collector endpoint, then start that profile normally:

export OTEL_SERVICE_NAME=dsh-agent
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
export OTEL_EXPORTER_OTLP_HEADERS='authorization=Bearer%20your-token'

dsh --profile web
# or: dsh --profile headless "summarize this workspace"

The shared endpoint is expanded to /v1/traces and /v1/metrics. The exporter uses the standard OpenTelemetry default when no endpoint is configured.

Configure the plugin

Environment variables are enough for most deployments. You can also edit the plugin row in $DSH_HOME/profiles/<profile>/cordis.patch.yml (by default under ~/.dsh):

- id: loongsuite-observability
  config:
    endpoint: http://localhost:4318
    serviceName: dsh-agent
    headers:
      authorization: Bearer your-token
    resourceAttributes:
      deployment.environment.name: development
    captureContent: false
    exportMetrics: true

Explicit plugin settings take precedence over environment variables.

To enable content capture without editing the profile, set the GenAI content mode before starting DSH:

export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_ONLY
dsh --profile web

Supported standard OpenTelemetry variables are:

• OTEL_EXPORTER_OTLP_ENDPOINT
• OTEL_EXPORTER_OTLP_TRACES_ENDPOINT and OTEL_EXPORTER_OTLP_METRICS_ENDPOINT
• OTEL_EXPORTER_OTLP_HEADERS
• OTEL_EXPORTER_OTLP_TRACES_HEADERS and OTEL_EXPORTER_OTLP_METRICS_HEADERS
• OTEL_SERVICE_NAME
• OTEL_RESOURCE_ATTRIBUTES
• OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT (SPAN_ONLY or SPAN_AND_EVENT enables span content when captureContent is omitted)
• OTEL_METRICS_EXPORTER (none disables metrics when exportMetrics is omitted)

Header and resource values use the standard comma-separated, percent-encoded key=value syntax.

Privacy and runtime behavior

Content capture is off by default. With that default, prompts, responses, tool schemas, arguments, and results are not attached to spans; structural metadata and token counts are still exported. Enabling captureContent or setting the content-capture environment variable to SPAN_ONLY or SPAN_AND_EVENT can send source code, credentials, personal data, or other sensitive content to the configured backend. Review backend retention and access controls before enabling it. Set captureContent: false explicitly when a profile must remain content-free regardless of the process environment.

The plugin owns private OpenTelemetry providers and never replaces DSH's or another library's global provider. It also disposes listeners and flushes providers with the DSH plugin lifecycle. When attached to an already-running/HMR-reloaded profile, it adopts existing session identities but starts collection at the next native turn/start; historical events are not replayed or duplicated.

Development

Node.js 22.19 or newer and pnpm are required.

pnpm install
pnpm run check
pnpm test
pnpm run build
pnpm pack

See CONTRIBUTING.md for the implementation invariants and release checklist.

License

Apache-2.0