@livekit/agents 1.0.18 → 1.0.20

package/src/stt/stt.ts

@@ -135,6 +135,10 @@ export abstract class STT extends (EventEmitter as new () => TypedEmitter<STTCal
    * transcriptions
    */
   abstract stream(): SpeechStream;
+
+  async close(): Promise<void> {
+    return;
+  }
 }
 
 /**

package/src/telemetry/index.ts

@@ -0,0 +1,10 @@
+// SPDX-FileCopyrightText: 2025 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+// TODO(brian): PR4 - Add logging integration exports
+// TODO(brian): PR5 - Add uploadSessionReport export
+
+export * as traceTypes from './trace_types.js';
+export { setTracerProvider, setupCloudTracer, tracer, type StartSpanOptions } from './traces.js';
+export { recordException, recordRealtimeMetrics } from './utils.js';

package/src/telemetry/trace_types.ts

@@ -0,0 +1,88 @@
+// SPDX-FileCopyrightText: 2025 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+// LiveKit custom attributes
+export const ATTR_SPEECH_ID = 'lk.speech_id';
+export const ATTR_AGENT_LABEL = 'lk.agent_label';
+export const ATTR_START_TIME = 'lk.start_time';
+export const ATTR_END_TIME = 'lk.end_time';
+export const ATTR_RETRY_COUNT = 'lk.retry_count';
+
+export const ATTR_PARTICIPANT_ID = 'lk.participant_id';
+export const ATTR_PARTICIPANT_IDENTITY = 'lk.participant_identity';
+export const ATTR_PARTICIPANT_KIND = 'lk.participant_kind';
+
+// session start
+export const ATTR_JOB_ID = 'lk.job_id';
+export const ATTR_AGENT_NAME = 'lk.agent_name';
+export const ATTR_ROOM_NAME = 'lk.room_name';
+export const ATTR_SESSION_OPTIONS = 'lk.session_options';
+
+// assistant turn
+export const ATTR_USER_INPUT = 'lk.user_input';
+export const ATTR_INSTRUCTIONS = 'lk.instructions';
+export const ATTR_SPEECH_INTERRUPTED = 'lk.interrupted';
+
+// llm node
+export const ATTR_CHAT_CTX = 'lk.chat_ctx';
+export const ATTR_FUNCTION_TOOLS = 'lk.function_tools';
+export const ATTR_RESPONSE_TEXT = 'lk.response.text';
+export const ATTR_RESPONSE_FUNCTION_CALLS = 'lk.response.function_calls';
+
+// function tool
+export const ATTR_FUNCTION_TOOL_NAME = 'lk.function_tool.name';
+export const ATTR_FUNCTION_TOOL_ARGS = 'lk.function_tool.arguments';
+export const ATTR_FUNCTION_TOOL_IS_ERROR = 'lk.function_tool.is_error';
+export const ATTR_FUNCTION_TOOL_OUTPUT = 'lk.function_tool.output';
+
+// tts node
+export const ATTR_TTS_INPUT_TEXT = 'lk.input_text';
+export const ATTR_TTS_STREAMING = 'lk.tts.streaming';
+export const ATTR_TTS_LABEL = 'lk.tts.label';
+
+// eou detection
+export const ATTR_EOU_PROBABILITY = 'lk.eou.probability';
+export const ATTR_EOU_UNLIKELY_THRESHOLD = 'lk.eou.unlikely_threshold';
+export const ATTR_EOU_DELAY = 'lk.eou.endpointing_delay';
+export const ATTR_EOU_LANGUAGE = 'lk.eou.language';
+export const ATTR_USER_TRANSCRIPT = 'lk.user_transcript';
+export const ATTR_TRANSCRIPT_CONFIDENCE = 'lk.transcript_confidence';
+export const ATTR_TRANSCRIPTION_DELAY = 'lk.transcription_delay';
+export const ATTR_END_OF_TURN_DELAY = 'lk.end_of_turn_delay';
+
+// metrics
+export const ATTR_LLM_METRICS = 'lk.llm_metrics';
+export const ATTR_TTS_METRICS = 'lk.tts_metrics';
+export const ATTR_REALTIME_MODEL_METRICS = 'lk.realtime_model_metrics';
+
+// OpenTelemetry GenAI attributes
+// OpenTelemetry specification: https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/
+export const ATTR_GEN_AI_OPERATION_NAME = 'gen_ai.operation.name';
+export const ATTR_GEN_AI_REQUEST_MODEL = 'gen_ai.request.model';
+export const ATTR_GEN_AI_USAGE_INPUT_TOKENS = 'gen_ai.usage.input_tokens';
+export const ATTR_GEN_AI_USAGE_OUTPUT_TOKENS = 'gen_ai.usage.output_tokens';
+
+// Unofficial OpenTelemetry GenAI attributes, recognized by LangFuse
+// https://langfuse.com/integrations/native/opentelemetry#usage
+// but not yet in the official OpenTelemetry specification.
+export const ATTR_GEN_AI_USAGE_INPUT_TEXT_TOKENS = 'gen_ai.usage.input_text_tokens';
+export const ATTR_GEN_AI_USAGE_INPUT_AUDIO_TOKENS = 'gen_ai.usage.input_audio_tokens';
+export const ATTR_GEN_AI_USAGE_INPUT_CACHED_TOKENS = 'gen_ai.usage.input_cached_tokens';
+export const ATTR_GEN_AI_USAGE_OUTPUT_TEXT_TOKENS = 'gen_ai.usage.output_text_tokens';
+export const ATTR_GEN_AI_USAGE_OUTPUT_AUDIO_TOKENS = 'gen_ai.usage.output_audio_tokens';
+
+// OpenTelemetry GenAI event names (for structured logging)
+export const EVENT_GEN_AI_SYSTEM_MESSAGE = 'gen_ai.system.message';
+export const EVENT_GEN_AI_USER_MESSAGE = 'gen_ai.user.message';
+export const EVENT_GEN_AI_ASSISTANT_MESSAGE = 'gen_ai.assistant.message';
+export const EVENT_GEN_AI_TOOL_MESSAGE = 'gen_ai.tool.message';
+export const EVENT_GEN_AI_CHOICE = 'gen_ai.choice';
+
+// Exception attributes
+export const ATTR_EXCEPTION_TRACE = 'exception.stacktrace';
+export const ATTR_EXCEPTION_TYPE = 'exception.type';
+export const ATTR_EXCEPTION_MESSAGE = 'exception.message';
+
+// Platform-specific attributes
+export const ATTR_LANGFUSE_COMPLETION_START_TIME = 'langfuse.observation.completion_start_time';

package/src/telemetry/traces.ts

@@ -0,0 +1,266 @@
+// SPDX-FileCopyrightText: 2025 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import {
+  type Attributes,
+  type Context,
+  type Span,
+  type SpanOptions,
+  type Tracer,
+  type TracerProvider,
+  context as otelContext,
+  trace,
+} from '@opentelemetry/api';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { CompressionAlgorithm } from '@opentelemetry/otlp-exporter-base';
+import { Resource } from '@opentelemetry/resources';
+import type { ReadableSpan, SpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { BatchSpanProcessor, NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';
+import { AccessToken } from 'livekit-server-sdk';
+
+export interface StartSpanOptions {
+  /** Name of the span */
+  name: string;
+  /** Optional parent context to use for this span */
+  context?: Context;
+  /** Attributes to set on the span when it starts */
+  attributes?: Attributes;
+  /** Whether to end the span when the function exits (default: true) */
+  endOnExit?: boolean;
+}
+
+/**
+ * A dynamic tracer that allows the tracer provider to be changed at runtime.
+ */
+class DynamicTracer {
+  private tracerProvider: TracerProvider;
+  private tracer: Tracer;
+  private readonly instrumentingModuleName: string;
+
+  constructor(instrumentingModuleName: string) {
+    this.instrumentingModuleName = instrumentingModuleName;
+    this.tracerProvider = trace.getTracerProvider();
+    this.tracer = trace.getTracer(instrumentingModuleName);
+  }
+
+  /**
+   * Set a new tracer provider. This updates the underlying tracer instance.
+   * @param provider - The new tracer provider to use
+   */
+  setProvider(provider: TracerProvider): void {
+    this.tracerProvider = provider;
+    this.tracer = this.tracerProvider.getTracer(this.instrumentingModuleName);
+  }
+
+  /**
+   * Get the underlying OpenTelemetry tracer.
+   * Use this to access the full Tracer API when needed.
+   */
+  getTracer(): Tracer {
+    return this.tracer;
+  }
+
+  /**
+   * Start a span manually (without making it active).
+   * You must call span.end() when done.
+   *
+   * @param options - Span configuration including name
+   * @returns The created span
+   */
+  startSpan(options: StartSpanOptions): Span {
+    const ctx = options.context || otelContext.active();
+    const span = this.tracer.startSpan(
+      options.name,
+      {
+        attributes: options.attributes,
+      },
+      ctx,
+    );
+
+    return span;
+  }
+
+  /**
+   * Start a new span and make it active in the current context.
+   * The span will automatically be ended when the provided function completes (unless endOnExit=false).
+   *
+   * @param fn - The function to execute within the span context
+   * @param options - Span configuration including name
+   * @returns The result of the provided function
+   */
+  async startActiveSpan<T>(fn: (span: Span) => Promise<T>, options: StartSpanOptions): Promise<T> {
+    const ctx = options.context || otelContext.active();
+    const endOnExit = options.endOnExit === undefined ? true : options.endOnExit; // default true
+    const opts: SpanOptions = { attributes: options.attributes };
+
+    return new Promise((resolve, reject) => {
+      this.tracer.startActiveSpan(options.name, opts, ctx, async (span) => {
+        try {
+          const result = await fn(span);
+          resolve(result);
+        } catch (error) {
+          reject(error);
+        } finally {
+          if (endOnExit) {
+            span.end();
+          }
+        }
+      });
+    });
+  }
+
+  /**
+   * Synchronous version of startActiveSpan for non-async operations.
+   *
+   * @param fn - The function to execute within the span context
+   * @param options - Span configuration including name
+   * @returns The result of the provided function
+   */
+  startActiveSpanSync<T>(fn: (span: Span) => T, options: StartSpanOptions): T {
+    const ctx = options.context || otelContext.active();
+    const endOnExit = options.endOnExit === undefined ? true : options.endOnExit; // default true
+    const opts: SpanOptions = { attributes: options.attributes };
+
+    return this.tracer.startActiveSpan(options.name, opts, ctx, (span) => {
+      try {
+        return fn(span);
+      } finally {
+        if (endOnExit) {
+          span.end();
+        }
+      }
+    });
+  }
+}
+
+/**
+ * The global tracer instance used throughout the agents framework.
+ * This tracer can have its provider updated at runtime via setTracerProvider().
+ */
+export const tracer = new DynamicTracer('livekit-agents');
+
+class MetadataSpanProcessor implements SpanProcessor {
+  private metadata: Attributes;
+
+  constructor(metadata: Attributes) {
+    this.metadata = metadata;
+  }
+
+  onStart(span: Span, _parentContext: Context): void {
+    span.setAttributes(this.metadata);
+  }
+
+  onEnd(_span: ReadableSpan): void {}
+
+  shutdown(): Promise<void> {
+    return Promise.resolve();
+  }
+
+  forceFlush(): Promise<void> {
+    return Promise.resolve();
+  }
+}
+
+// TODO(brian): PR4 - Add MetadataLogProcessor for structured logging
+
+// TODO(brian): PR4 - Add ExtraDetailsProcessor for structured logging
+
+/**
+ * Set the tracer provider for the livekit-agents framework.
+ * This should be called before agent session start if using custom tracer providers.
+ *
+ * @param provider - The tracer provider to use (must be a NodeTracerProvider)
+ * @param options - Optional configuration with metadata property to inject into all spans
+ *
+ * @example
+ * ```typescript
+ * import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+ * import { setTracerProvider } from '@livekit/agents/telemetry';
+ *
+ * const provider = new NodeTracerProvider();
+ * setTracerProvider(provider, {
+ *   metadata: { room_id: 'room123', job_id: 'job456' }
+ * });
+ * ```
+ */
+export function setTracerProvider(
+  provider: NodeTracerProvider,
+  options?: { metadata?: Attributes },
+): void {
+  if (options?.metadata) {
+    provider.addSpanProcessor(new MetadataSpanProcessor(options.metadata));
+  }
+
+  tracer.setProvider(provider);
+}
+
+/**
+ * Setup OpenTelemetry tracer for LiveKit Cloud observability.
+ * This configures OTLP exporters to send traces to LiveKit Cloud.
+ *
+ * @param options - Configuration for cloud tracer with roomId, jobId, and cloudHostname properties
+ *
+ * @internal
+ */
+export async function setupCloudTracer(options: {
+  roomId: string;
+  jobId: string;
+  cloudHostname: string;
+}): Promise<void> {
+  const { roomId, jobId, cloudHostname } = options;
+
+  const apiKey = process.env.LIVEKIT_API_KEY;
+  const apiSecret = process.env.LIVEKIT_API_SECRET;
+
+  if (!apiKey || !apiSecret) {
+    throw new Error('LIVEKIT_API_KEY and LIVEKIT_API_SECRET must be set for cloud tracing');
+  }
+
+  const token = new AccessToken(apiKey, apiSecret, {
+    identity: 'livekit-agents-telemetry',
+    ttl: '6h',
+  });
+  token.addObservabilityGrant({ write: true });
+
+  try {
+    const jwt = await token.toJwt();
+
+    const headers = {
+      Authorization: `Bearer ${jwt}`,
+    };
+
+    const metadata: Attributes = {
+      room_id: roomId,
+      job_id: jobId,
+    };
+
+    const resource = new Resource({
+      [ATTR_SERVICE_NAME]: 'livekit-agents',
+      room_id: roomId,
+      job_id: jobId,
+    });
+
+    // Configure OTLP exporter to send traces to LiveKit Cloud
+    const spanExporter = new OTLPTraceExporter({
+      url: `https://${cloudHostname}/observability/traces/otlp/v0`,
+      headers,
+      compression: CompressionAlgorithm.GZIP,
+    });
+
+    const tracerProvider = new NodeTracerProvider({
+      resource,
+      spanProcessors: [new MetadataSpanProcessor(metadata), new BatchSpanProcessor(spanExporter)],
+    });
+    tracerProvider.register();
+
+    // Metadata processor is already configured in the constructor above
+    setTracerProvider(tracerProvider);
+
+    // TODO(brian): PR4 - Add logger provider setup here for structured logging
+    // Similar to Python's setup: LoggerProvider, OTLPLogExporter, BatchLogRecordProcessor
+  } catch (error) {
+    console.error('Failed to setup cloud tracer:', error);
+    throw error;
+  }
+}

