@pipedog/core 0.0.0 → 0.2.0

package/dist/utils/tracing/setup.d.ts

@@ -0,0 +1,107 @@
+export type OtelAttributeValue = string | number | boolean | ReadonlyArray<string | null | undefined> | ReadonlyArray<number | null | undefined> | ReadonlyArray<boolean | null | undefined>;
+/** `SpanContext` from `@opentelemetry/api`. */
+export interface OtelSpanContext {
+    traceId: string;
+    spanId: string;
+    traceFlags: number;
+    isRemote?: boolean;
+}
+/** `Span` from `@opentelemetry/api`. */
+export interface OtelSpan {
+    spanContext(): OtelSpanContext;
+    setAttribute(key: string, value: OtelAttributeValue): unknown;
+    end(endTime?: unknown): void;
+}
+/** `Context` from `@opentelemetry/api` (opaque). */
+export interface OtelContext {
+    getValue(key: symbol): unknown;
+}
+/** `Tracer` from `@opentelemetry/api`. */
+export interface OtelTracer {
+    startSpan(name: string, options?: Record<string, unknown>, context?: OtelContext): OtelSpan;
+}
+/** The `@opentelemetry/api` module. */
+export interface OtelApi {
+    trace: {
+        getTracer(name: string, version?: string): OtelTracer;
+        wrapSpanContext(spanContext: OtelSpanContext): OtelSpan;
+        setSpan(context: OtelContext, span: OtelSpan): OtelContext;
+        setGlobalTracerProvider(provider: unknown): unknown;
+    };
+    context: {
+        active(): OtelContext;
+    };
+}
+/** The `@opentelemetry/sdk-trace-base` module (v2). */
+export interface OtelSdkTraceBase {
+    BasicTracerProvider: new (config?: {
+        resource?: any;
+        spanProcessors?: any[];
+    }) => unknown;
+    BatchSpanProcessor: new (exporter: any) => unknown;
+    ConsoleSpanExporter: new () => unknown;
+}
+/** The `@opentelemetry/resources` module (v2). */
+export interface OtelResources {
+    resourceFromAttributes(attributes: Record<string, string>): unknown;
+}
+/** The OpenTelemetry modules handed to `registerOpenTelemetry()`. */
+export interface OpenTelemetryModules {
+    /** `@opentelemetry/api`. Enables tracing. */
+    api: OtelApi;
+    /** `@opentelemetry/sdk-trace-base`. Needed by `setupTracing()`. */
+    sdk?: OtelSdkTraceBase | null;
+    /** `@opentelemetry/resources`. Needed by `setupTracing()`. */
+    resources?: OtelResources | null;
+}
+/**
+ * Wait for the automatic `import("@opentelemetry/api")` started when core
+ * loaded, and report whether tracing is available.
+ *
+ * `PipelineWorker` awaits this in its async setup, so a worker built before
+ * the import finished (e.g. at module top level) still traces; the turn trace
+ * observer and the service decorators check availability when they run.
+ *
+ * @returns True if tracing is available, False otherwise.
+ */
+export declare function loadOpenTelemetry(): Promise<boolean>;
+/**
+ * Make OpenTelemetry available to Pipecat explicitly, instead of (or before)
+ * the automatic import of `@opentelemetry/api`. Pass `null` to disable
+ * tracing again.
+ */
+export declare function registerOpenTelemetry(modules: OpenTelemetryModules | null): void;
+/** The registered OpenTelemetry modules, or null if tracing is unavailable. */
+export declare function getOpenTelemetry(): OpenTelemetryModules | null;
+/**
+ * Check if OpenTelemetry tracing is available and configured.
+ *
+ * @returns True if tracing is available, False otherwise.
+ */
+export declare function isTracingAvailable(): boolean;
+export interface SetupTracingOptions {
+    /** The name of the service for traces. Defaults to `"pipecat"`. */
+    serviceName?: string;
+    /**
+     * A pre-configured OpenTelemetry span exporter instance. If null, only
+     * console export will be available if enabled.
+     */
+    exporter?: unknown;
+    /** Whether to also export traces to console (useful for debugging). */
+    consoleExport?: boolean;
+}
+/**
+ * Set up OpenTelemetry tracing with a user-provided exporter.
+ *
+ * Requires `registerOpenTelemetry()` to have been called with the `sdk` and
+ * `resources` modules.
+ *
+ * @returns True if setup was successful, False otherwise.
+ *
+ * @example
+ * // With OTLP exporter
+ * const exporter = new OTLPTraceExporter({ url: "http://localhost:4318/v1/traces" });
+ * setupTracing({ serviceName: "my-service", exporter });
+ */
+export declare function setupTracing(options?: SetupTracingOptions): boolean;
+//# sourceMappingURL=setup.d.ts.map

