/**
 * The tracer instance: a {@link Recorder}.
 *
 * A recorder is the object call sites reach for to *start* tracing. It owns a
 * {@link SignalChannel} (the transport sinks drain) and a {@link SampleGate}
 * (admission control), and stamps every trace it produces with a `serviceName`.
 * Its one job is {@link open}: consult the gate, and either mint a live
 * {@link SegmentHandle} whose signals flow onto the channel, or hand back the
 * shared {@link NOOP_HANDLE} so a sampled-out trace costs nothing downstream.
 *
 * This replaces the OTel "tracer provider / tracer" pair with a single, flat
 * object: there is no global ambient context, no `startSpan` ceremony, and no
 * exporter wiring here — sinks subscribe by draining {@link channel}.
 */
import { SignalChannel } from "../channel/signal";
import { type SegmentHandle } from "../signal/handle";
import { type SegmentKind } from "../signal/segment";
import { SampleGate, type SampleStrategy } from "./sampling";
/** Per-`open` options; all optional. */
export interface OpenOptions {
    /**
     * Trace to join. Omit to start a *new* trace (the recorder mints a fresh id
     * and the gate decides on it). Supplied for a child whose admission should
     * follow its trace's verdict.
     */
    readonly traceId?: string;
    /** Enclosing segment id, or `null`/omitted for a trace root. */
    readonly parentId?: string | null;
    /** Initial attributes for the opened segment. */
    readonly attributes?: Readonly<Record<string, unknown>>;
}
/** Construction options for a {@link Recorder}. */
export interface RecorderOptions {
    /**
     * Logical name of the service/agent this recorder traces. Stamped onto the
     * root attributes of every admitted trace under the `service.name` key.
     */
    readonly serviceName: string;
    /** Admission strategy or a pre-built gate; defaults to `"always"`. */
    readonly sampling?: SampleStrategy | SampleGate;
    /** Transport to emit onto; a fresh unbounded {@link SignalChannel} by default. */
    readonly channel?: SignalChannel;
}
/**
 * A homegrown tracer instance.
 *
 * Holds a service name, a {@link SampleGate}, and a {@link SignalChannel}.
 * {@link open} is the sole entry point; {@link channel} exposes the stream for
 * sinks to drain.
 */
export declare class Recorder {
    /** Logical service/agent name stamped onto admitted root traces. */
    readonly serviceName: string;
    private readonly gate;
    private readonly signalChannel;
    constructor(options: RecorderOptions);
    /**
     * Open a segment, subject to sampling.
     *
     * Resolves the trace id (a supplied `opts.traceId` joins an existing trace; a
     * root mints a fresh one), then consults the {@link SampleGate}. Sampled out →
     * the frozen {@link NOOP_HANDLE} (nothing is emitted). Sampled in → a live
     * {@link SegmentHandle} from {@link openHandle}, whose `open` signal — and all
     * subsequent `update`/`close` signals — land on this recorder's channel. A
     * root open also folds `serviceName` into the segment's attributes.
     */
    open(kind: SegmentKind, name: string, opts?: OpenOptions): SegmentHandle;
    /**
     * The recorder's signal stream.
     *
     * Sinks drain this with `for await … of recorder.channel()`. It is the same
     * underlying {@link SignalChannel} every {@link open}ed handle emits onto.
     */
    channel(): SignalChannel;
}
