import { type Attributes, type Context, type Span, type Tracer, type TracerProvider } from '@opentelemetry/api';
import type { ReadableSpan, Span as SdkSpan, SpanExporter, SpanProcessor } from '@opentelemetry/sdk-trace-base';
import { type SessionReport } from '../voice/report.js';
import type { ObservabilityEndpoint } from './observability_endpoint.js';
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;
    /** Optional start time for the span in milliseconds (Date.now() format) */
    startTime?: number;
}
/**
 * An object that can appear in `AgentSession` options (a turn detector, a model) and wants the
 * session report to show its configuration.
 *
 * Return the options worth reporting, keyed by name; values can be primitives, plain objects or
 * arrays of them. Leave secrets and endpoints out: the report is uploaded. Objects without this
 * method are reported by class name alone.
 *
 * @public
 */
export interface DescribesOptions {
    /** The options worth reporting, keyed by name. Never credentials or endpoints. */
    describeOptions(): Readonly<Record<string, unknown>>;
}
/** @deprecated Use OpenTelemetry SDK 2.x's `SpanProcessor` type directly. */
export type SpanProcessorLike = SpanProcessor;
/**
 * 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;
    /**
     * Returns the current tracer provider — the API's ProxyTracerProvider if none has been set
     * via setProvider(), which callers use to detect whether a user-configured provider exists.
     */
    getProvider(): TracerProvider;
    /**
     * 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;
type SpanProcessorRegistrar = (spanProcessor: SpanProcessor) => void;
/**
 * Span processor that forwards to a list of processors that can grow after the owning provider
 * is constructed.
 *
 * OpenTelemetry 2.x providers accept span processors only at construction time. Include one of
 * these in the provider's `spanProcessors` and pass its {@link FanoutSpanProcessor.add | add}
 * method as `registerSpanProcessor` so LiveKit Cloud tracing can attach its processors later.
 */
export declare class FanoutSpanProcessor implements SpanProcessor {
    private readonly processors;
    /** Adds a processor that receives all span events from this point on. */
    add(processor: SpanProcessor): void;
    onStart(span: SdkSpan, parentContext: Context): void;
    onEnding(span: SdkSpan): void;
    onEnd(span: ReadableSpan): void;
    forceFlush(): Promise<void>;
    shutdown(): Promise<void>;
}
/** Inputs for building a span processor that exports to LiveKit Cloud. */
export interface CloudSpanProcessorOptions {
    /** OTLP/HTTP protobuf endpoint for LiveKit Cloud traces. */
    url: string;
    /** Request headers, including the authorization token, the exporter must send. */
    headers: Record<string, string>;
    /** Framework-owned exporter that applies LiveKit Cloud's recording-disabled upload gate. */
    exporter: SpanExporter;
}
/** Options for configuring a custom tracer provider. */
export interface SetTracerProviderOptions {
    /** Attributes to add to every span created by the provider. */
    metadata?: Attributes;
    /**
     * Adds a span processor to the provider.
     *
     * OpenTelemetry 2.x providers no longer expose `addSpanProcessor`. Supply this callback when
     * using a provider backed by a mutable or delegating span processor so LiveKit Cloud tracing can
     * share the same provider as another observability backend.
     */
    registerSpanProcessor?: SpanProcessorRegistrar;
    /**
     * Builds the span processor that exports to LiveKit Cloud, called when cloud tracing starts.
     *
     * The built-in OpenTelemetry SDK 2.x cloud processor is used by default. Supply this callback
     * only to override how that processor is constructed:
     *
     * ```typescript
     * import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-node';
     *
     * createCloudSpanProcessor: ({ exporter }) => new BatchSpanProcessor(exporter)
     * ```
     *
     * Build the processor around the supplied exporter so the recording-disabled upload gate remains
     * active. The returned processor must use OpenTelemetry SDK 2.x.
     */
    createCloudSpanProcessor?: (options: CloudSpanProcessorOptions) => SpanProcessor;
    /**
     * Whether this provider's exporters may receive conversational content, tool payloads and
     * other user data.
     *
     * Defaults to `true` (or `LIVEKIT_TELEMETRY_ALLOW_PII`, when set), since a GenAI backend
     * can only render the conversation if it receives it. Pass `false` to strip PII in-process
     * before every exporter but LiveKit Cloud's, leaving them the non-content attributes.
     * Ignored when the project mandates redaction — that setting is not weakened from here.
     */
    allowPii?: boolean;
}
/**
 * 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
 * @param options - Optional provider configuration
 *
 * @example OpenTelemetry SDK 2.x — share one provider between another backend and LiveKit Cloud.
 * SDK 2.x providers accept span processors only at construction time, so the provider must be
 * built around a processor whose targets can grow later ({@link FanoutSpanProcessor}). The
 * built-in cloud exporter is SDK 2.x and is attached through the fanout automatically.
 * ```typescript
 * import { telemetry } from '@livekit/agents';
 * import { BatchSpanProcessor, NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
 *
 * const fanout = new telemetry.FanoutSpanProcessor();
 * const provider = new NodeTracerProvider({
 *   spanProcessors: [new BatchSpanProcessor(myBackendExporter), fanout],
 * });
 * provider.register();
 * telemetry.setTracerProvider(provider, {
 *   metadata: { room_id: 'room123', job_id: 'job456' },
 *   registerSpanProcessor: (processor) => fanout.add(processor),
 * });
 * ```
 */
export declare function setTracerProvider(provider: TracerProvider, options?: SetTracerProviderOptions): 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 observabilityUrl properties
 *
 * @internal
 */
export declare function setupCloudTracer(options: ObservabilityEndpoint & {
    roomId: string;
    jobId: string;
    agentName?: string;
    enableTraces?: boolean;
    enableLogs?: boolean;
    metadata?: Attributes;
}): Promise<void>;
/**
 * Flush all pending Pino logs to ensure they are exported.
 * Call this before session/job ends to ensure all logs are sent.
 *
 * @internal
 */
export declare function flushOtelLogs(): Promise<void>;
/**
 * Export every measurement the cloud meter provider holds. Call it once all work that could
 * record a metric is done: the job process exits explicitly, so no later flush would run.
 *
 * @internal
 */
export declare function flushCloudMetrics(): Promise<void>;
/**
 * Render an object from the session options as `Class` or, when it implements
 * {@link DescribesOptions}, `Class(k=v, ...)`.
 *
 * The OTel log exporter walks the enumerable properties of anything that is not a primitive,
 * which for these objects would dump their internals (a turn detector's cloud credentials
 * among them). The class alone is stable and safe; the object itself decides what else is
 * worth showing.
 *
 * @internal
 */
export declare function describeOptionObject(value: object): string;
/**
 * Serialize one session option value into JSON-safe primitives and containers.
 *
 * Primitives pass through (`undefined` becomes `null`); plain objects and `Map`s recurse with
 * the key aliases and omissions applied; arrays, `Set`s (sorted, for a deterministic report) and
 * other iterables are serialized element-wise, since any iterable is a valid option value;
 * anything else is reported by class via {@link describeOptionObject}.
 *
 * @internal
 */
export declare function serializeOptionValue(value: unknown): unknown;
/** @internal */
export declare function serializeSessionOptions(options: SessionReport['options']): Record<string, unknown>;
/**
 * Upload session report to LiveKit Cloud observability.
 * @param options - Configuration with agentName, observabilityUrl, and report
 */
export declare function uploadSessionReport(options: ObservabilityEndpoint & {
    agentName: string;
    report: SessionReport;
    metadata?: Attributes;
}): Promise<void>;
export {};
//# sourceMappingURL=traces.d.ts.map