package/src/telemetry/utils.ts

@@ -0,0 +1,61 @@
+// SPDX-FileCopyrightText: 2025 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import { type Span, SpanStatusCode, context as otelContext, trace } from '@opentelemetry/api';
+import type { RealtimeModelMetrics } from '../metrics/base.js';
+import * as traceTypes from './trace_types.js';
+import { tracer } from './traces.js';
+
+export function recordException(span: Span, error: Error): void {
+  span.recordException(error);
+  span.setStatus({
+    code: SpanStatusCode.ERROR,
+    message: error.message,
+  });
+
+  // Set exception attributes for better visibility
+  // (in case the exception event is not rendered by the backend)
+  span.setAttributes({
+    [traceTypes.ATTR_EXCEPTION_TYPE]: error.constructor.name,
+    [traceTypes.ATTR_EXCEPTION_MESSAGE]: error.message,
+    [traceTypes.ATTR_EXCEPTION_TRACE]: error.stack || '',
+  });
+}
+
+export function recordRealtimeMetrics(span: Span, metrics: RealtimeModelMetrics): void {
+  const attrs: Record<string, string | number> = {
+    [traceTypes.ATTR_GEN_AI_REQUEST_MODEL]: metrics.label || 'unknown',
+    [traceTypes.ATTR_REALTIME_MODEL_METRICS]: JSON.stringify(metrics),
+    [traceTypes.ATTR_GEN_AI_USAGE_INPUT_TOKENS]: metrics.inputTokens,
+    [traceTypes.ATTR_GEN_AI_USAGE_OUTPUT_TOKENS]: metrics.outputTokens,
+    [traceTypes.ATTR_GEN_AI_USAGE_INPUT_TEXT_TOKENS]: metrics.inputTokenDetails.textTokens,
+    [traceTypes.ATTR_GEN_AI_USAGE_INPUT_AUDIO_TOKENS]: metrics.inputTokenDetails.audioTokens,
+    [traceTypes.ATTR_GEN_AI_USAGE_INPUT_CACHED_TOKENS]: metrics.inputTokenDetails.cachedTokens,
+    [traceTypes.ATTR_GEN_AI_USAGE_OUTPUT_TEXT_TOKENS]: metrics.outputTokenDetails.textTokens,
+    [traceTypes.ATTR_GEN_AI_USAGE_OUTPUT_AUDIO_TOKENS]: metrics.outputTokenDetails.audioTokens,
+  };
+
+  // Add LangFuse-specific completion start time if TTFT is available
+  if (metrics.ttftMs !== undefined && metrics.ttftMs !== -1) {
+    const completionStartTime = metrics.timestamp + metrics.ttftMs;
+    // Convert to UTC ISO string for LangFuse compatibility
+    const completionStartTimeUtc = new Date(completionStartTime).toISOString();
+    attrs[traceTypes.ATTR_LANGFUSE_COMPLETION_START_TIME] = completionStartTimeUtc;
+  }
+
+  if (span.isRecording()) {
+    span.setAttributes(attrs);
+  } else {
+    const currentContext = otelContext.active();
+    const spanContext = trace.setSpan(currentContext, span);
+
+    // Create a dedicated child span for orphaned metrics
+    tracer.getTracer().startActiveSpan('realtime_metrics', {}, spanContext, (child) => {
+      try {
+        child.setAttributes(attrs);
+      } finally {
+        child.end();
+      }
+    });
+  }
+}

