dsh-langfuse

English | 中文

Community DeepSeek Harness bundle that exports one Langfuse trace per agent turn. Each trace has a session.turn root with direct GENERATION children for LLM requests and TOOL children for tool executions. It also exports LLM, tool, and active-session metrics through OTLP/HTTP.

Install from GitHub

Pin an audited release tag when installing:

dsh plugin --profile headless add github:leungBH/dsh-langfuse#v0.1.0

Git installs build this TypeScript package from source. With pnpm 10 or later, the first installation may ask you to authorize its prepare script. Add the exact package key reported by pnpm to $DSH_HOME/profiles/headless/pnpm-workspace.yaml:

allowBuilds:
  dsh-langfuse: true

Then repeat the install and verify the bundle layer:

dsh plugin --profile headless add github:leungBH/dsh-langfuse#v0.1.0
dsh --profile headless --dump-config

The effective configuration should contain a dsh-langfuse bundle layer and the dsh-langfuse-tracing, dsh-langfuse-metrics, and dsh-langfuse-instrumentation rows.

Configure Langfuse

The plugin never stores credentials or changes the selected DSH model. Configure a working model through normal DSH settings, then export Langfuse credentials:

cp .env.example .env
# Fill LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY.

The runnable scripts build the standard OTLP Basic authorization header in memory and enable both exporters:

./examples/run-demo.sh "list the first three files in this directory"
# Windows PowerShell:
./examples/run-demo.ps1 "list the first three files in this directory"

DSH_TRACE_CONTENT defaults to OFF. Set it to FULL only when uploading prompts, responses, tool arguments, and tool results is acceptable for the selected project.

Data model

• One DSH Session maps to one Langfuse Session through langfuse.session.id.
• One DSH turn maps to one Langfuse Trace.
• session.turn is the root SPAN.
• LLM calls are direct GENERATION children with model, token, TTFT, duration, and outcome data.
• Tool executions are direct TOOL children with tool name, duration, and outcome data.
• Children close before their root on success, failure, Session disposal, and plugin teardown.

Environment

Variable	Purpose
LANGFUSE_PUBLIC_KEY	Project-scoped Langfuse public key used by the example scripts
LANGFUSE_SECRET_KEY	Project-scoped Langfuse secret key used by the example scripts
LANGFUSE_BASE_URL	Cloud region or self-hosted base URL; defaults to https://cloud.langfuse.com
DSH_TRACE_MODE	FULL enables trace export; the shipped bundle default is DISABLED
DSH_METRICS_MODE	FULL enables metric export; the shipped bundle default is DISABLED
DSH_TRACE_CONTENT	OFF or FULL; defaults to metadata-only OFF
DSH_OTEL_EXPORTER_OTLP_TRACES_ENDPOINT	Explicit OTLP trace endpoint
DSH_OTEL_EXPORTER_OTLP_METRICS_ENDPOINT	Explicit OTLP metric endpoint
OTEL_EXPORTER_OTLP_HEADERS	Standard OTel exporter headers; the scripts set Basic authorization here

Compatibility and limitations

The first release targets official DSH builds that do not yet ship the sessionTracing and sessionMetrics services. DSH is pre-release software, so verify the pinned plugin commit after every DSH upgrade. Do not install this community bundle alongside a DSH build that already mounts those services; disable or remove the community bundle first.

This standalone version does not guarantee active trace-context propagation through provider HTTP requests, local subprocesses, or subagent forks. Those paths require stable upstream extension points. The turn traces produced by this plugin remain internally complete and have no orphan observation parents.

Langfuse Cloud accepts OTLP traces and metrics but not OTLP logs. Collector export failures are reported by the OTel SDK and do not replace the agent result.

Development

pnpm install
pnpm run build
pnpm run typecheck
pnpm test
pnpm pack --pack-destination .artifacts

This project contains code derived from MIT-licensed DeepSeek Harness observability packages. See LICENSE.