package/dist/utils/tracing/setup.js

@@ -0,0 +1,160 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/tracing/setup.py
+/**
+ * Core OpenTelemetry tracing utilities and setup for Pipecat.
+ *
+ * This module provides functions to check availability and configure
+ * OpenTelemetry tracing for Pipecat applications. It handles the optional
+ * nature of OpenTelemetry dependencies and provides a safe setup process.
+ *
+ * Porting notes: upstream detects OpenTelemetry by trying to import it, and
+ * treats it as an optional extra (`pipecat-ai[tracing]`). Here
+ * `@opentelemetry/api` is an optional peer dependency of `@pipedog/core`:
+ *
+ * - When this module loads it starts a dynamic `import("@opentelemetry/api")`
+ *   (no top-level await, so importing core never waits or throws). If the
+ *   package is not installed the import fails quietly and tracing stays
+ *   unavailable, exactly like upstream's `OPENTELEMETRY_AVAILABLE = False`.
+ *   Because the import is asynchronous, `isTracingAvailable()` turns true a
+ *   moment after core loads; `await loadOpenTelemetry()` waits for it.
+ *   Nothing latches the early "unavailable": `PipelineWorker` awaits it in
+ *   its async setup before creating the tracing observers.
+ * - `registerOpenTelemetry()` hands the modules in explicitly and
+ *   synchronously (it wins over the automatic import). `@pipedog/tracing`'s
+ *   `setupTracing()` does this, also registering `@opentelemetry/sdk-trace-base`
+ *   and `@opentelemetry/resources`, which this module's `setupTracing()` needs.
+ *
+ * Without OpenTelemetry every tracing helper is a no-op, as upstream behaves.
+ *
+ * @example
+ * import * as api from "@opentelemetry/api";
+ * import * as sdk from "@opentelemetry/sdk-trace-base";
+ * import * as resources from "@opentelemetry/resources";
+ *
+ * registerOpenTelemetry({ api, sdk, resources });
+ * setupTracing({ serviceName: "my-service", exporter: new sdk.ConsoleSpanExporter() });
+ */
+import { rethrowIfCancelled } from "@pipedog/asyncio";
+import { logger } from "../logger.js";
+let openTelemetry = null;
+/** Set once `registerOpenTelemetry()` is called; the automatic import then leaves things alone. */
+let registeredExplicitly = false;
+/**
+ * Import `@opentelemetry/api` if it is installed (upstream's optional import).
+ *
+ * The specifier is a string literal so bundlers (esbuild/wrangler, Bun.build)
+ * bundle the package when it is installed; when it is not, they leave the
+ * `import()` in place and it rejects at runtime, which is caught here.
+ */
+async function importOpenTelemetryApi() {
+    try {
+        const mod = (await import("@opentelemetry/api"));
+        // CommonJS interop (some bundlers) puts the exports on `default`.
+        const api = mod?.trace ? mod : mod?.default;
+        return api?.trace && api.context ? api : null;
+    }
+    catch (e) {
+        rethrowIfCancelled(e);
+        return null;
+    }
+}
+const autoLoad = importOpenTelemetryApi().then((api) => {
+    if (api && !registeredExplicitly) {
+        openTelemetry = { api };
+    }
+});
+/**
+ * Wait for the automatic `import("@opentelemetry/api")` started when core
+ * loaded, and report whether tracing is available.
+ *
+ * `PipelineWorker` awaits this in its async setup, so a worker built before
+ * the import finished (e.g. at module top level) still traces; the turn trace
+ * observer and the service decorators check availability when they run.
+ *
+ * @returns True if tracing is available, False otherwise.
+ */
+export async function loadOpenTelemetry() {
+    await autoLoad;
+    return isTracingAvailable();
+}
+/**
+ * Make OpenTelemetry available to Pipecat explicitly, instead of (or before)
+ * the automatic import of `@opentelemetry/api`. Pass `null` to disable
+ * tracing again.
+ */
+export function registerOpenTelemetry(modules) {
+    registeredExplicitly = true;
+    openTelemetry = modules;
+}
+/** The registered OpenTelemetry modules, or null if tracing is unavailable. */
+export function getOpenTelemetry() {
+    return openTelemetry;
+}
+/**
+ * Check if OpenTelemetry tracing is available and configured.
+ *
+ * @returns True if tracing is available, False otherwise.
+ */
+export function isTracingAvailable() {
+    return openTelemetry !== null;
+}
+function getenv(name) {
+    return globalThis.process?.env?.[name];
+}
+/**
+ * Set up OpenTelemetry tracing with a user-provided exporter.
+ *
+ * Requires `registerOpenTelemetry()` to have been called with the `sdk` and
+ * `resources` modules.
+ *
+ * @returns True if setup was successful, False otherwise.
+ *
+ * @example
+ * // With OTLP exporter
+ * const exporter = new OTLPTraceExporter({ url: "http://localhost:4318/v1/traces" });
+ * setupTracing({ serviceName: "my-service", exporter });
+ */
+export function setupTracing(options = {}) {
+    const serviceName = options.serviceName ?? "pipecat";
+    const exporter = options.exporter ?? null;
+    const consoleExport = options.consoleExport ?? false;
+    const otel = openTelemetry;
+    if (!otel) {
+        return false;
+    }
+    try {
+        const { sdk, resources } = otel;
+        if (!sdk || !resources) {
+            throw new Error("the OpenTelemetry `sdk` and `resources` modules were not registered");
+        }
+        // Create a resource with service info
+        const resource = resources.resourceFromAttributes({
+            "service.name": serviceName,
+            "service.instance.id": getenv("HOSTNAME") ?? "unknown",
+            "deployment.environment": getenv("ENVIRONMENT") ?? "development",
+        });
+        const spanProcessors = [];
+        // Add console exporter if requested (good for debugging)
+        if (consoleExport) {
+            const consoleExporter = new sdk.ConsoleSpanExporter();
+            spanProcessors.push(new sdk.BatchSpanProcessor(consoleExporter));
+        }
+        // Add user-provided exporter if available
+        if (exporter) {
+            spanProcessors.push(new sdk.BatchSpanProcessor(exporter));
+        }
+        // Set up the tracer provider with the resource
+        const tracerProvider = new sdk.BasicTracerProvider({ resource, spanProcessors });
+        otel.api.trace.setGlobalTracerProvider(tracerProvider);
+        return true;
+    }
+    catch (e) {
+        rethrowIfCancelled(e);
+        logger.error(`Error setting up tracing: ${e instanceof Error ? e.message : e}`);
+        return false;
+    }
+}
+//# sourceMappingURL=setup.js.map

