Preface

The philosophy of DSH is “everything is a plugin”; the plugin directory is a community site with no official affiliation to DeepSeek / Huansuan. When debugging agent sessions, a common requirement is to put model calls, tool calls, token usage, TTFT, and subsequent user feedback into a single traceable view. dsh-langfuse is a DSH plugin prepared for this purpose: it organizes each agent session into an OpenTelemetry trace tree and sends it to Langfuse.

Below introduces its positioning, capabilities, installation, and notes.

What is This

dsh-langfuse is a DSH plugin maintained by TtTRz under the MIT license. Its one-sentence positioning is: Langfuse LLM observability for DeepSeek Harness—each agent session is an OpenTelemetry trace tree, complete with feedback scores and subagent lineage.

It is not a replacement for DSH’s logging system, but rather organizes existing session events into visible traces, generations, tool spans, and scores within Langfuse. The default mode does not export data; it is only enabled after configuration.

Core Features

First, the events it covers: turns, generations, and tool calls all go into Langfuse, carrying model, provider, usage (including cache-read and reasoning tokens), and TTFT.

Specific capabilities include:

  • Full session tracing: Every turn, generation, and tool call falls into Langfuse.
  • Content-Length transport: Spans are sent in a single write with an explicit Content-Length header, no chunking.
  • Feedback scores: /feedback records become TEXT scores on the latest turn trace of that session.
  • Subagent lineage: Child session turn traces link to the parent session’s trace; this is best-effort within the same process.
  • Three sharing modes: FULL for real-time export; FEEDBACK_ONLY for export only after user records feedback; DISABLED is the default, content stays within the process.
  • Opt-in inputs: Generation inputs (system prompt / tools / prompt) are only exported when includeGenerationInput is enabled.
  • Fail-loud config: URL errors, missing keys, and invalid bounds throw errors during plugin loading, before any transport is established.

Installation and Enablement

First, confirm the runtime environment meets plugin requirements:

Node engine: >=22.19
Peer dependency: @deepseek-ai/cordis >=4.0.1

Add the plugin:

dsh plugin --profile web add dsh-langfuse

Configure Langfuse key and host:

export LANGFUSE_PUBLIC_KEY=pk-lf-...
export LANGFUSE_SECRET_KEY=sk-lf-...
export LANGFUSE_HOST=https://langfuse.example.com

Start the Web interface:

dsh web

Verified behavior: when keys exist, the backend runs in FULL mode; when keys are absent, it runs in DISABLED mode.

If you want to narrow the sharing scope, you can use:

LANGFUSE_TELEMETRY_MODE=FEEDBACK_ONLY
LANGFUSE_INCLUDE_GENERATION_INPUT=1

There are two easily overlooked default values: includeGenerationInput defaults to false; exporter.url and auth.publicKey / auth.secretKey are required fields unless in DISABLED.

Typical Usage

Default Real-Time Export

The environment variable example above is the minimal path: install the plugin, set Langfuse keys, start dsh web, and then execute a turn.

Export Only After Recording Feedback

export LANGFUSE_PUBLIC_KEY=pk-lf-...
export LANGFUSE_SECRET_KEY=sk-lf-...
export LANGFUSE_HOST=https://langfuse.example.com
LANGFUSE_TELEMETRY_MODE=FEEDBACK_ONLY
dsh web

Explicitly Writing to cordis.yml

It can also be written as a clear cordis.yml row:

- id: session-telemetry-langfuse
  name: dsh-langfuse
  config:
    mode: FULL
    exporter:
      url: https://cloud.langfuse.com/api/public/otel/v1/traces
    auth:
      publicKey: !!js process.env.LANGFUSE_PUBLIC_KEY
      secretKey: !!js process.env.LANGFUSE_SECRET_KEY
    processor: {}
    includeGenerationInput: false

mode can be FULL, FEEDBACK_ONLY, or DISABLED, with DISABLED being the default. processor is an optional field. If the property payload exceeds maxAttributeChars (default 16384), it will be truncated with a …[truncated] marker.

Applicable Scenarios and Notes

Suitable for the following situations:

  • Already using Langfuse and want to integrate DSH sessions into existing observability workflows.
  • Need to view model, provider, usage, TTFT, and tool calls.
  • Want to attach /feedback records as TEXT scores to the latest turn trace.
  • Need to link child session traces with parent session traces within the same process.

Please note before use:

  • The plugin runs with the current DSH process permissions. You should check the source code, dependencies, and license before installing.
  • The plugin directory is a community directory, not an official app store; it has no official affiliation with DeepSeek/Huansuan.
  • There can only be one backend per context; the bundled patch will disable the session-telemetry-otel row of the base profile.
  • There is no durable delivery (at-most-once); score push is fire-and-forget, with failures only logged.
  • Subagent lineage is best-effort within the same process; when recovering parent sessions across restarts, the trace ID is unknown.
  • By default DISABLED does not export data; before choosing FULL or FEEDBACK_ONLY, confirm the sharing boundaries.

Ending

The value of dsh-langfuse lies in placing DSH agent session turns, generations, tool calls, usage, and feedback into a single trace tree, facilitating troubleshooting and observation.

  • Directory page: dsh-langfuse page in the DSH Plugin Directory
  • GitHub: https://github.com/TtTRz/dsh-langfuse