/**
 * @db4/core - Telemetry Hooks
 *
 * A telemetry module for tracking database operations with:
 * - Event types: query, write, error, performance
 * - Span tracking for distributed tracing
 * - Pluggable collector interface
 * - Async hooks for non-blocking telemetry
 * - Sampling support for high-throughput scenarios
 *
 * @packageDocumentation
 */
/**
 * Telemetry event categories.
 */
export type TelemetryEventCategory = 'query' | 'write' | 'error' | 'performance';
/**
 * Specific telemetry event types within each category.
 */
export type TelemetryEventType = 'query:start' | 'query:end' | 'query:error' | 'query:slow' | 'write:start' | 'write:end' | 'write:error' | 'write:batch' | 'error:validation' | 'error:conflict' | 'error:timeout' | 'error:internal' | 'performance:memory' | 'performance:latency' | 'performance:throughput' | 'performance:cache';
/**
 * Status of a telemetry span.
 */
export type SpanStatus = 'ok' | 'error' | 'timeout' | 'cancelled';
/**
 * Span kind for categorizing spans.
 */
export type SpanKind = 'internal' | 'client' | 'server' | 'producer' | 'consumer';
/**
 * Attributes that can be attached to events and spans.
 */
export interface TelemetryAttributes {
    [key: string]: string | number | boolean | string[] | number[] | undefined;
}
/**
 * Base telemetry event interface.
 */
export interface TelemetryEvent {
    /** Unique event ID */
    eventId: string;
    /** Event type */
    type: TelemetryEventType;
    /** Event category */
    category: TelemetryEventCategory;
    /** ISO8601 timestamp */
    timestamp: string;
    /** Event duration in milliseconds (if applicable) */
    duration?: number | undefined;
    /** Associated span ID */
    spanId?: string | undefined;
    /** Associated trace ID */
    traceId?: string | undefined;
    /** Parent span ID */
    parentSpanId?: string | undefined;
    /** Event attributes */
    attributes?: TelemetryAttributes | undefined;
    /** Shard ID where the event occurred */
    shardId?: string | undefined;
    /** Collection name (for document operations) */
    collection?: string | undefined;
    /** Document count affected */
    documentCount?: number | undefined;
}
/**
 * Query-specific telemetry event.
 */
export interface QueryTelemetryEvent extends TelemetryEvent {
    category: 'query';
    type: 'query:start' | 'query:end' | 'query:error' | 'query:slow';
    /** Query filters as JSON string */
    filters?: string;
    /** Number of results returned */
    resultCount?: number;
    /** Query execution plan strategy */
    strategy?: string;
    /** Whether cache was used */
    cacheHit?: boolean;
    /** Estimated rows scanned */
    rowsScanned?: number;
    /** Index used for the query */
    indexUsed?: string;
}
/**
 * Write-specific telemetry event.
 */
export interface WriteTelemetryEvent extends TelemetryEvent {
    category: 'write';
    type: 'write:start' | 'write:end' | 'write:error' | 'write:batch';
    /** Operation type */
    operation?: 'insert' | 'update' | 'delete' | 'upsert';
    /** Number of documents in batch */
    batchSize?: number;
    /** Document IDs affected */
    documentIds?: string[];
    /** Size in bytes of the write */
    sizeBytes?: number;
}
/**
 * Error-specific telemetry event.
 */
export interface ErrorTelemetryEvent extends TelemetryEvent {
    category: 'error';
    type: 'error:validation' | 'error:conflict' | 'error:timeout' | 'error:internal';
    /** Error code */
    errorCode?: string;
    /** Error message */
    errorMessage?: string;
    /** Stack trace (if available) */
    stackTrace?: string;
    /** Recovery attempted */
    recoveryAttempted?: boolean;
    /** Recovery successful */
    recoverySuccessful?: boolean;
}
/**
 * Performance-specific telemetry event.
 */
export interface PerformanceTelemetryEvent extends TelemetryEvent {
    category: 'performance';
    type: 'performance:memory' | 'performance:latency' | 'performance:throughput' | 'performance:cache';
    /** Memory usage in bytes */
    memoryUsed?: number;
    /** Peak memory usage in bytes */
    peakMemory?: number;
    /** Memory limit in bytes */
    memoryLimit?: number;
    /** Latency percentiles */
    latencyP50?: number;
    latencyP95?: number;
    latencyP99?: number;
    /** Operations per second */
    throughput?: number;
    /** Cache hit rate (0-1) */
    cacheHitRate?: number;
    /** Cache size */
    cacheSize?: number;
}
/**
 * Telemetry span for tracking operation timing and context.
 */