package/dist/utils/tracing/tracing_context.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Pipeline-scoped tracing context for OpenTelemetry tracing in Pipecat.
+ *
+ * This module provides a per-pipeline tracing context that holds the current
+ * conversation and turn span contexts. Each PipelineWorker creates its own
+ * TracingContext, ensuring concurrent pipelines do not interfere with each
+ * other.
+ */
+import { type OtelContext, type OtelSpanContext } from "./setup.ts";
+/**
+ * Pipeline-scoped tracing context.
+ *
+ * Holds the current conversation and turn span contexts for a single pipeline.
+ * Created by PipelineWorker, passed to TurnTraceObserver (writer) and services
+ * (readers) via StartFrame.
+ */
+export declare class TracingContext {
+    protected _conversationContext: OtelContext | null;
+    protected _turnContext: OtelContext | null;
+    protected _conversationId: string | null;
+    /**
+     * Set the current conversation context.
+     *
+     * @param spanContext The span context for the current conversation or null to clear it.
+     * @param conversationId Optional ID for the conversation.
+     */
+    setConversationContext(spanContext: OtelSpanContext | null, conversationId?: string | null): void;
+    /**
+     * Get the OpenTelemetry context for the current conversation.
+     *
+     * @returns The current conversation context or null if not available.
+     */
+    getConversationContext(): OtelContext | null;
+    /**
+     * Set the current turn context.
+     *
+     * @param spanContext The span context for the current turn or null to clear it.
+     */
+    setTurnContext(spanContext: OtelSpanContext | null): void;
+    /**
+     * Get the OpenTelemetry context for the current turn.
+     *
+     * @returns The current turn context or null if not available.
+     */
+    getTurnContext(): OtelContext | null;
+    /** The ID for the current conversation, or null if not available. */
+    get conversationId(): string | null;
+    /**
+     * Generate a new conversation ID.
+     *
+     * @returns A new randomly generated UUID string.
+     */
+    static generateConversationId(): string;
+}
+//# sourceMappingURL=tracing_context.d.ts.map

