@livekit/agents 0.0.0-20260120144724

package/src/telemetry/otel_http_exporter.ts

@@ -0,0 +1,195 @@
+// SPDX-FileCopyrightText: 2025 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * OTLP HTTP JSON Log Exporter for LiveKit Cloud
+ *
+ * This module provides a custom OTLP log exporter that uses HTTP with JSON format
+ * instead of the default protobuf format.
+ */
+import { SeverityNumber } from '@opentelemetry/api-logs';
+import { AccessToken } from 'livekit-server-sdk';
+
+export interface SimpleLogRecord {
+  /** Log message body */
+  body: string;
+  /** Timestamp in milliseconds since epoch */
+  timestampMs: number;
+  /** Log attributes */
+  attributes: Record<string, unknown>;
+  /** Severity number (default: UNSPECIFIED) */
+  severityNumber?: SeverityNumber;
+  /** Severity text (default: 'unspecified') */
+  severityText?: string;
+}
+
+export interface SimpleOTLPHttpLogExporterConfig {
+  /** LiveKit Cloud hostname */
+  cloudHostname: string;
+  /** Resource attributes (e.g., room_id, job_id) */
+  resourceAttributes: Record<string, string>;
+  /** Scope name for the logger */
+  scopeName: string;
+  /** Scope attributes */
+  scopeAttributes?: Record<string, string>;
+}
+
+/**
+ * Simple OTLP HTTP Log Exporter for direct log export
+ *
+ * This is a simplified exporter that doesn't require the full SDK infrastructure.
+ * Use this when you need to send logs directly without LoggerProvider.
+ *
+ * @example
+ * ```typescript
+ * const exporter = new SimpleOTLPHttpLogExporter({
+ *   cloudHostname: 'cloud.livekit.io',
+ *   resourceAttributes: { room_id: 'xxx', job_id: 'yyy' },
+ *   scopeName: 'chat_history',
+ * });
+ *
+ * await exporter.export([
+ *   { body: 'Hello', timestampMs: Date.now(), attributes: { test: true } },
+ * ]);
+ * ```
+ */
+export class SimpleOTLPHttpLogExporter {
+  private readonly config: SimpleOTLPHttpLogExporterConfig;
+  private jwt: string | null = null;
+
+  constructor(config: SimpleOTLPHttpLogExporterConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Export simple log records
+   */
+  async export(records: SimpleLogRecord[]): Promise<void> {
+    if (records.length === 0) return;
+
+    await this.ensureJwt();
+
+    const endpoint = `https://${this.config.cloudHostname}/observability/logs/otlp/v0`;
+    const payload = this.buildPayload(records);
+
+    const response = await fetch(endpoint, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${this.jwt}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(payload),
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(
+        `OTLP log export failed: ${response.status} ${response.statusText} - ${text}`,
+      );
+    }
+  }
+
+  private async ensureJwt(): Promise<void> {
+    if (this.jwt) return;
+
+    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');
+    }
+
+    const token = new AccessToken(apiKey, apiSecret, { ttl: '6h' });
+    token.addObservabilityGrant({ write: true });
+    this.jwt = await token.toJwt();
+  }
+
+  private buildPayload(records: SimpleLogRecord[]): object {
+    const resourceAttrs = Object.entries(this.config.resourceAttributes).map(([key, value]) => ({
+      key,
+      value: { stringValue: value },
+    }));
+
+    if (!this.config.resourceAttributes['service.name']) {
+      resourceAttrs.push({ key: 'service.name', value: { stringValue: 'livekit-agents' } });
+    }
+
+    const scopeAttrs = this.config.scopeAttributes
+      ? Object.entries(this.config.scopeAttributes).map(([key, value]) => ({
+          key,
+          value: { stringValue: value },
+        }))
+      : [];
+
+    const logRecords = records.map((record) => {
+      // Ensure timestampMs is a valid number, fallback to current time if NaN/undefined
+      const timestampMs = Number.isFinite(record.timestampMs) ? record.timestampMs : Date.now();
+      return {
+        timeUnixNano: String(BigInt(Math.floor(timestampMs * 1_000_000))),
+        observedTimeUnixNano: String(BigInt(Date.now()) * BigInt(1_000_000)),
+        severityNumber: record.severityNumber ?? SeverityNumber.UNSPECIFIED,
+        severityText: record.severityText ?? 'unspecified',
+        body: { stringValue: record.body },
+        attributes: this.convertAttributes(record.attributes),
+        traceId: '',
+        spanId: '',
+      };
+    });
+
+    return {
+      resourceLogs: [
+        {
+          resource: { attributes: resourceAttrs },
+          scopeLogs: [
+            {
+              scope: {
+                name: this.config.scopeName,
+                attributes: scopeAttrs,
+              },
+              logRecords,
+            },
+          ],
+        },
+      ],
+    };
+  }
+
+  private convertAttributes(
+    attrs: Record<string, unknown>,
+  ): Array<{ key: string; value: unknown }> {
+    return Object.entries(attrs).map(([key, value]) => ({
+      key,
+      value: this.convertValue(value),
+    }));
+  }
+
+  private convertValue(value: unknown): unknown {
+    if (value === null || value === undefined) {
+      return { stringValue: '' };
+    }
+    if (typeof value === 'string') {
+      return { stringValue: value };
+    }
+    if (typeof value === 'number') {
+      return Number.isInteger(value) ? { intValue: String(value) } : { doubleValue: value };
+    }
+    if (typeof value === 'boolean') {
+      return { boolValue: value };
+    }
+    if (Array.isArray(value)) {
+      return { arrayValue: { values: value.map((v) => this.convertValue(v)) } };
+    }
+    if (typeof value === 'object') {
+      return {
+        kvlistValue: {
+          values: Object.entries(value as Record<string, unknown>).map(([k, v]) => ({
+            key: k,
+            value: this.convertValue(v),
+          })),
+        },
+      };
+    }
+    return { stringValue: String(value) };
+  }
+}