export interface TelemetrySpan {
    /** Unique span ID */
    spanId: string;
    /** Trace ID (shared across related spans) */
    traceId: string;
    /** Parent span ID */
    parentSpanId?: string | undefined;
    /** Human-readable span name */
    name: string;
    /** Span kind */
    kind: SpanKind;
    /** Start time in milliseconds since epoch */
    startTime: number;
    /** End time in milliseconds since epoch */
    endTime?: number | undefined;
    /** Duration in milliseconds */
    duration?: number | undefined;
    /** Span status */
    status: SpanStatus;
    /** Span attributes */
    attributes: TelemetryAttributes;
    /** Events that occurred during this span */
    events: TelemetryEvent[];
    /** Error information (if status is 'error') */
    error?: {
        code?: string | undefined;
        message: string;
        stack?: string | undefined;
    } | undefined;
}
/**
 * Active span handle for managing span lifecycle.
 */
export interface ActiveSpan {
    /** Get the span ID */
    getSpanId(): string;
    /** Get the trace ID */
    getTraceId(): string;
    /** Add an attribute to the span */
    setAttribute(key: string, value: string | number | boolean): void;
    /** Add multiple attributes */
    setAttributes(attributes: TelemetryAttributes): void;
    /** Record an event within this span */
    recordEvent(event: Omit<TelemetryEvent, 'spanId' | 'traceId' | 'parentSpanId' | 'eventId' | 'timestamp'>): void;
    /** Set the span status */
    setStatus(status: SpanStatus, message?: string): void;
    /** Record an error */
    recordError(error: Error | string): void;
    /** End the span */
    end(): void;
    /** Check if span is ended */
    isEnded(): boolean;
}
/**
 * Sampling configuration for telemetry collection.
 */
export interface TelemetrySamplingConfig {
    /** Sample rate for query events (0-1) */
    query?: number;
    /** Sample rate for write events (0-1) */
    write?: number;
    /** Sample rate for error events (0-1, default 1.0) */
    error?: number;
    /** Sample rate for performance events (0-1) */
    performance?: number;
}
/**
 * Telemetry collector interface.
 * Implement this to export telemetry to external systems.
 */
export interface TelemetryCollector {
    /** Collect a telemetry event */
    collectEvent(event: TelemetryEvent): void;
    /** Collect a completed span */
    collectSpan(span: TelemetrySpan): void;
    /** Flush any buffered telemetry */
    flush(): Promise<void>;
    /** Shutdown the collector */
    shutdown(): Promise<void>;
}
/**
 * Configuration for the telemetry manager.
 */
export interface TelemetryConfig {
    /** Enable/disable telemetry collection */
    enabled?: boolean;
    /** Service name for identification */
    serviceName?: string;
    /** Service version */
    serviceVersion?: string;
    /** Default shard ID */
    shardId?: string;
    /** Sampling configuration */
    sampling?: TelemetrySamplingConfig;
    /** Collectors to send telemetry to */
    collectors?: TelemetryCollector[];
    /** Maximum events to buffer before flush */
    bufferSize?: number;
    /** Flush interval in milliseconds */
    flushInterval?: number;
    /** Enable debug mode (logs all telemetry) */
    debug?: boolean;
}
/**
 * Telemetry manager interface.
 */