package/dist/utils/tracing/tracing_context.js

@@ -0,0 +1,97 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/tracing/tracing_context.py
+/**
+ * Pipeline-scoped tracing context for OpenTelemetry tracing in Pipecat.
+ *
+ * This module provides a per-pipeline tracing context that holds the current
+ * conversation and turn span contexts. Each PipelineWorker creates its own
+ * TracingContext, ensuring concurrent pipelines do not interfere with each
+ * other.
+ */
+import { getOpenTelemetry } from "./setup.js";
+/** Wrap a span context in a non-recording span and put it in a context. */
+function contextWithSpanContext(spanContext) {
+    const otel = getOpenTelemetry();
+    if (!otel)
+        return null;
+    const nonRecordingSpan = otel.api.trace.wrapSpanContext(spanContext);
+    return otel.api.trace.setSpan(otel.api.context.active(), nonRecordingSpan);
+}
+/**
+ * Pipeline-scoped tracing context.
+ *
+ * Holds the current conversation and turn span contexts for a single pipeline.
+ * Created by PipelineWorker, passed to TurnTraceObserver (writer) and services
+ * (readers) via StartFrame.
+ */
+export class TracingContext {
+    _conversationContext = null;
+    _turnContext = null;
+    _conversationId = null;
+    /**
+     * Set the current conversation context.
+     *
+     * @param spanContext The span context for the current conversation or null to clear it.
+     * @param conversationId Optional ID for the conversation.
+     */
+    setConversationContext(spanContext, conversationId = null) {
+        if (getOpenTelemetry() === null) {
+            return;
+        }
+        this._conversationId = conversationId;
+        if (spanContext) {
+            this._conversationContext = contextWithSpanContext(spanContext);
+        }
+        else {
+            this._conversationContext = null;
+        }
+    }
+    /**
+     * Get the OpenTelemetry context for the current conversation.
+     *
+     * @returns The current conversation context or null if not available.
+     */
+    getConversationContext() {
+        return this._conversationContext;
+    }
+    /**
+     * Set the current turn context.
+     *
+     * @param spanContext The span context for the current turn or null to clear it.
+     */
+    setTurnContext(spanContext) {
+        if (getOpenTelemetry() === null) {
+            return;
+        }
+        if (spanContext) {
+            this._turnContext = contextWithSpanContext(spanContext);
+        }
+        else {
+            this._turnContext = null;
+        }
+    }
+    /**
+     * Get the OpenTelemetry context for the current turn.
+     *
+     * @returns The current turn context or null if not available.
+     */
+    getTurnContext() {
+        return this._turnContext;
+    }
+    /** The ID for the current conversation, or null if not available. */
+    get conversationId() {
+        return this._conversationId;
+    }
+    /**
+     * Generate a new conversation ID.
+     *
+     * @returns A new randomly generated UUID string.
+     */
+    static generateConversationId() {
+        return crypto.randomUUID();
+    }
+}
+//# sourceMappingURL=tracing_context.js.map

package/dist/utils/tracing/turn_trace_observer.d.ts

