Introduction¶

The DSH plugin ecosystem revolves around the concept of “everything is a plugin”: a capability can be plugged into the public seam of the harness. For agent sessions, dsh-observability provides a traces perspective: it collapses the turn, model step, and tool call within a session into an OTLP span tree and sends it to a collector that accepts OTLP/HTTP.

It is a community plugin, not part of the DeepSeek official repository, and should not be interpreted as an official app store.

What is this?¶

dsh-observability is a community plugin maintained by CodePrometheus, licensed under the MIT license, and tagged with the dsh-plugin topic. Its positioning is as the OpenTelemetry traces backend for the DeepSeek Harness telemetry seam: it collapses agent session events into an OTLP span tree.

The plugin implements the harness’s public telemetry Service Definition, working as a second Service Provider alongside the official provider. It only observes the session stream and does not participate in model requests.

Core Capabilities¶

• Export each agent session as an OTLP span tree: a turn corresponds to a trace, a model step corresponds to a child span of that trace, and a tool call corresponds to a child span of that step.
• Add GenAI semantic convention attributes.
• Support FULL, FEEDBACK_ONLY, and DISABLED modes.
• Send to any collector accepting OTLP/HTTP.
• Includes cordis.patch.yml with the plugin package, installable as a profile bundle; or can be mounted as an explicit cordis.yml entry.
• Only observes the session stream via the telemetry Service Definition and does not contribute content to model requests.

Installation and Enablement¶

First, install the plugin as a profile bundle, then set the run mode and OTLP endpoint. The endpoint must be a full traces path.

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

If you need to mount it explicitly in cordis.yml, you can use a configuration line similar to the following. The example below lists only verified fields; an empty processor object indicates no additional processor configuration override.

- 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

The main configuration items are as follows:

When in DISABLED mode, no transport is constructed, and no data leaves the process. Configuration errors will fail during the plugin loading phase, occurring before any transport construction.

Typical Usage¶

Enable Upload Mode¶

In a local or controlled environment, you can set the mode to FULL first, then point the endpoint to a collector that accepts OTLP/HTTP.

export DSH_OBSERVABILITY_MODE=FULL
export DSH_OBSERVABILITY_OTLP_URL=http://127.0.0.1:4318/v1/traces

Run Tests¶

The plugin provides unit tests and real-composition end-to-end (e2e) tests. These tests verify configuration, the collapsing logic, and the actual composition of build artifacts on a mock collector.

npm test
npm run build && npm run test:e2e

npm test runs the unit tests; npm run build && npm run test:e2e runs the e2e tests after building, targeting a mock collector.

Suitable Scenarios and Notes¶

Suitable for:

• Developers who want to put DSH agent sessions into a trace backend and view sessions by turn, model step, and tool call.
• Teams that already have a collector accepting OTLP/HTTP and need to ingest dsh session events into OpenTelemetry traces.
• Scenarios where you want to add observability capabilities without modifying the model request path.

Notes:

• The plugin runs with the current dsh process permissions. Check the source code, dependencies, and MIT license before installing.
• DISABLED is the default mode; nothing is constructed, and no data leaves the process.
• In upload mode, span attributes may carry user and assistant message content, tool arguments and results, model and usage metadata, and the session current working directory (cwd).
• The plugin does not provide redaction rules; if exporting beyond trust boundaries, the deployment side needs to mount rules themselves.
• The serialization content of each span attribute is truncated by maxAttributeChars; the canonical session log retains full bytes.
• Provider API keys do not enter telemetry structurally, because adapter credentials are constructor parameters, not session events.
• DeepSeek Harness is in developer preview with no compatibility commitment; this plugin pins precise @deepseek-ai/dsh-* versions.
• The documentation lists best-effort delivery as a Known Limitation; whether it meets production requirements should be evaluated based on your own collector and reliability requirements.

Links¶

GitHub: https://github.com/CodePrometheus/dsh-observability