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.