Back to directory

dsh-observe

In a curated listMaintenance: Active

perrylink/dsh-observe

OpenTelemetry and Langfuse observability exporter for DeepSeek Harness: turn/step/tool/LLM spans, token and cost metrics, sanitized prompt/completion capture, async batching, bounded offline buffering, retry with backoff

View on GitHubHomepage
$ dsh plugin --profile web add dsh-observe

16

stars

2

forks

TypeScript

Language

Apache-2.0

License

2026-08-16

Created

2026-11-18

Last push

Apache-2.0 TypeScript plugin for DeepSeek Harness (dsh 0.2.x, Node ^22.19 || >=24.9): a passive OTLP/Langfuse exporter with pre-send redaction, bounded offline buffering and backoff retry.

DSH integration

Native runtime

Author-claimed

Safety audit

Unaudited

Last verified

2026-11-20

License

Apache-2.0

01What can it help you accomplish?

  • Get every DeepSeek Harness session into your existing observability stack as standard traces and metrics

    One trace per turn, with spans for steps, tool calls (duration, status, retry inference) and LLM generations, plus per-provider/model token counters, USD cost counters and an optional context-pressure gauge

    Platform and agent engineers running DeepSeek Harness who need per-session latency, tool usage and spend visibility in OpenTelemetry or Langfuse

  • Ship prompt/completion observability without shipping secrets

    Records that are key-name redacted, secret-pattern scrubbed and character-budget truncated before they are queued, buffered or sent — or sizes only if you switch the payload capture off

    Teams with data-handling or compliance requirements that still want LLM-level tracing

  • Keep telemetry flowing through backend outages without stalling the harness

    Async batched delivery with deterministic exponential backoff and a bounded persistent spool; undelivered batches are still there after a restart

    Operators who cannot let an observability backend outage block or slow their agent sessions

02How to install into DeepSeek Harness

Prerequisites

  • Node `^22.19.0 || >=24.9.0` — the package is pure ESM and `zod` is its only runtime dependency
  • A DeepSeek Harness CLI whose engines range matches `>=0.2.1-0 <0.3.0` or `>=0.2.2-0 <0.3.0` (the plugin is developed and tested against `@deepseek-ai/dsh@0.2.2-rc.1`)
  • At least one backend to point it at: an OTLP/HTTP endpoint (`/v1/traces` and `/v1/metrics` are appended by the plugin) or Langfuse `baseUrl` + `publicKey` + `secretKey`

Installation steps

  1. 01

    Install into a profile: `dsh plugin --profile web add dsh-observe` for the published npm version, `dsh plugin --profile web add github:PerryLink/dsh-observe` for the latest main, or a local tarball via `dsh plugin --profile web add ./dsh-observe-<version>.tgz`.

    $ dsh plugin --profile web add dsh-observe

  2. 02

    If pnpm blocks the build with `ERR_PNPM_IGNORED_BUILDS` (the harmless esbuild platform-binary check), add `allowBuilds: { esbuild: true }` to your `pnpm-workspace.yaml` — the dsh CLI prints the exact snippet.

  3. 03

    Turn it on in the profile patch: the `cordis.patch.yml` line ships disabled, so set `enabled: true` and configure `otlp.endpoint` and/or `langfuse.baseUrl` + `langfuse.publicKey` + `langfuse.secretKey`; both backends can be on at once.

Verify the integration

  • `dsh --profile web --dump-config | grep -A2 'id: dsh-observe'` to confirm the plugin line and your values landed in the profile.
  • There is no `/observe` command to trigger: check that the first trace and metrics arrive in your OTLP backend (or observations in Langfuse), and with `remote.enabled: true` read `observe/status` for configured backends, queue depth and spool occupancy.

Rollback

  • `dsh plugin --profile web remove dsh-observe`, or delete the block from the profile patch.

03DSH integration and capability boundaries

DSH integrationNative runtime

A DeepSeek Harness plugin loaded through `dsh plugin --profile <name> add dsh-observe`; it listens to the harness session/event stream and exports it as OTLP traces/metrics and Langfuse observations, with no tools or commands registered.

  • Turn / step / tool / LLM spans

    the harness session/event stream→one trace per turn with step, tool-call (duration, status, retry inference) and LLM generation spans; span and trace ids are deterministic and reproducible

  • Token, cost and context metrics

    provider/model attributes from the session events, plus optional `pricing` rules→token counters per provider/model, USD cost counters (first matching pricing rule wins) and an optional `ctx.tokenMeter`-driven context-pressure gauge

    cost metrics only appear when a `pricing` entry matches the model
  • Pre-send sanitization

    prompts, completions, tool arguments and tool results→records with structural key names redacted, built-in secret patterns plus custom regexes applied, and character budgets enforced (4000 prompt / 4000 completion / 2000 tool input / 2000 tool output / 512 attribute)

    payloads are truncated, so long prompts and completions are not preserved verbatim
  • Durable async delivery

    queued span and metric records→batches flushed by count (256) or interval (5000 ms), retried 5 times with deterministic exponential backoff (1000 ms × 2, capped at 60000 ms), then spilled to a bounded persistent spool (10000 records, oldest evicted first) that is re-drained every 30000 ms and survives a restart

    spooled records occupy storage; the spool is bounded and evicts the oldest entriesrecords read back from storage are re-validated before reaching a sink
  • Runtime kill switch

    `observe/setEnabled`, exposed only when `remote.enabled: true`→start/stop of export at runtime without uninstalling, plus `observe/status` with the master-switch state, configured backends, queue depth and spool occupancy

    adds a remote service named `observe` to the profile — do not register the same name twice

