Add LiveKit Agents instrumentation coverage + warn about the OTel SDK v1/v2 setTracerProvider mismatch

[samuelarbolai]

Describe your idea or feedback

The instrumentation guidance (references/instrumentation.md) lists framework integrations for OpenAI, LangChain, LlamaIndex, Vercel AI SDK, and LiteLLM — but not LiveKit Agents (Node.js).

Wiring @langfuse/otel into a LiveKit Agents worker hits a non-obvious, costly trap. @langfuse/otel (v5) requires OpenTelemetry JS SDK v2 (@opentelemetry/sdk-trace-node@2.x). But @livekit/agents@1.2.0's setTracerProvider(provider, { metadata }) does:

if (options?.metadata) provider.addSpanProcessor(new MetadataSpanProcessor(options.metadata));
tracer.setProvider(provider);

addSpanProcessor() was removed in SDK v2 (providers are immutable; processors are constructor-only — NodeTracerProvider.prototype.addSpanProcessor is undefined). So the metadata path throws TypeError: provider.addSpanProcessor is not a function, and because it runs inside the agent's job entry, it crashes the worker on every call. The no-metadata path (setTracerProvider(provider)) is fine. We shipped this once and every flow crashed on entry until we wrapped the call non-fatally.

This likely affects any host framework whose tracer-provider hook is written against the removed v1 addSpanProcessor API.

What would the ideal outcome look like?

• Add LiveKit Agents (Node.js) to the instrumentation guidance as an OTel-exporter-based integration: import the telemetry namespace from @livekit/agents (there is no ./telemetry subpath export), build a NodeTracerProvider with LangfuseSpanProcessor, and pass it to telemetry.setTracerProvider(provider).
• Add a general caveat: when a host framework exposes its own setTracerProvider/provider hook, verify it doesn't rely on the removed v1 addSpanProcessor API before pairing it with @langfuse/otel (SDK v2), and wrap provider registration defensively so a tracing failure can't crash the host process.

[Lotte-Verheyden]

Hi @samuelarbolai , thanks for flagging this! The skill is instructed to look up the integration pages on our docs site, no need to add specific code to the skill itself. We updated our Livekit docs accordingly now: https://langfuse.com/integrations/frameworks/livekit, let me know if it happens again!