package/src/telemetry/pino_otel_transport.ts

@@ -0,0 +1,265 @@
+// SPDX-FileCopyrightText: 2025 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Custom Pino OTEL Transport
+ *
+ * Standalone exporter for Pino logs to LiveKit Cloud.
+ * Uses raw HTTP JSON format, bypassing the OTEL SDK.
+ */
+import { SeverityNumber } from '@opentelemetry/api-logs';
+import { AccessToken } from 'livekit-server-sdk';
+
+export interface PinoLogObject {
+  level: number;
+  time: number;
+  msg: string;
+  pid?: number;
+  hostname?: string;
+  [key: string]: unknown;
+}
+
+export interface PinoCloudExporterConfig {
+  cloudHostname: string;
+  roomId: string;
+  jobId: string;
+  loggerName?: string;
+  batchSize?: number;
+  flushIntervalMs?: number;
+}
+
+function mapPinoLevelToSeverity(pinoLevel: number): {
+  severityNumber: SeverityNumber;
+  severityText: string;
+} {
+  if (pinoLevel <= 10) {
+    return { severityNumber: SeverityNumber.TRACE, severityText: 'TRACE' };
+  } else if (pinoLevel <= 20) {
+    return { severityNumber: SeverityNumber.DEBUG, severityText: 'DEBUG' };
+  } else if (pinoLevel <= 30) {
+    return { severityNumber: SeverityNumber.INFO, severityText: 'INFO' };
+  } else if (pinoLevel <= 40) {
+    return { severityNumber: SeverityNumber.WARN, severityText: 'WARN' };
+  } else if (pinoLevel <= 50) {
+    return { severityNumber: SeverityNumber.ERROR, severityText: 'ERROR' };
+  } else {
+    return { severityNumber: SeverityNumber.FATAL, severityText: 'FATAL' };
+  }
+}
+
+const EXCLUDE_FIELDS = new Set(['level', 'time', 'msg', 'pid', 'hostname', 'v']);
+
+function convertValue(value: unknown): unknown {
+  if (value === null || value === undefined) {
+    return { stringValue: '' };
+  }
+  if (typeof value === 'string') {
+    return { stringValue: value };
+  }
+  if (typeof value === 'number') {
+    return Number.isInteger(value) ? { intValue: String(value) } : { doubleValue: value };
+  }
+  if (typeof value === 'boolean') {
+    return { boolValue: value };
+  }
+  if (typeof value === 'object') {
+    return { stringValue: JSON.stringify(value) };
+  }
+  return { stringValue: String(value) };
+}
+
+/**
+ * Standalone Pino log exporter for LiveKit Cloud.
+ *
+ * Collects Pino logs, batches them, and sends via raw HTTP JSON.
+ * No OTEL SDK dependency
+ *
+ * @example
+ * ```typescript
+ * const exporter = new PinoCloudExporter({
+ *   cloudHostname: 'cloud.livekit.io',
+ *   roomId: 'RM_xxx',
+ *   jobId: 'AJ_xxx',
+ * });
+ *
+ * // In Pino formatter hook:
+ * exporter.emit(logObj);
+ *
+ * // On session end:
+ * await exporter.flush();
+ * ```
+ */
+export class PinoCloudExporter {
+  private readonly config: PinoCloudExporterConfig;
+  private readonly loggerName: string;
+  private readonly batchSize: number;
+  private readonly flushIntervalMs: number;
+  private jwt: string | null = null;
+  private pendingLogs: any[] = [];
+  private flushTimer: NodeJS.Timeout | null = null;
+
+  constructor(config: PinoCloudExporterConfig) {
+    this.config = config;
+    this.loggerName = config.loggerName || 'livekit.agents';
+    this.batchSize = config.batchSize || 100;
+    this.flushIntervalMs = config.flushIntervalMs || 5000;
+  }
+
+  emit(logObj: PinoLogObject): void {
+    const record = this.convertToOtlpRecord(logObj);
+    this.pendingLogs.push(record);
+
+    if (!this.flushTimer) {
+      this.flushTimer = setTimeout(() => {
+        this.flush().catch(console.error);
+      }, this.flushIntervalMs);
+    }
+
+    if (this.pendingLogs.length >= this.batchSize) {
+      this.flush().catch(console.error);
+    }
+  }
+
+  private convertToOtlpRecord(logObj: PinoLogObject): any {
+    const { severityNumber, severityText } = mapPinoLevelToSeverity(logObj.level);
+
+    const attributes: any[] = [
+      { key: 'room_id', value: { stringValue: this.config.roomId } },
+      { key: 'job_id', value: { stringValue: this.config.jobId } },
+      { key: 'logger.name', value: { stringValue: this.loggerName } },
+    ];
+
+    if (logObj.pid !== undefined) {
+      attributes.push({ key: 'process.pid', value: { intValue: String(logObj.pid) } });
+    }
+    if (logObj.hostname !== undefined) {
+      attributes.push({ key: 'host.name', value: { stringValue: logObj.hostname } });
+    }
+
+    for (const [key, value] of Object.entries(logObj)) {
+      if (!EXCLUDE_FIELDS.has(key)) {
+        attributes.push({ key, value: convertValue(value) });
+      }
+    }
+
+    return {
+      timeUnixNano: String(BigInt(logObj.time) * BigInt(1_000_000)),
+      observedTimeUnixNano: String(BigInt(Date.now()) * BigInt(1_000_000)),
+      severityNumber,
+      severityText,
+      body: { stringValue: logObj.msg || '' },
+      attributes,
+      traceId: '',
+      spanId: '',
+    };
+  }
+
+  async flush(): Promise<void> {
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+
+    if (this.pendingLogs.length === 0) {
+      return;
+    }
+
+    const logs = this.pendingLogs;
+    this.pendingLogs = [];
+
+    try {
+      await this.sendLogs(logs);
+    } catch (error) {
+      this.pendingLogs = [...logs, ...this.pendingLogs];
+      console.error('[PinoCloudExporter] Failed to flush logs:', error);
+    }
+  }
+
+  private async sendLogs(logRecords: any[]): Promise<void> {
+    await this.ensureJwt();
+
+    const payload = {
+      resourceLogs: [
+        {
+          resource: {
+            attributes: [
+              { key: 'service.name', value: { stringValue: 'livekit-agents' } },
+              { key: 'room_id', value: { stringValue: this.config.roomId } },
+              { key: 'job_id', value: { stringValue: this.config.jobId } },
+            ],
+          },
+          scopeLogs: [
+            {
+              scope: {
+                name: this.loggerName,
+                attributes: [
+                  { key: 'room_id', value: { stringValue: this.config.roomId } },
+                  { key: 'job_id', value: { stringValue: this.config.jobId } },
+                ],
+              },
+              logRecords,
+            },
+          ],
+        },
+      ],
+    };
+
+    const endpoint = `https://${this.config.cloudHostname}/observability/logs/otlp/v0`;
+
+    const response = await fetch(endpoint, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${this.jwt}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(payload),
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`Log export failed: ${response.status} ${response.statusText} - ${text}`);
+    }
+  }
+
+  private async ensureJwt(): Promise<void> {
+    if (this.jwt) return;
+
+    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');
+    }
+
+    const token = new AccessToken(apiKey, apiSecret, { ttl: '6h' });
+    token.addObservabilityGrant({ write: true });
+    this.jwt = await token.toJwt();
+  }
+
+  async shutdown(): Promise<void> {
+    await this.flush();
+  }
+}
+
+let globalExporter: PinoCloudExporter | null = null;
+
+export function initPinoCloudExporter(config: PinoCloudExporterConfig): void {
+  globalExporter = new PinoCloudExporter(config);
+}
+
+export function getPinoCloudExporter(): PinoCloudExporter | null {
+  return globalExporter;
+}
+
+export function emitToOtel(logObj: PinoLogObject): void {
+  if (globalExporter) {
+    globalExporter.emit(logObj);
+  }
+}
+
+export async function flushPinoLogs(): Promise<void> {
+  if (globalExporter) {
+    await globalExporter.flush();
+  }
+}

package/src/telemetry/trace_types.ts

@@ -0,0 +1,95 @@
+// 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';
+
+// Adaptive Interruption attributes
+export const ATTR_IS_INTERRUPTION = 'lk.is_interruption';
+export const ATTR_INTERRUPTION_PROBABILITY = 'lk.interruption.probability';
+export const ATTR_INTERRUPTION_TOTAL_DURATION = 'lk.interruption.total_duration';
+export const ATTR_INTERRUPTION_PREDICTION_DURATION = 'lk.interruption.prediction_duration';
+export const ATTR_INTERRUPTION_DETECTION_DELAY = 'lk.interruption.detection_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';