04Who is it for? When not to use it?

Good for

  • Platform and agent engineers running DeepSeek Harness who need per-session latency, tool usage and spend visibility in OpenTelemetry or Langfuse
  • Teams with data-handling or compliance requirements that still want LLM-level tracing
  • Operators who cannot let an observability backend outage block or slow their agent sessions

Not for

  • Version-pinned on both sides: `engines.dsh` accepts `>=0.2.1-0 <0.3.0 || >=0.2.2-0 <0.3.0` with the current baseline at `@deepseek-ai/dsh@0.2.2-rc.1`, and the package needs Node `^22.19.0 || >=24.9.0` as pure ESM. The adapter tracks session format V4 (`role: 'tool'` messages), so it targets the 0.2.x harness line.
  • Langfuse key pairs and OTLP headers are sent only to the endpoints you configure, and the plugin stores no credentials itself — the README tells you to use credential references or environment injection and not to commit secrets into the profile patch.

05Compatibility, maintenance and safety notes

  • Version-pinned on both sides: `engines.dsh` accepts `>=0.2.1-0 <0.3.0 || >=0.2.2-0 <0.3.0` with the current baseline at `@deepseek-ai/dsh@0.2.2-rc.1`, and the package needs Node `^22.19.0 || >=24.9.0` as pure ESM. The adapter tracks session format V4 (`role: 'tool'` messages), so it targets the 0.2.x harness line.
  • Langfuse key pairs and OTLP headers are sent only to the endpoints you configure, and the plugin stores no credentials itself — the README tells you to use credential references or environment injection and not to commit secrets into the profile patch.
  • The plugin requests outbound network to your configured endpoints, read access to the session event stream and write access to the offline spool. It has no native code and no filesystem access, registers no model tools, no user-visible commands and no client slots, and reads the live event stream instead of session log files.
  • There is no sampling: every enabled span family is exported, so busy profiles must tune the `capture.*` switches and `batch.maxBufferRecords` themselves. OTLP metrics skip the retry and buffer path by design — a dropped metrics flush heals on the next cumulative aggregation.
2026-08-162026-11-13v0.2.29

Apache-2.0 · actively maintained (latest release v0.2.29, published 2026-11-18)

06Frequently asked questions

Are my prompts and tool arguments sent to the backend verbatim?

No. Three layers run before a record is queued: structural key-name redaction (key, token, secret, password, authorization, credential and apiKey are always on the list, extendable via `sanitize.redactKeys`), built-in secret patterns (API keys, GitHub tokens, AWS keys, bearer credentials, private keys) plus your own regexes in `sanitize.redactPatterns`, and character budgets — 4000 characters for prompt and completion, 2000 for tool input and output, 512 for span attributes. If you only want volume, set `llm.prompt` and `llm.completion` to `false` and the records keep sizes and counters only.

What happens when the backend is down or the network drops?

Ordinary spans and metrics follow retry → overflow to the offline spool: batches are retried `retry.maxAttempts` times (default 5) with a deterministic `retry.baseDelayMs × retry.factor` backoff, then spilled into the bounded persistent spool (`batch.maxBufferRecords`, default 10000, oldest evicted first) when retries run out or the in-memory queue exceeds `batch.maxQueueRecords`. The spool is re-drained every `batch.bufferRetryIntervalMs` (default 30000) and undelivered batches survive a restart. OTLP metrics are the documented exception: they aggregate cumulatively, so a lost flush heals on the next one.

Is the model's reasoning / chain of thought exported too?

Yes by default. `llm.reasoning` is on, and reasoning is sent as a separate `gen_ai.completion.reasoning` attribute — never merged into `gen_ai.completion`; in Langfuse it lands in the generation metadata. The README warns that reasoning can contain the user's own text or context the model echoed verbatim, so evaluate your compliance requirements before export and set `llm.reasoning: false` if you do not need it. `llm.completion: false` disables both the completion body and reasoning.

Does it slow the session down?

Collection and sanitization run synchronously inside the event handler, but all sending is asynchronous: the queue flushes by count or on a timer, and `session/flush` is only a best-effort kick — the persistence checkpoint never waits for a remote backend. Export failures are logged, counted as `observe.export_failures`, retried and finally spooled, and an exception thrown by the event handler itself is caught and recorded, so observability does not sit on the harness hot path.

Will it collide with other plugins in the same profile?

The registration surface is deliberately narrow: it injects only the `storageDomain` service key, listens only to `session/event`, `session/flush` and `session/disposed`, and registers no tools, commands, client slots or waterfalls. The one name to watch is the optional `observe` remote service (`remote.enabled`, off by default) — if another plugin already owns that service name, enable only one of them. Running a second observability plugin is fine (Cordis broadcasts events, so neither starves), but you will get two sets of traces.

08Data and sources

  • Author-claimedgithub.com2491014f11d1…

    把每次会话变成标准 OTLP trace 与 Langfuse 观测——发出去之前先脱敏,默认什么都不发。

  • Author-claimedgithub.com2491014f11d1…

    它只做导出——不注册任何模型工具、不注册用户可见命令,全部行为由配置决定

This page is generated from the project’s public documentation, repository metadata and a structured parse of DSH Plugins; last verified on 2026-11-20. Found an error? Submit a correction.

🏆

Best DeepSeek Harness Plugins

Twelve plugins worth installing first — picked from the whole catalog, across every category.

DSH Plugins is an independent community directory of DeepSeek Harness plugins. Not affiliated with or endorsed by DeepSeek. Third-party plugins are not security-audited — review the source before installing.

New DeepSeek Harness plugins, weekly. No spam.