package/src/tts/tts.ts

@@ -94,6 +94,10 @@ export abstract class TTS extends (EventEmitter as new () => TypedEmitter<TTSCal
    * Returns a {@link SynthesizeStream} that can be used to push text and receive audio data
    */
   abstract stream(): SynthesizeStream;
+
+  async close(): Promise<void> {
+    return;
+  }
 }
 
 /**
@@ -157,8 +161,10 @@ export abstract class SynthesizeStream
   }
 
   private async mainTask() {
+    // TODO(brian): PR3 - Add span wrapping: tracer.startActiveSpan('tts_request', ..., { endOnExit: false })
     for (let i = 0; i < this._connOptions.maxRetry + 1; i++) {
       try {
+        // TODO(brian): PR3 - Add span for retry attempts: tracer.startActiveSpan('tts_request_run', ...)
         return await this.run();
       } catch (error) {
         if (error instanceof APIError) {
@@ -385,8 +391,10 @@ export abstract class ChunkedStream implements AsyncIterableIterator<Synthesized
   }
 
   private async mainTask() {
+    // TODO(brian): PR3 - Add span wrapping: tracer.startActiveSpan('tts_request', ..., { endOnExit: false })
     for (let i = 0; i < this._connOptions.maxRetry + 1; i++) {
       try {
+        // TODO(brian): PR3 - Add span for retry attempts: tracer.startActiveSpan('tts_request_run', ...)
         return await this.run();
       } catch (error) {
         if (error instanceof APIError) {

package/src/vad.ts

@@ -80,6 +80,10 @@ export abstract class VAD extends (EventEmitter as new () => TypedEmitter<VADCal
    * Returns a {@link VADStream} that can be used to push audio frames and receive VAD events.
    */
   abstract stream(): VADStream;
