@livekit/agents 1.0.18 → 1.0.19

package/dist/telemetry/traces.cjs.map

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

package/dist/telemetry/traces.d.cts

@@ -0,0 +1,97 @@
+import { type Attributes, type Context, type Span, type Tracer, type TracerProvider } from '@opentelemetry/api';
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+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.
+ */
+declare class DynamicTracer {
+    private tracerProvider;
+    private tracer;
+    private readonly instrumentingModuleName;
+    constructor(instrumentingModuleName: string);
+    /**
+     * Set a new tracer provider. This updates the underlying tracer instance.
+     * @param provider - The new tracer provider to use
+     */
+    setProvider(provider: TracerProvider): void;
+    /**
+     * Get the underlying OpenTelemetry tracer.
+     * Use this to access the full Tracer API when needed.
+     */
+    getTracer(): 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;
+    /**
+     * 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
+     */
+    startActiveSpan<T>(fn: (span: Span) => Promise<T>, options: StartSpanOptions): Promise<T>;
+    /**
+     * 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;
+}
+/**
+ * The global tracer instance used throughout the agents framework.
+ * This tracer can have its provider updated at runtime via setTracerProvider().
+ */
+export declare const tracer: DynamicTracer;
+/**
+ * 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 declare function setTracerProvider(provider: NodeTracerProvider, options?: {
+    metadata?: Attributes;
+}): void;
+/**
+ * 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 declare function setupCloudTracer(options: {
+    roomId: string;
+    jobId: string;
+    cloudHostname: string;
+}): Promise<void>;
+export {};
+//# sourceMappingURL=traces.d.ts.map

package/dist/telemetry/traces.d.ts

@@ -0,0 +1,97 @@
+import { type Attributes, type Context, type Span, type Tracer, type TracerProvider } from '@opentelemetry/api';
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+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.
+ */
+declare class DynamicTracer {
+    private tracerProvider;
+    private tracer;
+    private readonly instrumentingModuleName;
+    constructor(instrumentingModuleName: string);
+    /**
+     * Set a new tracer provider. This updates the underlying tracer instance.
+     * @param provider - The new tracer provider to use
+     */
+    setProvider(provider: TracerProvider): void;
+    /**
+     * Get the underlying OpenTelemetry tracer.
+     * Use this to access the full Tracer API when needed.
+     */
+    getTracer(): 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;
+    /**
+     * 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
+     */
+    startActiveSpan<T>(fn: (span: Span) => Promise<T>, options: StartSpanOptions): Promise<T>;
+    /**
+     * 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;
+}
+/**
+ * The global tracer instance used throughout the agents framework.
+ * This tracer can have its provider updated at runtime via setTracerProvider().
+ */
+export declare const tracer: DynamicTracer;
+/**
+ * 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 declare function setTracerProvider(provider: NodeTracerProvider, options?: {
+    metadata?: Attributes;
+}): void;
+/**
+ * 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 declare function setupCloudTracer(options: {
+    roomId: string;
+    jobId: string;
+    cloudHostname: string;
+}): Promise<void>;
+export {};
+//# sourceMappingURL=traces.d.ts.map

package/dist/telemetry/traces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traces.d.ts","sourceRoot":"","sources":["../../src/telemetry/traces.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,UAAU,EACf,KAAK,OAAO,EACZ,KAAK,IAAI,EAET,KAAK,MAAM,EACX,KAAK,cAAc,EAGpB,MAAM,oBAAoB,CAAC;AAK5B,OAAO,EAAsB,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAIvF,MAAM,WAAW,gBAAgB;IAC/B,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,mDAAmD;IACnD,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,sEAAsE;IACtE,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;GAEG;AACH,cAAM,aAAa;IACjB,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAS;gBAErC,uBAAuB,EAAE,MAAM;IAM3C;;;OAGG;IACH,WAAW,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI;IAK3C;;;OAGG;IACH,SAAS,IAAI,MAAM;IAInB;;;;;;OAMG;IACH,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI;IAa1C;;;;;;;OAOG;IACG,eAAe,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,CAAC,CAAC;IAqB/F;;;;;;OAMG;IACH,mBAAmB,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,EAAE,OAAO,EAAE,gBAAgB,GAAG,CAAC;CAe5E;AAED;;;GAGG;AACH,eAAO,MAAM,MAAM,eAAsC,CAAC;AA4B1D;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,UAAU,CAAA;CAAE,GAClC,IAAI,CAMN;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwDhB"}

package/dist/telemetry/traces.js

@@ -0,0 +1,173 @@
+import {
+  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 { BatchSpanProcessor, NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
+import { AccessToken } from "livekit-server-sdk";
+class DynamicTracer {
+  tracerProvider;
+  tracer;
+  instrumentingModuleName;
+  constructor(instrumentingModuleName) {
+    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) {
+    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() {
+    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) {
+    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(fn, options) {
+    const ctx = options.context || otelContext.active();
+    const endOnExit = options.endOnExit === void 0 ? true : options.endOnExit;
+    const opts = { 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(fn, options) {
+    const ctx = options.context || otelContext.active();
+    const endOnExit = options.endOnExit === void 0 ? true : options.endOnExit;
+    const opts = { attributes: options.attributes };
+    return this.tracer.startActiveSpan(options.name, opts, ctx, (span) => {
+      try {
+        return fn(span);
+      } finally {
+        if (endOnExit) {
+          span.end();
+        }
+      }
+    });
+  }
+}
+const tracer = new DynamicTracer("livekit-agents");
+class MetadataSpanProcessor {
+  metadata;
+  constructor(metadata) {
+    this.metadata = metadata;
+  }
+  onStart(span, _parentContext) {
+    span.setAttributes(this.metadata);
+  }
+  onEnd(_span) {
+  }
+  shutdown() {
+    return Promise.resolve();
+  }
+  forceFlush() {
+    return Promise.resolve();
+  }
+}
+function setTracerProvider(provider, options) {
+  if (options == null ? void 0 : options.metadata) {
+    provider.addSpanProcessor(new MetadataSpanProcessor(options.metadata));
+  }
+  tracer.setProvider(provider);
+}
+async function setupCloudTracer(options) {
+  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 = {
+      room_id: roomId,
+      job_id: jobId
+    };
+    const resource = new Resource({
+      [ATTR_SERVICE_NAME]: "livekit-agents",
+      room_id: roomId,
+      job_id: jobId
+    });
+    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();
+    setTracerProvider(tracerProvider);
+  } catch (error) {
+    console.error("Failed to setup cloud tracer:", error);
+    throw error;
+  }
+}
+export {
+  setTracerProvider,
+  setupCloudTracer,
+  tracer
+};
+//# sourceMappingURL=traces.js.map

package/dist/telemetry/traces.js.map

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

package/dist/telemetry/utils.cjs

@@ -0,0 +1,86 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var utils_exports = {};
+__export(utils_exports, {
+  recordException: () => recordException,
+  recordRealtimeMetrics: () => recordRealtimeMetrics
+});
+module.exports = __toCommonJS(utils_exports);
+var import_api = require("@opentelemetry/api");
+var traceTypes = __toESM(require("./trace_types.cjs"), 1);
+var import_traces = require("./traces.cjs");
+function recordException(span, error) {
+  span.recordException(error);
+  span.setStatus({
+    code: import_api.SpanStatusCode.ERROR,
+    message: error.message
+  });
+  span.setAttributes({
+    [traceTypes.ATTR_EXCEPTION_TYPE]: error.constructor.name,
+    [traceTypes.ATTR_EXCEPTION_MESSAGE]: error.message,
+    [traceTypes.ATTR_EXCEPTION_TRACE]: error.stack || ""
+  });
+}
+function recordRealtimeMetrics(span, metrics) {
+  const attrs = {
+    [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
+  };
+  if (metrics.ttftMs !== void 0 && metrics.ttftMs !== -1) {
+    const completionStartTime = metrics.timestamp + metrics.ttftMs;
+    const completionStartTimeUtc = new Date(completionStartTime).toISOString();
+    attrs[traceTypes.ATTR_LANGFUSE_COMPLETION_START_TIME] = completionStartTimeUtc;
+  }
+  if (span.isRecording()) {
+    span.setAttributes(attrs);
+  } else {
+    const currentContext = import_api.context.active();
+    const spanContext = import_api.trace.setSpan(currentContext, span);
+    import_traces.tracer.getTracer().startActiveSpan("realtime_metrics", {}, spanContext, (child) => {
+      try {
+        child.setAttributes(attrs);
+      } finally {
+        child.end();
+      }
+    });
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  recordException,
+  recordRealtimeMetrics
+});
+//# sourceMappingURL=utils.cjs.map

package/dist/telemetry/utils.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/telemetry/utils.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2025 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport { type Span, SpanStatusCode, context as otelContext, trace } from '@opentelemetry/api';\nimport type { RealtimeModelMetrics } from '../metrics/base.js';\nimport * as traceTypes from './trace_types.js';\nimport { tracer } from './traces.js';\n\nexport function recordException(span: Span, error: Error): void {\n  span.recordException(error);\n  span.setStatus({\n    code: SpanStatusCode.ERROR,\n    message: error.message,\n  });\n\n  // Set exception attributes for better visibility\n  // (in case the exception event is not rendered by the backend)\n  span.setAttributes({\n    [traceTypes.ATTR_EXCEPTION_TYPE]: error.constructor.name,\n    [traceTypes.ATTR_EXCEPTION_MESSAGE]: error.message,\n    [traceTypes.ATTR_EXCEPTION_TRACE]: error.stack || '',\n  });\n}\n\nexport function recordRealtimeMetrics(span: Span, metrics: RealtimeModelMetrics): void {\n  const attrs: Record<string, string | number> = {\n    [traceTypes.ATTR_GEN_AI_REQUEST_MODEL]: metrics.label || 'unknown',\n    [traceTypes.ATTR_REALTIME_MODEL_METRICS]: JSON.stringify(metrics),\n    [traceTypes.ATTR_GEN_AI_USAGE_INPUT_TOKENS]: metrics.inputTokens,\n    [traceTypes.ATTR_GEN_AI_USAGE_OUTPUT_TOKENS]: metrics.outputTokens,\n    [traceTypes.ATTR_GEN_AI_USAGE_INPUT_TEXT_TOKENS]: metrics.inputTokenDetails.textTokens,\n    [traceTypes.ATTR_GEN_AI_USAGE_INPUT_AUDIO_TOKENS]: metrics.inputTokenDetails.audioTokens,\n    [traceTypes.ATTR_GEN_AI_USAGE_INPUT_CACHED_TOKENS]: metrics.inputTokenDetails.cachedTokens,\n    [traceTypes.ATTR_GEN_AI_USAGE_OUTPUT_TEXT_TOKENS]: metrics.outputTokenDetails.textTokens,\n    [traceTypes.ATTR_GEN_AI_USAGE_OUTPUT_AUDIO_TOKENS]: metrics.outputTokenDetails.audioTokens,\n  };\n\n  // Add LangFuse-specific completion start time if TTFT is available\n  if (metrics.ttftMs !== undefined && metrics.ttftMs !== -1) {\n    const completionStartTime = metrics.timestamp + metrics.ttftMs;\n    // Convert to UTC ISO string for LangFuse compatibility\n    const completionStartTimeUtc = new Date(completionStartTime).toISOString();\n    attrs[traceTypes.ATTR_LANGFUSE_COMPLETION_START_TIME] = completionStartTimeUtc;\n  }\n\n  if (span.isRecording()) {\n    span.setAttributes(attrs);\n  } else {\n    const currentContext = otelContext.active();\n    const spanContext = trace.setSpan(currentContext, span);\n\n    // Create a dedicated child span for orphaned metrics\n    tracer.getTracer().startActiveSpan('realtime_metrics', {}, spanContext, (child) => {\n      try {\n        child.setAttributes(attrs);\n      } finally {\n        child.end();\n      }\n    });\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAGA,iBAAyE;AAEzE,iBAA4B;AAC5B,oBAAuB;AAEhB,SAAS,gBAAgB,MAAY,OAAoB;AAC9D,OAAK,gBAAgB,KAAK;AAC1B,OAAK,UAAU;AAAA,IACb,MAAM,0BAAe;AAAA,IACrB,SAAS,MAAM;AAAA,EACjB,CAAC;AAID,OAAK,cAAc;AAAA,IACjB,CAAC,WAAW,mBAAmB,GAAG,MAAM,YAAY;AAAA,IACpD,CAAC,WAAW,sBAAsB,GAAG,MAAM;AAAA,IAC3C,CAAC,WAAW,oBAAoB,GAAG,MAAM,SAAS;AAAA,EACpD,CAAC;AACH;AAEO,SAAS,sBAAsB,MAAY,SAAqC;AACrF,QAAM,QAAyC;AAAA,IAC7C,CAAC,WAAW,yBAAyB,GAAG,QAAQ,SAAS;AAAA,IACzD,CAAC,WAAW,2BAA2B,GAAG,KAAK,UAAU,OAAO;AAAA,IAChE,CAAC,WAAW,8BAA8B,GAAG,QAAQ;AAAA,IACrD,CAAC,WAAW,+BAA+B,GAAG,QAAQ;AAAA,IACtD,CAAC,WAAW,mCAAmC,GAAG,QAAQ,kBAAkB;AAAA,IAC5E,CAAC,WAAW,oCAAoC,GAAG,QAAQ,kBAAkB;AAAA,IAC7E,CAAC,WAAW,qCAAqC,GAAG,QAAQ,kBAAkB;AAAA,IAC9E,CAAC,WAAW,oCAAoC,GAAG,QAAQ,mBAAmB;AAAA,IAC9E,CAAC,WAAW,qCAAqC,GAAG,QAAQ,mBAAmB;AAAA,EACjF;AAGA,MAAI,QAAQ,WAAW,UAAa,QAAQ,WAAW,IAAI;AACzD,UAAM,sBAAsB,QAAQ,YAAY,QAAQ;AAExD,UAAM,yBAAyB,IAAI,KAAK,mBAAmB,EAAE,YAAY;AACzE,UAAM,WAAW,mCAAmC,IAAI;AAAA,EAC1D;AAEA,MAAI,KAAK,YAAY,GAAG;AACtB,SAAK,cAAc,KAAK;AAAA,EAC1B,OAAO;AACL,UAAM,iBAAiB,WAAAA,QAAY,OAAO;AAC1C,UAAM,cAAc,iBAAM,QAAQ,gBAAgB,IAAI;AAGtD,yBAAO,UAAU,EAAE,gBAAgB,oBAAoB,CAAC,GAAG,aAAa,CAAC,UAAU;AACjF,UAAI;AACF,cAAM,cAAc,KAAK;AAAA,MAC3B,UAAE;AACA,cAAM,IAAI;AAAA,MACZ;AAAA,IACF,CAAC;AAAA,EACH;AACF;","names":["otelContext"]}

package/dist/telemetry/utils.d.cts

@@ -0,0 +1,5 @@
+import { type Span } from '@opentelemetry/api';
+import type { RealtimeModelMetrics } from '../metrics/base.js';
+export declare function recordException(span: Span, error: Error): void;
+export declare function recordRealtimeMetrics(span: Span, metrics: RealtimeModelMetrics): void;
+//# sourceMappingURL=utils.d.ts.map

package/dist/telemetry/utils.d.ts

@@ -0,0 +1,5 @@
+import { type Span } from '@opentelemetry/api';
+import type { RealtimeModelMetrics } from '../metrics/base.js';
+export declare function recordException(span: Span, error: Error): void;
+export declare function recordRealtimeMetrics(span: Span, metrics: RealtimeModelMetrics): void;
+//# sourceMappingURL=utils.d.ts.map

package/dist/telemetry/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/telemetry/utils.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,IAAI,EAAiD,MAAM,oBAAoB,CAAC;AAC9F,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAI/D,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAc9D;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,oBAAoB,GAAG,IAAI,CAoCrF"}

package/dist/telemetry/utils.js

@@ -0,0 +1,51 @@
+import { SpanStatusCode, context as otelContext, trace } from "@opentelemetry/api";
+import * as traceTypes from "./trace_types.js";
+import { tracer } from "./traces.js";
+function recordException(span, error) {
+  span.recordException(error);
+  span.setStatus({
+    code: SpanStatusCode.ERROR,
+    message: error.message
+  });
+  span.setAttributes({
+    [traceTypes.ATTR_EXCEPTION_TYPE]: error.constructor.name,
+    [traceTypes.ATTR_EXCEPTION_MESSAGE]: error.message,
+    [traceTypes.ATTR_EXCEPTION_TRACE]: error.stack || ""
+  });
+}
+function recordRealtimeMetrics(span, metrics) {
+  const attrs = {
+    [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
+  };
+  if (metrics.ttftMs !== void 0 && metrics.ttftMs !== -1) {
+    const completionStartTime = metrics.timestamp + metrics.ttftMs;
+    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);
+    tracer.getTracer().startActiveSpan("realtime_metrics", {}, spanContext, (child) => {
+      try {
+        child.setAttributes(attrs);
+      } finally {
+        child.end();
+      }
+    });
+  }
+}
+export {
+  recordException,
+  recordRealtimeMetrics
+};
+//# sourceMappingURL=utils.js.map

package/dist/telemetry/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/telemetry/utils.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2025 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport { type Span, SpanStatusCode, context as otelContext, trace } from '@opentelemetry/api';\nimport type { RealtimeModelMetrics } from '../metrics/base.js';\nimport * as traceTypes from './trace_types.js';\nimport { tracer } from './traces.js';\n\nexport function recordException(span: Span, error: Error): void {\n  span.recordException(error);\n  span.setStatus({\n    code: SpanStatusCode.ERROR,\n    message: error.message,\n  });\n\n  // Set exception attributes for better visibility\n  // (in case the exception event is not rendered by the backend)\n  span.setAttributes({\n    [traceTypes.ATTR_EXCEPTION_TYPE]: error.constructor.name,\n    [traceTypes.ATTR_EXCEPTION_MESSAGE]: error.message,\n    [traceTypes.ATTR_EXCEPTION_TRACE]: error.stack || '',\n  });\n}\n\nexport function recordRealtimeMetrics(span: Span, metrics: RealtimeModelMetrics): void {\n  const attrs: Record<string, string | number> = {\n    [traceTypes.ATTR_GEN_AI_REQUEST_MODEL]: metrics.label || 'unknown',\n    [traceTypes.ATTR_REALTIME_MODEL_METRICS]: JSON.stringify(metrics),\n    [traceTypes.ATTR_GEN_AI_USAGE_INPUT_TOKENS]: metrics.inputTokens,\n    [traceTypes.ATTR_GEN_AI_USAGE_OUTPUT_TOKENS]: metrics.outputTokens,\n    [traceTypes.ATTR_GEN_AI_USAGE_INPUT_TEXT_TOKENS]: metrics.inputTokenDetails.textTokens,\n    [traceTypes.ATTR_GEN_AI_USAGE_INPUT_AUDIO_TOKENS]: metrics.inputTokenDetails.audioTokens,\n    [traceTypes.ATTR_GEN_AI_USAGE_INPUT_CACHED_TOKENS]: metrics.inputTokenDetails.cachedTokens,\n    [traceTypes.ATTR_GEN_AI_USAGE_OUTPUT_TEXT_TOKENS]: metrics.outputTokenDetails.textTokens,\n    [traceTypes.ATTR_GEN_AI_USAGE_OUTPUT_AUDIO_TOKENS]: metrics.outputTokenDetails.audioTokens,\n  };\n\n  // Add LangFuse-specific completion start time if TTFT is available\n  if (metrics.ttftMs !== undefined && metrics.ttftMs !== -1) {\n    const completionStartTime = metrics.timestamp + metrics.ttftMs;\n    // Convert to UTC ISO string for LangFuse compatibility\n    const completionStartTimeUtc = new Date(completionStartTime).toISOString();\n    attrs[traceTypes.ATTR_LANGFUSE_COMPLETION_START_TIME] = completionStartTimeUtc;\n  }\n\n  if (span.isRecording()) {\n    span.setAttributes(attrs);\n  } else {\n    const currentContext = otelContext.active();\n    const spanContext = trace.setSpan(currentContext, span);\n\n    // Create a dedicated child span for orphaned metrics\n    tracer.getTracer().startActiveSpan('realtime_metrics', {}, spanContext, (child) => {\n      try {\n        child.setAttributes(attrs);\n      } finally {\n        child.end();\n      }\n    });\n  }\n}\n"],"mappings":"AAGA,SAAoB,gBAAgB,WAAW,aAAa,aAAa;AAEzE,YAAY,gBAAgB;AAC5B,SAAS,cAAc;AAEhB,SAAS,gBAAgB,MAAY,OAAoB;AAC9D,OAAK,gBAAgB,KAAK;AAC1B,OAAK,UAAU;AAAA,IACb,MAAM,eAAe;AAAA,IACrB,SAAS,MAAM;AAAA,EACjB,CAAC;AAID,OAAK,cAAc;AAAA,IACjB,CAAC,WAAW,mBAAmB,GAAG,MAAM,YAAY;AAAA,IACpD,CAAC,WAAW,sBAAsB,GAAG,MAAM;AAAA,IAC3C,CAAC,WAAW,oBAAoB,GAAG,MAAM,SAAS;AAAA,EACpD,CAAC;AACH;AAEO,SAAS,sBAAsB,MAAY,SAAqC;AACrF,QAAM,QAAyC;AAAA,IAC7C,CAAC,WAAW,yBAAyB,GAAG,QAAQ,SAAS;AAAA,IACzD,CAAC,WAAW,2BAA2B,GAAG,KAAK,UAAU,OAAO;AAAA,IAChE,CAAC,WAAW,8BAA8B,GAAG,QAAQ;AAAA,IACrD,CAAC,WAAW,+BAA+B,GAAG,QAAQ;AAAA,IACtD,CAAC,WAAW,mCAAmC,GAAG,QAAQ,kBAAkB;AAAA,IAC5E,CAAC,WAAW,oCAAoC,GAAG,QAAQ,kBAAkB;AAAA,IAC7E,CAAC,WAAW,qCAAqC,GAAG,QAAQ,kBAAkB;AAAA,IAC9E,CAAC,WAAW,oCAAoC,GAAG,QAAQ,mBAAmB;AAAA,IAC9E,CAAC,WAAW,qCAAqC,GAAG,QAAQ,mBAAmB;AAAA,EACjF;AAGA,MAAI,QAAQ,WAAW,UAAa,QAAQ,WAAW,IAAI;AACzD,UAAM,sBAAsB,QAAQ,YAAY,QAAQ;AAExD,UAAM,yBAAyB,IAAI,KAAK,mBAAmB,EAAE,YAAY;AACzE,UAAM,WAAW,mCAAmC,IAAI;AAAA,EAC1D;AAEA,MAAI,KAAK,YAAY,GAAG;AACtB,SAAK,cAAc,KAAK;AAAA,EAC1B,OAAO;AACL,UAAM,iBAAiB,YAAY,OAAO;AAC1C,UAAM,cAAc,MAAM,QAAQ,gBAAgB,IAAI;AAGtD,WAAO,UAAU,EAAE,gBAAgB,oBAAoB,CAAC,GAAG,aAAa,CAAC,UAAU;AACjF,UAAI;AACF,cAAM,cAAc,KAAK;AAAA,MAC3B,UAAE;AACA,cAAM,IAAI;AAAA,MACZ;AAAA,IACF,CAAC;AAAA,EACH;AACF;","names":[]}