/**
 * @module trace-spans
 * Distributed tracing spans with parent-child relationships
 *
 * Provides span tracking for distributed tracing with automatic timing,
 * attribute collection, and integration with W3C Trace Context.
 *
 * Performance target: <1ms overhead per operation
 *
 * Usage:
 * ```typescript
 * import { TraceSpan, SpanRecorder } from '@private.me/xbind';
 *
 * // Create a span recorder
 * const recorder = new SpanRecorder();
 *
 * // Start a span
 * const span = recorder.startSpan('operation-name', { attr: 'value' });
 *
 * // Do work...
 *
 * // End the span
 * span.end();
 *
 * // Get completed spans
 * const spans = recorder.getCompletedSpans();
 * ```
 */
import { TraceContext } from './trace-context.js';
/**
 * Span status codes (aligned with OpenTelemetry)
 */
export declare enum SpanStatusCode {
    /** Operation completed successfully */
    OK = 0,
    /** Operation encountered an error */
    ERROR = 1,
    /** Status is unset (default) */
    UNSET = 2
}
/**
 * Span status
 */
export interface SpanStatus {
    code: SpanStatusCode;
    message?: string;
}
/**
 * Span attributes (key-value pairs)
 */
export interface SpanAttributes {
    [key: string]: string | number | boolean | undefined;
}
/**
 * Span event (timestamped log entry within a span)
 */
export interface SpanEvent {
    /** Event name */
    name: string;
    /** Event timestamp (milliseconds since epoch) */
    timestamp: number;
    /** Event attributes */
    attributes?: SpanAttributes;
}
/**
 * Span kind (aligned with OpenTelemetry)
 */
export declare enum SpanKind {
    /** Internal span (default) */
    INTERNAL = 0,
    /** Server span (handling incoming request) */
    SERVER = 1,
    /** Client span (outgoing request) */
    CLIENT = 2,
    /** Producer span (message queue producer) */
    PRODUCER = 3,
    /** Consumer span (message queue consumer) */
    CONSUMER = 4
}
/**
 * Completed span data
 */
export interface SpanData {
    /** Span ID (16 hex characters) */
    spanId: string;
    /** Trace ID (32 hex characters) */
    traceId: string;
    /** Parent span ID (16 hex characters, if any) */
    parentSpanId?: string;
    /** Span name */
    name: string;
    /** Span kind */
    kind: SpanKind;
    /** Start timestamp (milliseconds since epoch) */
    startTime: number;
    /** End timestamp (milliseconds since epoch) */
    endTime: number;
    /** Duration in milliseconds */
    duration: number;
    /** Span status */
    status: SpanStatus;
    /** Span attributes */
    attributes: SpanAttributes;
    /** Span events */
    events: SpanEvent[];
}
/**
 * Trace span for distributed tracing
 *
 * Represents a single unit of work in a distributed trace with automatic timing.
 */
export declare class TraceSpan {
    /** Span ID (unique within trace) */
    readonly spanId: string;
    /** Trace context */
    readonly traceContext: TraceContext;
    /** Span name */
    readonly name: string;
    /** Span kind */
    readonly kind: SpanKind;
    /** Parent span ID */
    readonly parentSpanId?: string;
    /** Start timestamp (milliseconds since epoch) */
    readonly startTime: number;
    /** End timestamp (milliseconds since epoch, undefined if not ended) */
    private endTime?;
    /** Span status */
    private status;
    /** Span attributes */
    private attributes;
    /** Span events */
    private events;
    /** Whether span has ended */
    private ended;
    /**
     * Create a trace span
     *
     * @param name - Span name
     * @param traceContext - Trace context
     * @param options - Span options
     */
    constructor(name: string, traceContext: TraceContext, options?: {
        kind?: SpanKind;
        parentSpanId?: string;
        attributes?: SpanAttributes;
    });
    /**
     * Set span attribute
     *
     * @param key - Attribute key
     * @param value - Attribute value
     * @returns This span (for chaining)
     */
    setAttribute(key: string, value: string | number | boolean): this;
    /**
     * Set multiple span attributes
     *
     * @param attributes - Attributes to set
     * @returns This span (for chaining)
     */
    setAttributes(attributes: SpanAttributes): this;
    /**
     * Add an event to the span
     *
     * Events are timestamped log entries within a span.
     *
     * @param name - Event name
     * @param attributes - Optional event attributes
     * @returns This span (for chaining)
     */
    addEvent(name: string, attributes?: SpanAttributes): this;
    /**
     * Set span status
     *
     * @param code - Status code
     * @param message - Optional status message
     * @returns This span (for chaining)
     */
    setStatus(code: SpanStatusCode, message?: string): this;
    /**
     * Record an exception in the span
     *
     * Automatically sets status to ERROR and adds exception event.
     *
     * @param error - Error to record
     * @returns This span (for chaining)
     */
    recordException(error: Error | unknown): this;
    /**
     * End the span
     *
     * Records the end timestamp and marks the span as complete.
     * If status is UNSET, automatically sets to OK.
     *
     * @param endTime - Optional end timestamp (defaults to now)
     */
    end(endTime?: number): void;
    /**
     * Check if span has ended
     *
     * @returns True if ended
     */
    isEnded(): boolean;
    /**
     * Get span duration in milliseconds
     *
     * @returns Duration or null if not ended
     */
    getDuration(): number | null;
    /**
     * Export span data
     *
     * @returns Span data (throws if span not ended)
     */
    toData(): SpanData;
    /**
     * Create a child span
     *
     * The child span will have the same trace ID but a new span ID.
     *
     * @param name - Child span name
     * @param options - Span options
     * @returns New child span
     */
    createChild(name: string, options?: {
        kind?: SpanKind;
        attributes?: SpanAttributes;
    }): TraceSpan;
}
/**
 * Span recorder for collecting completed spans
 *
 * Manages span lifecycle and provides access to completed span data.
 */
