[cryptotavares]

Description

Summary: Propagate telemetry.traceName to the Langfuse trace and its observations. Use agent-runner when no name is configured.

Problem

The configured name currently names only the root observation. Trace propagation omits the name, so observations lack an explicit langfuse.trace.name attribute.

telemetry.traceName = "pr-visual-validation.plan"

Before: root observation name = "pr-visual-validation.plan"
        trace propagation omits traceName
After:  root observation name = "pr-visual-validation.plan"
        root, generation, tool: langfuse.trace.name = "pr-visual-validation.plan"

Changes

• Resolve the trace name once per message handler.
• Include the resolved name in root and generation trace contexts. Tool observations receive the same context during generation handling.
• Forward traceName through propagateAttributes.
• Add an in-memory integration test using the real NodeSDK and LangfuseSpanProcessor.
• Update the telemetry type documentation.

Solution

flowchart TD
    A[Per-run telemetry] --> B[Resolve configured name or agent-runner once]
    B --> C[Include traceName in init and generation contexts]
    C --> D[Forward traceName through propagateAttributes]
    D --> E[Root observation]
    D --> F[Generation observation]
    D --> G[Tool observations]
    B -. root observation name .-> E

    classDef new fill:#fff3cd,stroke:#d39e00
    class B,C,D new

Loading

Yellow boxes show the new trace-name handling.

What changes

Input or call	Before	After
Custom telemetry.traceName	Names the root observation	Also sets langfuse.trace.name on root, generation, and tool observations
Omitted telemetry.traceName	Root observation uses agent-runner	All three observation types also carry trace name agent-runner
Two runs sharing one session	Each run has its own trace	Each trace carries its own resolved name; the test checks two trace IDs and one session

Decisions for reviewers

Decision	Reason
Use SDK attribute propagation	The installed SDK supports traceName and emits the trace-level attribute
Keep the fallback per handler	Root observation naming and trace propagation use the same resolved value
Capture real SDK output in memory	Verify emitted attributes without remote Langfuse writes
Pass empty metric readers and log processors in the test	Explicitly disable unrelated exporters instead of inheriting environment defaults

Review guide

Order	Files	Focus
1	src/telemetry/message-handler.ts	Per-handler fallback and both propagation sites
2	src/telemetry/tracing.ts	Optional traceName forwarding
3	src/telemetry/trace-name.test.ts, message-handler.test.ts, tracing.test.ts	Real emitted attributes, custom/default names, and propagation arguments
4	src/types.ts	Public description and default value

Testing

Runtime: Node v24.22.1, Yarn 4.16.0.

• yarn build && yarn typecheck && yarn lint && CI=true yarn test passes.
• Vitest: 30 files passed, 1 skipped; 653 tests passed, 4 skipped; no type errors.
• Coverage thresholds pass: statements 98.47%, branches 95.96%, functions 98.67%, lines 98.46%.
• The SDK integration test captures six spans across custom and default names. It checks each observation name, trace-name attribute, session, and two distinct trace IDs.
• Build completes before package analysis. Verified dist/index.mjs, dist/index.cjs, dist/index.d.mts, and dist/index.d.cts.
• yarn attw --pack --format json passes with assertions that types are included and package problems are empty. Node10, Node16 CJS, Node16 ESM, and bundler entrypoints resolve to declarations.
• git diff --check passes.

Review note

The independent review reported no actionable regressions. Addressed the optional test-isolation nit with metricReaders: [] and logRecordProcessors: [], supported by the installed SDK. The final full suite passes with those options.

Verification uses local fixtures and in-memory span export. Live Langfuse UI behavior is not verified.

References

No linked issue.

Checklist

• Tests are included if applicable
• Changelog changes omitted as requested

[cryptotavares]

CI blocker — shared lockfile-free dependency drift

Confirmed Compatibility test (20.x), run 40555896191 / job 122372348426 fails at Install dependencies via Yarn, before tests. After rm yarn.lock && YARN_ENABLE_IMMUTABLE_INSTALLS=false yarn, LavaMoat exits 1 with the same missing policy path:

@langfuse/otel>@opentelemetry/otlp-exporter-base>@opentelemetry/otlp-transformer>protobufjs [1 location(s)]

This matches the existing diagnosis and byte-identical base-package reproduction: fresh Langfuse 5.14.0 resolution uses the peer path introduced in 5.12.0; the existing deny policy covers only the older exporter path. The shared issue also reproduces on base 804e4607aae55941d655e8015ba7321524a99959. This PR changes no dependency, workflow, or LavaMoat configuration.

Build, lint, regular tests on Node20/22/24, and security checks pass. Compatibility 22/24 are cancelled by fail-fast. The compatibility blocker remains; no source changes or workflow reruns were made. PR stays draft at b34b8e54d15c89695516c571b692869d12c682f2.

[cryptotavares]

Updated LavaMoat policy in ce0f395 via yarn allow-scripts auto. The newly resolved protobufjs lifecycle-script path is explicitly set to false. Verified yarn allow-scripts, installation and the full test suite against a fresh dependency resolution (653 passed, 4 skipped), then restored the branch lockfile and passed immutable installation and lint. CI is rerunning on this commit.