@@ -0,0 +1,95 @@
+import { BaseObserver, type BaseObserverOptions, type FramePushed } from "../../observers/base_observer.ts";
+import type { TurnTrackingObserver } from "../../observers/turn_tracking_observer.ts";
+import type { UserBotLatencyObserver } from "../../observers/user_bot_latency_observer.ts";
+import { type OtelAttributeValue, type OtelSpan, type OtelSpanContext, type OtelTracer } from "./setup.ts";
+import { TracingContext } from "./tracing_context.ts";
+export interface TurnTraceObserverOptions extends BaseObserverOptions {
+    /** The turn tracking observer to monitor. */
+    turnTracker: TurnTrackingObserver;
+    /** The latency tracking observer for user-bot latency. */
+    latencyTracker: UserBotLatencyObserver;
+    /** Optional conversation ID for grouping turns. */
+    conversationId?: string | null;
+    /** Additional attributes to add to spans. */
+    additionalSpanAttributes?: Record<string, OtelAttributeValue> | null;
+    /** Pipeline-scoped tracing context for span hierarchy. */
+    tracingContext?: TracingContext | null;
+}
+/**
+ * Observer that creates trace spans for each conversation turn.
+ *
+ * This observer uses TurnTrackingObserver to track turns and creates
+ * OpenTelemetry spans for each turn. Service spans (STT, LLM, TTS)
+ * become children of the turn spans.
+ *
+ * If conversation tracing is enabled, turns become children of a
+ * conversation span that encapsulates the entire session.
+ */
+export declare class TurnTraceObserver extends BaseObserver {
+    protected _turnTracker: TurnTrackingObserver;
+    protected _latencyTracker: UserBotLatencyObserver;
+    protected _tracingContext: TracingContext;
+    protected _currentSpan: OtelSpan | null;
+    protected _currentTurnNumber: number;
+    protected _traceContextMap: Map<number, OtelSpanContext>;
+    protected _tracer: OtelTracer | null;
+    protected _conversationSpan: OtelSpan | null;
+    protected _conversationId: string | null;
+    protected _additionalSpanAttributes: Record<string, OtelAttributeValue>;
+    /** Initialize the turn trace observer. */
+    constructor(options: TurnTraceObserverOptions);
+    /**
+     * The turn tracer, resolved on first use if OpenTelemetry was not available
+     * yet when the observer was built (core imports it asynchronously).
+     */
+    protected _getTracer(): OtelTracer | null;
+    /**
+     * Handle latency measurement events.
+     *
+     * Called when the latency tracker measures user-to-bot latency.
+     * Adds the latency as an attribute to the current turn span.
+     *
+     * @param latencySeconds The measured latency in seconds.
+     */
+    protected _handleLatencyMeasured(latencySeconds: number): Promise<void>;
+    /**
+     * Process a frame without modifying it.
+     *
+     * Handles StartFrame to begin conversation tracing early, ensuring
+     * that any spans created before Turn 1 (e.g., from flow initialization)
+     * are properly attached to the conversation trace.
+     *
+     * @param data The frame push event data.
+     */
+    onPushFrame(data: FramePushed): Promise<void>;
+    /**
+     * Start a new conversation span.
+     *
+     * @param conversationId Optional custom ID for the conversation. If null, a UUID will be generated.
+     */
+    startConversationTracing(conversationId?: string | null): void;
+    /** End the current conversation span and ensure the last turn is closed. */
+    endConversationTracing(): void;
+    /** Handle a turn start event by creating a new span. */
+    protected _handleTurnStarted(turnNumber: number): Promise<void>;
+    /** Handle a turn end event by ending the current span. */
+    protected _handleTurnEnded(turnNumber: number, duration: number, wasInterrupted: boolean): Promise<void>;
+    /**
+     * Get the span context for the current turn.
+     *
+     * This can be used by services to create child spans.
+     *
+     * @returns The current turn's span context or null if not available.
+     */
+    getCurrentTurnContext(): OtelSpanContext | null;
+    /**
+     * Get the span context for a specific turn.
+     *
+     * This can be used by services to create child spans.
+     *
+     * @param turnNumber The turn number to get context for.
+     * @returns The specified turn's span context or null if not available.
+     */
+    getTurnContext(turnNumber: number): OtelSpanContext | null;
+}
+//# sourceMappingURL=turn_trace_observer.d.ts.map