export interface TelemetryManager {
    /** Check if telemetry is enabled */
    isEnabled(): boolean;
    /** Set enabled state */
    setEnabled(enabled: boolean): void;
    /** Start a new span */
    startSpan(name: string, options?: StartSpanOptions): ActiveSpan;
    /** Get the current active span (if any) */
    getCurrentSpan(): ActiveSpan | undefined;
    /** Run a function within a span */
    withSpan<T>(name: string, fn: (span: ActiveSpan) => T, options?: StartSpanOptions): T;
    /** Run an async function within a span */
    withSpanAsync<T>(name: string, fn: (span: ActiveSpan) => Promise<T>, options?: StartSpanOptions): Promise<T>;
    /** Record a telemetry event */
    recordEvent(event: Omit<TelemetryEvent, 'eventId' | 'timestamp'>): void;
    /** Record a query event */
    recordQueryEvent(event: Omit<QueryTelemetryEvent, 'eventId' | 'timestamp' | 'category'>): void;
    /** Record a write event */
    recordWriteEvent(event: Omit<WriteTelemetryEvent, 'eventId' | 'timestamp' | 'category'>): void;
    /** Record an error event */
    recordErrorEvent(event: Omit<ErrorTelemetryEvent, 'eventId' | 'timestamp' | 'category'>): void;
    /** Record a performance event */
    recordPerformanceEvent(event: Omit<PerformanceTelemetryEvent, 'eventId' | 'timestamp' | 'category'>): void;
    /** Add a collector */
    addCollector(collector: TelemetryCollector): void;
    /** Remove a collector */
    removeCollector(collector: TelemetryCollector): void;
    /** Flush all pending telemetry */
    flush(): Promise<void>;
    /** Shutdown the telemetry manager */
    shutdown(): Promise<void>;
}
/**
 * Options for starting a new span.
 */
export interface StartSpanOptions {
    /** Span kind */
    kind?: SpanKind;
    /** Initial attributes */
    attributes?: TelemetryAttributes;
    /** Parent span (for manual linking) */
    parent?: ActiveSpan;
    /** Custom trace ID (for distributed tracing) */
    traceId?: string;
}
/**
 * Default telemetry configuration.
 */
export declare const DEFAULT_TELEMETRY_CONFIG: Required<TelemetryConfig>;
/**
 * All telemetry event types.
 */
export declare const TELEMETRY_EVENT_TYPES: readonly TelemetryEventType[];
/**
 * All telemetry event categories.
 */
export declare const TELEMETRY_EVENT_CATEGORIES: readonly TelemetryEventCategory[];
/**
 * In-memory collector for testing and development.
 * Stores all events and spans in memory.
 */
export declare class InMemoryTelemetryCollector implements TelemetryCollector {
    private events;
    private spans;
    collectEvent(event: TelemetryEvent): void;
    collectSpan(span: TelemetrySpan): void;
    flush(): Promise<void>;
    shutdown(): Promise<void>;
    /** Get all collected events */
    getEvents(): TelemetryEvent[];
    /** Get all collected spans */
    getSpans(): TelemetrySpan[];
    /** Get events by type */
    getEventsByType(type: TelemetryEventType): TelemetryEvent[];
    /** Get events by category */
    getEventsByCategory(category: TelemetryEventCategory): TelemetryEvent[];
    /** Get spans by name */
    getSpansByName(name: string): TelemetrySpan[];
    /** Clear all collected data */
    clear(): void;
}
/**
 * Creates a new telemetry manager.
 */
export declare function createTelemetryManager(config?: TelemetryConfig): TelemetryManager;
/**
 * Creates a no-op telemetry manager (for when telemetry is disabled).
 */
export declare function createNoopTelemetryManager(): TelemetryManager;
/**
 * Creates an in-memory collector for testing.
 */
export declare function createInMemoryCollector(): InMemoryTelemetryCollector;
/**
 * Type guard for telemetry event categories.
 */
export declare function isTelemetryEventCategory(value: unknown): value is TelemetryEventCategory;
/**
 * Type guard for telemetry event types.
 */
export declare function isTelemetryEventType(value: unknown): value is TelemetryEventType;
/**
 * Type guard for telemetry events.
 */
export declare function isTelemetryEvent(value: unknown): value is TelemetryEvent;
/**
 * Type guard for telemetry spans.
 */
export declare function isTelemetrySpan(value: unknown): value is TelemetrySpan;
/**
 * Type guard for query telemetry events.
 */
export declare function isQueryTelemetryEvent(event: TelemetryEvent): event is QueryTelemetryEvent;
/**
 * Type guard for write telemetry events.
 */
export declare function isWriteTelemetryEvent(event: TelemetryEvent): event is WriteTelemetryEvent;
/**
 * Type guard for error telemetry events.
 */
export declare function isErrorTelemetryEvent(event: TelemetryEvent): event is ErrorTelemetryEvent;
/**
 * Type guard for performance telemetry events.
 */
export declare function isPerformanceTelemetryEvent(event: TelemetryEvent): event is PerformanceTelemetryEvent;
//# sourceMappingURL=telemetry.d.ts.map