dsh-plugin-langfuse: Langfuse observability as a community telemetry backend

[linyp]

Hi all 👋 — sharing a community plugin I just published: dsh-plugin-langfuse exports each dsh agent session to Langfuse as an OpenTelemetry trace tree.

What you see in Langfuse: each turn becomes a trace; each model step a generation (model, provider, gen_ai.usage.* tokens including cache-read/reasoning, time-to-first-token from the first assistant chunk); tool calls become child spans of their step's generation; user messages become trace input; everything else — todo, plan, compaction, plugin events — lands as span events on the turn, so the timeline stays complete even for event types the plugin has never heard of.

Install (published on npm as a profile bundle, prebuilt — no allowBuilds needed):

dsh plugin --profile web add dsh-plugin-langfuse
export LANGFUSE_PUBLIC_KEY=pk-lf-…
export LANGFUSE_SECRET_KEY=sk-lf-…

Why a separate backend instead of pointing session-telemetry-otel at Langfuse: the official backend exports OTLP logs, and Langfuse's OTLP endpoint accepts traces only. So this plugin implements the @deepseek-ai/dsh-session-telemetry seam as an alternative backend on the plain OTel traces SDK, with GenAI semantic-convention plus langfuse.* attributes. Building on the seam (rather than instrumenting the LLM layer) keeps the redaction waterfall, the FEEDBACK_ONLY consent semantics, and replay-identical trees — span timestamps come from the session log, never the wall clock.

Testing: REAL-composition e2e following the official pattern (dsh-app-boot + dsh-loader-smoke) — boots a real app via the Loader and asserts the OTLP payload a mock collector receives — plus a round trip against Langfuse Cloud.

Compatibility: pins @deepseek-ai/dsh-*@0.1.0-rc.6 (developer preview, understood — I'll track the RCs).

Deferred / open questions: feedback/record → Langfuse scores, subagent trace links, and multi-sink support (running Langfuse and the official backend at once would need a seam evolution — happy to discuss if there's upstream interest).

Feedback, issues, and PRs welcome!

• Repo: https://github.com/linyp/dsh-plugin-langfuse
• npm: https://www.npmjs.com/package/dsh-plugin-langfuse

[jiaoqsh]

This is exactly the seam backend we were about to ask for — thank you for building it.

Context: we embed the dsh SDK runtime (stdio JSON-RPC) as one of several agent
runtimes inside a host application, composed from our own deploy-root closure
(pinned to the same 0.1.0-rc.6 wave), so adding your plugin is one manifest
line for us. We independently hit the same wall you describe — the official
backend speaks OTLP logs while Langfuse ingests traces — and building
on the dsh-session-telemetry seam (redaction waterfall, log-derived
timestamps, replay-identical trees) is the design we'd hoped someone would
ship. We plan to evaluate it in our closure and will report back.

Three integration questions from the embedder seat:

1. Attribution / correlation. Our host already emits its own turn-skeleton
   traces into the same Langfuse project (one AGENT observation per turn,
   built from our cross-runtime event contract), stamped with our
   user_id / session_id. Can the plugin's trace identity be steered from
   composition config — e.g. configurable langfuse.session.id /
   langfuse.user.id attributes, or deterministic trace-id derivation from
   the dsh session id — so the two views correlate (or at least sit side by
   side under one session) instead of appearing as unrelated traces?

2. Nesting under an existing trace. Related but stronger: is there (or
   would you take a PR for) a way to hand the plugin a parent trace/span
   context (env TRACEPARENT-style or a config field)? Our host opens the
   turn observation before the runtime subprocess spawns; if the plugin could
   parent its turn trace under that context, embedders would get one unified
   tree — host skeleton outside, dsh's full-fidelity ledger inside — instead
   of choosing between the two or deduping double-traced turns.

3. Multi-sink seam evolution: +1. Your deferred question about running
   Langfuse and the official OTLP-logs backend simultaneously is real for
   us too (ops pipelines want the logs stream; humans want Langfuse). If
   upstream is open to the seam supporting multiple backends, we're an
   interested consumer happy to help think through the contract — the
   capture/cursor side already looks single-consumer by design, so this seems
   like the one place a seam evolution is genuinely needed.

Small compatibility note from our integration: the published latest
dist-tags of several @deepseek-ai/dsh-* packages still point at the
pre-rename 0.0.1-rc.x wave (see #1242), so pinning the whole 0.1.0-rc.6
wave exactly — as your plugin does — is currently the only resolution that
works. Tracking the RC waves together might be worth coordinating once
upstream tags stabilize.

[linyp]

Thanks for the detailed feedback.

1. Attribution/correlation: today langfuse.session.id is fixed to the dsh
   session id, langfuse.user.id is not configurable, and trace IDs are generated
   by the OTel SDK. I agree that explicit correlation configuration is useful.
   My preference is configurable session/user attributes, propagated to every
   observation, rather than deterministic trace IDs as the first mechanism.

2. Parent context: not currently. Each turn is deliberately started with
   root: true from ROOT_CONTEXT. I would be open to W3C trace-context support.
   One detail matters for the contract: does one runtime subprocess correspond to
   one host turn, or can a long-lived subprocess handle multiple host turns?
   A process-level TRACEPARENT works for the former; the latter needs a per-turn
   carrier through the runtime/session telemetry seam.

3. Multi-sink: agreed. In rc.6 the context exposes one sessionTelemetry
   backend, so independently loading both backends is not composable. I think the
   clean design is one capture/redaction coordinator fan-out to multiple sinks,
   with coordinated shutdown and sharing disclosure. I am happy to help discuss
   that upstream.

And yes, I will keep the whole dsh dependency wave pinned and upgrade it
together while the dist-tags remain unstable. Please do report what you find
during the closure evaluation.

[Electricitysheep]

Langfuse 遥测后端正好补上"成本/性能观测"的工具链缺口——和第 14 章（成本工程）的"测量方法"呼应。

已收录进手册生态章节 + 第 14 章工具推荐：https://github.com/Electricitysheep/dsh-handbook/blob/main/docs/14-cost.md

[linyp]

感谢收录 :)

[Electricitysheep]

不客气，好项目值得收录。有空欢迎来手册共建或投稿社区案例。