@pipedog/core 0.0.0 → 0.1.0

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

@@ -0,0 +1,95 @@
+export type OtelAttributeValue = string | number | boolean | readonly string[] | readonly number[] | readonly boolean[];
+/** `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?: unknown;
+        spanProcessors?: unknown[];
+    }) => unknown;
+    BatchSpanProcessor: new (exporter: unknown) => 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;
+}
+/**
+ * Make OpenTelemetry available to Pipecat (upstream's optional import).
+ * 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,110 @@
+// 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. Core
+ * takes no third-party dependencies, so the OpenTelemetry JS modules are
+ * handed in instead, once, at startup:
+ *
+ * @example
+ * import * as api from "@opentelemetry/api";
+ * import * as sdk from "@opentelemetry/sdk-trace-base";
+ * import * as resources from "@opentelemetry/resources";
+ * import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+ *
+ * registerOpenTelemetry({ api, sdk, resources });
+ * setupTracing({
+ *   serviceName: "my-service",
+ *   exporter: new OTLPTraceExporter({ url: "http://localhost:4318/v1/traces" }),
+ * });
+ *
+ * Until `registerOpenTelemetry()` is called, `isTracingAvailable()` is false and
+ * every tracing helper is a no-op, as upstream behaves without OpenTelemetry.
+ */
+import { rethrowIfCancelled } from "@pipedog/asyncio";
+import { logger } from "../logger.js";
+let openTelemetry = null;
+/**
+ * Make OpenTelemetry available to Pipecat (upstream's optional import).
+ * Pass `null` to disable tracing again.
+ */
+export function registerOpenTelemetry(modules) {
+    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,90 @@
+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);
+    /**
+     * 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

package/dist/utils/tracing/turn_trace_observer.js

@@ -0,0 +1,219 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/tracing/turn_trace_observer.py
+/**
+ * Turn trace observer for OpenTelemetry tracing in Pipecat.
+ *
+ * This module provides an observer that creates trace spans for each
+ * conversation turn, integrating with the turn tracking system to provide
+ * hierarchical tracing of conversation flows.
+ */
+import { StartFrame } from "../../frames/frames.js";
+import { BaseObserver, } from "../../observers/base_observer.js";
+import { logger } from "../logger.js";
+import { getOpenTelemetry, isTracingAvailable, } from "./setup.js";
+import { TracingContext } from "./tracing_context.js";
+/**
+ * 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 class TurnTraceObserver extends BaseObserver {
+    _turnTracker;
+    _latencyTracker;
+    _tracingContext;
+    _currentSpan = null;
+    _currentTurnNumber = 0;
+    _traceContextMap = new Map();
+    _tracer;
+    // Conversation tracking properties
+    _conversationSpan = null;
+    _conversationId;
+    _additionalSpanAttributes;
+    /** Initialize the turn trace observer. */
+    constructor(options) {
+        super(options);
+        this._turnTracker = options.turnTracker;
+        this._latencyTracker = options.latencyTracker;
+        this._tracingContext = options.tracingContext || new TracingContext();
+        this._tracer = getOpenTelemetry()?.api.trace.getTracer("pipecat.turn") ?? null;
+        this._conversationId = options.conversationId ?? null;
+        this._additionalSpanAttributes = options.additionalSpanAttributes || {};
+        this._turnTracker.eventHandler("on_turn_started", async (_tracker, turnNumber) => {
+            await this._handleTurnStarted(turnNumber);
+        });
+        this._turnTracker.eventHandler("on_turn_ended", async (_tracker, turnNumber, duration, wasInterrupted) => {
+            await this._handleTurnEnded(turnNumber, duration, wasInterrupted);
+        });
+        this._latencyTracker.eventHandler("on_latency_measured", async (_tracker, latencySeconds) => {
+            await this._handleLatencyMeasured(latencySeconds);
+        });
+    }
+    /**
+     * 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.
+     */
+    async _handleLatencyMeasured(latencySeconds) {
+        if (this._currentSpan && isTracingAvailable()) {
+            this._currentSpan.setAttribute("turn.user_bot_latency_seconds", latencySeconds);
+            logger.debug(`Turn ${this._currentTurnNumber} user-bot latency: ${latencySeconds.toFixed(3)}s`);
+        }
+    }
+    /**
+     * 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.
+     */
+    async onPushFrame(data) {
+        if (data.frame instanceof StartFrame && !this._conversationSpan) {
+            this.startConversationTracing(this._conversationId);
+        }
+    }
+    /**
+     * Start a new conversation span.
+     *
+     * @param conversationId Optional custom ID for the conversation. If null, a UUID will be generated.
+     */
+    startConversationTracing(conversationId = null) {
+        if (!isTracingAvailable() || !this._tracer) {
+            return;
+        }
+        // Generate a conversation ID if not provided
+        if (conversationId === null) {
+            conversationId = TracingContext.generateConversationId();
+            logger.debug(`Generated new conversation ID: ${conversationId}`);
+        }
+        this._conversationId = conversationId;
+        // Create a new span for this conversation
+        const conversationSpan = this._tracer.startSpan("conversation");
+        this._conversationSpan = conversationSpan;
+        // Set span attributes
+        conversationSpan.setAttribute("conversation.id", conversationId);
+        conversationSpan.setAttribute("conversation.type", "voice");
+        // Set custom otel attributes if provided
+        for (const [k, v] of Object.entries(this._additionalSpanAttributes || {})) {
+            conversationSpan.setAttribute(k, v);
+        }
+        // Update the tracing context
+        this._tracingContext.setConversationContext(conversationSpan.spanContext(), conversationId);
+        logger.debug(`Started tracing for Conversation ${conversationId}`);
+    }
+    /** End the current conversation span and ensure the last turn is closed. */
+    endConversationTracing() {
+        if (!isTracingAvailable()) {
+            return;
+        }
+        // First, ensure any active turn is closed properly
+        if (this._currentSpan) {
+            // If we have an active turn span, end it with a standard duration
+            logger.debug(`Ending Turn ${this._currentTurnNumber} due to conversation end`);
+            this._currentSpan.setAttribute("turn.was_interrupted", true);
+            this._currentSpan.setAttribute("turn.ended_by_conversation_end", true);
+            this._currentSpan.end();
+            this._currentSpan = null;
+            // Clear the turn context
+            this._tracingContext.setTurnContext(null);
+        }
+        // Now end the conversation span if it exists
+        if (this._conversationSpan) {
+            // End the span
+            this._conversationSpan.end();
+            this._conversationSpan = null;
+            // Clear the conversation context
+            this._tracingContext.setConversationContext(null);
+            logger.debug(`Ended tracing for Conversation ${this._conversationId}`);
+            this._conversationId = null;
+        }
+    }
+    /** Handle a turn start event by creating a new span. */
+    async _handleTurnStarted(turnNumber) {
+        if (!isTracingAvailable() || !this._tracer) {
+            return;
+        }
+        if (turnNumber === 1 && !this._conversationSpan) {
+            this.startConversationTracing(this._conversationId);
+        }
+        // Get the parent context - conversation if available, otherwise use root context
+        let parentContext = null;
+        if (this._conversationSpan) {
+            parentContext = this._tracingContext.getConversationContext();
+        }
+        // Create a new span for this turn
+        const currentSpan = this._tracer.startSpan("turn", undefined, parentContext ?? undefined);
+        this._currentSpan = currentSpan;
+        this._currentTurnNumber = turnNumber;
+        // Set span attributes
+        currentSpan.setAttribute("turn.number", turnNumber);
+        currentSpan.setAttribute("turn.type", "conversation");
+        // Add conversation ID attribute if available
+        if (this._conversationId) {
+            currentSpan.setAttribute("conversation.id", this._conversationId);
+        }
+        // Store the span context so services can become children of this span
+        this._traceContextMap.set(turnNumber, currentSpan.spanContext());
+        // Update the tracing context so services can access this span
+        this._tracingContext.setTurnContext(currentSpan.spanContext());
+        logger.debug(`Started tracing for Turn ${turnNumber}`);
+    }
+    /** Handle a turn end event by ending the current span. */
+    async _handleTurnEnded(turnNumber, duration, wasInterrupted) {
+        if (!isTracingAvailable() || !this._currentSpan) {
+            return;
+        }
+        // Only end the span if it matches the current turn
+        if (turnNumber === this._currentTurnNumber) {
+            // Set additional attributes
+            this._currentSpan.setAttribute("turn.duration_seconds", duration);
+            this._currentSpan.setAttribute("turn.was_interrupted", wasInterrupted);
+            // End the span
+            this._currentSpan.end();
+            this._currentSpan = null;
+            // Clear the turn context
+            this._tracingContext.setTurnContext(null);
+            logger.debug(`Ended tracing for Turn ${turnNumber}`);
+        }
+    }
+    /**
+     * 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() {
+        if (!isTracingAvailable() || !this._currentSpan) {
+            return null;
+        }
+        return this._currentSpan.spanContext();
+    }
+    /**
+     * 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) {
+        if (!isTracingAvailable()) {
+            return null;
+        }
+        return this._traceContextMap.get(turnNumber) ?? null;
+    }
+}
+//# sourceMappingURL=turn_trace_observer.js.map