import { type Tracer } from "@opentelemetry/api";
import type { FabricEvent, FabricEventCallback } from "./types.js";
import type { ObservabilityCorrelation } from "./observability.js";
/**
 * Build a hierarchical OpenTelemetry trace from Fabric's event stream.
 *
 * Unlike {@link openTelemetryExporter} (which emits one flat span per
 * duration-bearing event), this observer nests spans into a tree:
 * `prompt`/`skill` operations contain `turn`s, which contain `tool` / `shell`
 * spans, with `task` sub-work nested under the active operation. The result is
 * a single parent trace per operation that visualizes the full agent run.
 *
 * This module lives on the `@fabric-harness/sdk/otel-observer` subpath (not the
 * main entry) because building parent contexts requires `@opentelemetry/api` at
 * runtime; the main SDK keeps it an optional peer dependency.
 *
 * **Nesting model.** Fabric events carry no operation/turn/tool ids, so the
 * tree is inferred from start/end ordering: each session keeps a stack of open
 * spans, a `*_start` opens a child of the current top, and the matching `*_end`
 * closes it. This is exact for the common sequential case (the session lock
 * serializes operations and tools/turns are emitted start→end in order). A
 * `task()` runs in a child session, so its detailed turns form their own trace;
 * the parent trace shows the `task` span wrapping its duration.
 */
export interface OpenTelemetryObserverOptions {
    /** Tracer to emit spans through. Defaults to the global tracer. */
    tracer?: Tracer;
    /** Attributes added to every emitted span. */
    attributes?: Record<string, string | number | boolean>;
    /** Stable deployment correlation applied to every span. */
    correlation?: ObservabilityCorrelation;
    /**
     * Naming/attribute convention. `'fabric'` (default) emits `fabric.*` span
     * names; `'foundry'` emits `gen_ai.*` names + attributes matching Azure AI
     * Foundry / OpenTelemetry Generative-AI semantic conventions.
     */
    conventions?: "fabric" | "foundry";
    /**
     * Optional callback to sanitize events before they are converted to span
     * attributes. When not provided, a default sanitizer strips sensitive
     * content fields (`text`, `content`, `input`, `output`, `delta`, `result`,
     * `summary`) from event data while preserving metadata.
     */
    sanitize?: (event: FabricEvent) => FabricEvent;
    /** Receives fail-open span mutation/end errors. */
    onError?: (context: string, error: unknown) => void;
}
export declare function createOpenTelemetryObserver(options?: OpenTelemetryObserverOptions): FabricEventCallback;
//# sourceMappingURL=otel-observer.d.ts.map