+
+  async close(): Promise<void> {
+    return;
+  }
 }
 
 export abstract class VADStream implements AsyncIterableIterator<VADEvent> {

package/src/voice/agent.ts

@@ -59,6 +59,7 @@ export interface ModelSettings {
 }
 
 export interface AgentOptions<UserData> {
+  id?: string;
   instructions: string;
   chatCtx?: ChatContext;
   tools?: ToolContext<UserData>;
@@ -72,6 +73,7 @@ export interface AgentOptions<UserData> {
 }
 
 export class Agent<UserData = any> {
+  private _id: string;
   private turnDetection?: TurnDetectionMode;
   private _stt?: STT;
   private _vad?: VAD;
@@ -91,6 +93,7 @@ export class Agent<UserData = any> {
   _tools?: ToolContext<UserData>;
 
   constructor({
+    id,
     instructions,
     chatCtx,
     tools,
@@ -100,6 +103,21 @@ export class Agent<UserData = any> {
     llm,
     tts,
   }: AgentOptions<UserData>) {
+    if (id) {
+      this._id = id;
+    } else {
+      // Convert class name to snake_case
+      const className = this.constructor.name;
+      if (className === 'Agent') {
+        this._id = 'default_agent';
+      } else {
+        this._id = className
+          .replace(/([A-Z])/g, '_$1')
+          .toLowerCase()
+          .replace(/^_/, '');
+      }
+    }
+
     this._instructions = instructions;
     this._tools = { ...tools };
     this._chatCtx = chatCtx
@@ -152,6 +170,10 @@ export class Agent<UserData = any> {
     return new ReadonlyChatContext(this._chatCtx.items);
   }
 
+  get id(): string {
+    return this._id;
+  }
+
   get instructions(): string {
     return this._instructions;
   }

package/src/voice/agent_activity.ts

@@ -202,6 +202,8 @@ export class AgentActivity implements RecognitionHooks {
   }
 
   async start(): Promise<void> {
+    // TODO(brian): PR3 - Add span: startSpan = tracer.startSpan('start_agent_activity', { attributes: { 'lk.agent_label': this.agent.label } })
+    // TODO(brian): PR3 - Wrap prewarm calls with trace.useSpan(startSpan, endOnExit: false)
     const unlock = await this.lock.lock();
     try {
       this.agent._agentActivity = this;
@@ -289,6 +291,7 @@ export class AgentActivity implements RecognitionHooks {
       this.started = true;
 
       this._mainTask = Task.from(({ signal }) => this.mainTask(signal));
+      // TODO(brian): PR3 - Wrap onEnter with tracer.startActiveSpan('on_enter', { attributes: { 'lk.agent_label': this.agent.label }, context: startSpan context })
       this.createSpeechTask({
         task: Task.from(() => this.agent.onEnter()),
         name: 'AgentActivity_onEnter',
@@ -1251,6 +1254,7 @@ export class AgentActivity implements RecognitionHooks {
     }
   }
 
+  // TODO(brian): PR3 - Wrap entire pipelineReplyTask() method with tracer.startActiveSpan('agent_turn')
   private async pipelineReplyTask(
     speechHandle: SpeechHandle,
     chatCtx: ChatContext,
@@ -2092,12 +2096,14 @@ export class AgentActivity implements RecognitionHooks {
     this.wakeupMainTask();
   }
 
+  // TODO(brian): PR3 - Wrap entire drain() method with tracer.startActiveSpan('drain_agent_activity', { attributes: { 'lk.agent_label': this.agent.label } })
   async drain(): Promise<void> {
     const unlock = await this.lock.lock();
     try {
       if (this._draining) return;
 
       this.cancelPreemptiveGeneration();
+      // TODO(brian): PR3 - Wrap onExit with tracer.startActiveSpan('on_exit', { attributes: { 'lk.agent_label': this.agent.label } })
       this.createSpeechTask({
         task: Task.from(() => this.agent.onExit()),
         name: 'AgentActivity_onExit',
@@ -2135,12 +2141,15 @@ export class AgentActivity implements RecognitionHooks {
       }
       if (this.stt instanceof STT) {
         this.stt.off('metrics_collected', this.onMetricsCollected);
+        await this.stt.close();
       }
       if (this.tts instanceof TTS) {
         this.tts.off('metrics_collected', this.onMetricsCollected);
+        await this.tts.close();
       }
       if (this.vad instanceof VAD) {
         this.vad.off('metrics_collected', this.onMetricsCollected);
+        await this.vad.close();
       }
 
       this.detachAudioInput();