dsh-tracing

npm package name is dsh-tracing (dsh-trace is blocked by npm name-similarity rules); the harness plugin id stays dsh-trace.

OpenTelemetry-compatible tracing for DeepSeek Harness sessions. Projects session events into a span tree and exports them over OTLP/HTTP (JSON) or the Langfuse v3 ingestion API — no vendor lock, no built-in panel, your existing observability stack stays the source of truth.

What you get

• Span tree per session turn: invoke_agent turn N (root) → step N → execute_tool {name} / chat {model}, with deterministic trace IDs (sha1(sessionId:turn)) so replays and cross-references stay stable.
• GenAI semantic conventions: gen_ai.operation.name, gen_ai.request.model, gen_ai.usage.input_tokens / output_tokens, plus cache-read and reasoning token details. Token invariants are respected: cache-read counts inside input, reasoning inside output — details are exported as attributes, never re-summed.
• Two backends, fan-out enabled: OTLP/HTTP (Jaeger, Tempo, Alloy, …) and Langfuse (traces map to trace-create, tools/steps to span-create, LLM calls to generation-create with usage in Langfuse token units).
• Sanitize before send: built-in key redaction (key, token, secret, password, authorization, …), credential patterns (sk-…, ghp_…, AKIA…, Bearer …, PEM blocks), per-field truncation budgets, and an attribute-length cap. Custom keys/regexes merge in.
• Batching with bounded memory: records queue up to batch.maxQueueRecords, flush every batch.flushIntervalMs or batch.maxRecords, retried with exponential backoff up to retry.maxAttempts, then dropped with a warning — tracing never blocks or crashes a session.
• Fail-safe lifecycle: flushes on session/flush and session/disposed; missing starts still emit best-effort spans (zero-duration, status derived).

Install & enable

dsh plugin --profile web add dsh-tracing

The bundled row ships enabled: false. Enable it in your profile patch:

- insert:
  - id: dsh-trace
    name: dsh-tracing
    config:
      enabled: true
      otlp:
        endpoint: http://localhost:4318   # /v1/traces is appended
        serviceName: deepseek-harness
      # langfuse:
      #   publicKey: pk-lf-...
      #   secretKey: sk-lf-...
      #   baseUrl: https://cloud.langfuse.com

A profile-level patch targeting this id replaces the whole row config (no deep merge) — restate every key you want to keep.

Configuration

Key	Type	Default	Notes
enabled	boolean	false	No-op when false (logs and exits).
otlp	object?	–	OTLP/HTTP backend. endpoint required; /v1/traces appended automatically. Optional serviceName (deepseek-harness), serviceVersion, headers.
langfuse	object?	–	Langfuse backend. publicKey/secretKey required (Basic auth); optional baseUrl (cloud default), release, tags.
capture.turns / capture.steps / capture.tools / capture.llm	boolean	true	Per-kind capture switches.
capture.llm.prompt / capture.llm.completion	boolean	true	Include prompt/completion text (subject to truncation + sanitization).
sanitize.enabled	boolean	true	Master switch.
sanitize.redactKeys	string[]	[]	Extra key names to redact (case-insensitive substring match, merged with builtins).
sanitize.redactPatterns	string[]	[]	Extra regexes for values (invalid entries are skipped, not thrown).
sanitize.truncatePromptChars / …CompletionChars / …ToolInputChars / …ToolOutputChars	number	4000/4000/2000/2000	Per-field truncation budgets (marker appended: …[truncated N chars]).
sanitize.truncateAttributeChars	number	1000	Cap for any single span attribute string.
metadata	object	{}	Static key/values copied onto every span (dsh.trace.* prefix is reserved).
batch.maxRecords / batch.flushIntervalMs / batch.maxQueueRecords	number	256 / 5000 / 2000	Batching and queue bound.
retry.maxAttempts / retry.baseDelayMs / retry.factor / retry.maxDelayMs	number	5 / 1000 / 2 / 60000	Export retry backoff.

Event mapping

The collector consumes harness session/event broadcasts and makes a best-effort projection (snake_case/camelCase, type/event/kind, nested or flat payloads all tolerated):

Event shape	Projection
turn/start, turn/end	invoke_agent turn N span (root of the turn's trace)
step/start, step/end	step N child span
tool/start + tool/end (matched by callId)	execute_tool {name} span
assistant/model/chat/message/attempt events	chat {model} span; usage fields (input_tokens, output_tokens, cache_read…, reasoning…) accepted in both cases

Events this plugin does not model are silently skipped. Unpaired ends still emit a best-effort span; the first end for a session closes any dangling parents.

Known limitations (v0.1)

• Session events are shaped best-effort; harness payloads may evolve and the projector will miss fields it does not recognize (never crash).
• OTel SpanKind is always INTERNAL (1).
• The Langfuse mapping identifies observations by OTel span IDs — queries that join both views should use trace IDs.

Compatibility

Targets @deepseek-ai/cordis ^4.0.1. See the repo-level compatibility policy and the monthly CI job.

License

MIT