dsh-langfuse
dsh-langfuse：DeepSeek Harness 的 Langfuse LLM 可观测性——每个代理会话对应一棵 OpenTelemetry 追踪树，并包含反馈评分和子代理谱系。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:TtTRz/dsh-langfuse#17c8cd5e2512a4dbee7cf569bdd058bb6a03d090Langfuse 以 dsh-langfuse 发布，当前版本为 0.2.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
Langfuse LLM observability for DeepSeek Harness — one OpenTelemetry trace tree per agent session, with feedback scores and subagent lineage.
Send every agent session to Langfuse as an OpenTelemetry trace tree — turn → trace, model step → generation, tool call → tool span — with GenAI semantic-convention attributes, token usage, time-to-first-token, and error statuses.
Content-Length header, never chunked. Some Langfuse deployments sit behind gateways that mangle chunked POST bodies (400 Failed to parse OTel JSON Trace); this transport sidesteps that class of bugs entirely./feedback records become TEXT scores on the session's latest turn trace.FULL (live), FEEDBACK_ONLY (export only when the user records feedback), DISABLED (default; nothing leaves the process).includeGenerationInput is on.dsh plugin --profile web add dsh-langfuse
export LANGFUSE_PUBLIC_KEY=pk-lf-...
export LANGFUSE_SECRET_KEY=sk-lf-...
# optional: self-hosted or non-EU region
export LANGFUSE_HOST=https://langfuse.example.com
dsh web # restart the running instance, then take a turn
With a key present the backend runs in FULL mode; without one it is DISABLED. LANGFUSE_TELEMETRY_MODE=FEEDBACK_ONLY narrows sharing to feedback-gated release, and LANGFUSE_INCLUDE_GENERATION_INPUT=1 exports generation inputs.
The bundled patch disables the base profile's session-telemetry-otel row (the telemetry seam accepts exactly one backend per context) and mounts this one. dsh --profile web --dump-config shows the composed result without booting.
cordis.yml row- id: session-telemetry-langfuse
name: dsh-langfuse
config:
mode: FULL # FULL | FEEDBACK_ONLY | DISABLED (default)
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: {} # optional; passed verbatim to BatchSpanProcessor
includeGenerationInput: false
Version 0.2.0 requires DeepSeek Harness 0.1.7-rc.2. The session and telemetry SDKs are peer dependencies and must be provided by the same Harness installation. Install through dsh plugin; do not install an older telemetry SDK alongside a newer host.
Upgrading from 0.1.x removes the pinned telemetry 0.1.0-rc.6 dependency that could break session creation or restoration with session.events is not iterable. Restart Harness after upgrading. Other Harness versions are not covered by the compatibility checks.
| Field | Default | Meaning |
|---|---|---|
mode | DISABLED | FULL exports every session live; FEEDBACK_ONLY exports the canonical session log only when feedback is recorded; DISABLED constructs nothing. |
exporter.url | — | Full OTLP traces endpoint (…/api/public/otel/v1/traces). Required unless DISABLED. |
exporter.timeoutMillis | 10000 | Per-request timeout. |
auth.publicKey / auth.secretKey | — | Langfuse project key pair (Basic auth). Required unless DISABLED. |
processor | {} | Passed verbatim to BatchSpanProcessor (scheduledDelayMillis, maxQueueSize, …). Retries (bounded backoff, 6 attempts) live in the exporter. |
includeGenerationInput | false | Export langfuse.observation.input (system prompt / tool schemas / model / user prompt). |
maxAttributeChars | 16384 | Per-attribute payload ceiling; longer payloads are truncated with a …[truncated] marker (the canonical log keeps the full bytes). |
shutdownTimeoutMillis | 3000 | Deadline on the SDK's shutdown drain. |
feedbackScoreName | user-feedback | Langfuse score name for /feedback pushes. |
| dsh session event | Langfuse concept |
|---|---|
turn/start / turn/end | trace (turn N; error end reasons → ERROR status) |
step/start + request/header + assistant/message | generation (step T.S) — model, provider, output, gen_ai.usage.* tokens |
| first token in the embedded assistant stream | langfuse.observation.completion_start_time (TTFT) |
tool/call + tool/result | tool span (arguments → input, result → output, isError → ERROR) |
user/message | trace input |
feedback/record | TEXT score on the session's latest turn trace |
| subagent session turns | trace links to the parent session's trace |
agent-error ops record | exception event + ERROR status |
| every other event type (todo, plan, compaction, …) | span event on the open turn |
Correlation attributes use this package's own vocabulary (dsh.turn_idx, dsh.step_idx, dsh.event_seq, …) so multiple telemetry backends can share one Langfuse project without attribute collisions.
SessionTelemetryBackend (@deepseek-ai/dsh-session-telemetry), so it captures every event — including ones it has never heard of — with the seam's consent semantics and redaction waterfall for free.BasicTracerProvider + BatchSpanProcessor, serialized with @opentelemetry/otlp-transformer, and delivered by a custom SpanExporter with Content-Length and bounded retries.SessionTimeline replays the flat record stream into span trees keyed by (session.id, turn, step). Span boundaries always use the record's own timestamp — live capture and canonical-log replay produce identical trees.langfuse.session.id + dsh.turn_idx + dsh.event_seq.npm run check # biome + typecheck + vitest (unit & seam integration) + build
npm run test:install -- /path/to/stock-dsh-install
The installation smoke test requires a separate stock @deepseek-ai/dsh@0.1.7-rc.2 installation. It installs and reinstalls the packed plugin in a temporary profile, checks FULL-mode activation and session creation/reopening, and uses only a local mock collector. It does not send prompts or contact a real Langfuse project.
Tests cover config validation, the folding timeline, the transport (Content-Length, no Transfer-Encoding, retry/backoff), score pushes, and a full seam integration that drives a real SessionTelemetryCoordinator and asserts the wire payload.