export declare class SpanRecorder {
    /** Active spans (not yet ended) */
    private activeSpans;
    /** Completed spans */
    private completedSpans;
    /** Maximum number of completed spans to keep (prevent memory leak) */
    private maxSpans;
    /** Trace context for root spans */
    private rootContext?;
    /**
     * Create a span recorder
     *
     * @param options - Recorder options
     */
    constructor(options?: {
        maxSpans?: number;
        traceContext?: TraceContext;
    });
    /**
     * Start a new span
     *
     * @param name - Span name
     * @param options - Span options
     * @returns New span
     */
    startSpan(name: string, options?: {
        kind?: SpanKind;
        attributes?: SpanAttributes;
        traceContext?: TraceContext;
        parentSpan?: TraceSpan;
    }): TraceSpan;
    /**
     * End a span and record its data
     *
     * @param span - Span to end
     */
    private endSpan;
    /**
     * Get all completed spans
     *
     * @returns Array of completed span data
     */
    getCompletedSpans(): readonly SpanData[];
    /**
     * Get active spans
     *
     * @returns Array of active spans
     */
    getActiveSpans(): readonly TraceSpan[];
    /**
     * Clear all completed spans
     */
    clearCompletedSpans(): void;
    /**
     * Get span count
     *
     * @returns Object with active and completed span counts
     */
    getSpanCount(): {
        active: number;
        completed: number;
    };
    /**
     * Find completed spans by trace ID
     *
     * @param traceId - Trace ID to search for
     * @returns Array of matching spans
     */
    findSpansByTraceId(traceId: string): SpanData[];
    /**
     * Build trace tree from completed spans
     *
     * Groups spans by trace ID and builds parent-child relationships.
     *
     * @param traceId - Trace ID to build tree for
     * @returns Tree structure
     */
    buildTraceTree(traceId: string): SpanTree | null;
}
/**
 * Span tree node (for visualization)
 */
export interface SpanTree {
    span: SpanData;
    children: SpanTree[];
}
/**
 * Helper function to measure async operation with automatic span tracking
 *
 * @param recorder - Span recorder
 * @param name - Span name
 * @param fn - Async function to measure
 * @param options - Span options
 * @returns Result of async function
 *
 * @example
 * ```typescript
 * const result = await measureAsync(recorder, 'database-query', async () => {
 *   return await db.query('SELECT * FROM users');
 * });
 * ```
 */
export declare function measureAsync<T>(recorder: SpanRecorder, name: string, fn: () => Promise<T>, options?: {
    kind?: SpanKind;
    attributes?: SpanAttributes;
}): Promise<T>;
/**
 * Helper function to measure sync operation with automatic span tracking
 *
 * @param recorder - Span recorder
 * @param name - Span name
 * @param fn - Sync function to measure
 * @param options - Span options
 * @returns Result of sync function
 *
 * @example
 * ```typescript
 * const result = measureSync(recorder, 'encryption', () => {
 *   return encrypt(data, key);
 * });
 * ```
 */
export declare function measureSync<T>(recorder: SpanRecorder, name: string, fn: () => T, options?: {
    kind?: SpanKind;
    attributes?: SpanAttributes;
}): T;
