/// <reference types="node" resolution-mode="require"/>
import { inspect } from 'util';
import { HiResTime } from './binding.js';
import { ServiceType } from './generaltypes.js';
import { CouchbaseLogger } from './logger.js';
import { AttributeValue, SpanStatus, TimeInput } from './observabilitytypes.js';
import { RequestSpan, RequestTracer } from './tracing.js';
/**
 * Options for the {@link ThresholdLoggingTracer} — the default tracer.
 *
 * The cluster's `tracingConfig` is typed after these options (it extends them with
 * the cluster-level `enableTracing` flag), so `tracingConfig` configures the default
 * tracer and only that.
 *
 * @category Observability
 */
export interface ThresholdLoggingOptions {
    /**
     * Specifies the interval after which the aggregated trace information is
     * logged, specified in milliseconds (10 seconds).
     *
     * @default 10_000
     */
    emitInterval?: number;
    /**
     * Specifies how many entries to sample per service in each emit interval
     * (the slowest requests are kept).
     *
     * @default 10
     */
    sampleSize?: number;
    /**
     * Threshold over which the request is taken into account for the KV service,
     * specified in milliseconds.
     *
     * @default 500
     */
    kvThreshold?: number;
    /**
     * Threshold over which the request is taken into account for the query
     * service, specified in milliseconds.
     *
     * @default 1_000
     */
    queryThreshold?: number;
    /**
     * Threshold over which the request is taken into account for the search
     * service, specified in milliseconds.
     *
     * @default 1_000
     */
    searchThreshold?: number;
    /**
     * Threshold over which the request is taken into account for the analytics
     * service, specified in milliseconds.
     *
     * @default 1_000
     */
    analyticsThreshold?: number;
    /**
     * Threshold over which the request is taken into account for management
     * operations, specified in milliseconds.
     *
     * @default 1_000
     */
    managementThreshold?: number;
    /**
     * Threshold over which the request is taken into account for eventing
     * service, specified in milliseconds.
     *
     * @default 1_000
     */
    eventingThreshold?: number;
    /**
     * Threshold over which the request is taken into account for the views
     * service, specified in milliseconds.
     *
     * @default 1_000
     */
    viewsThreshold?: number;
    /**
     * When enabled, records the document key (`couchbase.document.id`) on KV spans,
     * the query parameter values (`db.query.parameter.<key>`) on query/analytics
     * spans, and the `mutateIn` mutation values (`couchbase.subdoc.values`) on KV
     * spans. The `mutateIn` values additionally require
     * {@link ThresholdLoggingOptions.recordSubDocSpecs} — without the paths there is
     * nothing to attach a value to, so they are omitted.
     *
     * These values are frequently sensitive (PII / document content) and may be
     * exported to whichever tracing backend is configured, so capture is opt-in.
     *
     * @default false
     */
    recordRequestArguments?: boolean;
    /**
     * When enabled, records the sub-document paths of `lookupIn` / `mutateIn`
     * operations (`couchbase.subdoc.specs`) on KV spans, so a trace shows which
     * fields the operation targeted.
     *
     * This flag records the field paths. The `mutateIn` values are gated
     * additionally on {@link ThresholdLoggingOptions.recordRequestArguments}, and
     * when both are on they are recorded as `couchbase.subdoc.values`. Paths alone
     * can still reveal the document schema, so capture is opt-in.
     *
     * @default false
     */
    recordSubDocSpecs?: boolean;
}
declare class ThresholdLoggingSpanSnapshot {
    readonly name: string;
    readonly serviceType: ServiceType | undefined;
    readonly totalDuration: number;
    readonly encodeDuration: number | undefined;
    readonly dispatchDuration: number | undefined;
    readonly totalDispatchDuration: number;
    readonly serverDuration: number | undefined;
    readonly totalServerDuration: number;
    readonly localId: string | undefined;
    readonly operationId: string | undefined;
    readonly localSocket: string | undefined;
    readonly remoteSocket: string | undefined;
    constructor(span: ThresholdLoggingSpan);
}
/**
 * @internal
 */
declare class ThresholdLoggingReporter {
    private readonly _interval;
    private readonly _thresholdQueues;
    private readonly _logger;
    private _timerId;
    private _stopped;
    constructor(logger: CouchbaseLogger, interval: number, capacity?: number);
    addLogRecord(serviceType: ServiceType, item: ThresholdLogRecord, totalDuration: number): void;
    start(): void;
    stop(): void;
    report(returnReport?: boolean): Record<string, any> | undefined;
}
/**
 * @internal
 */
type ThresholdLogRecord = Map<string, string | number>;
/**
 * A RequestSpan implementation that tracks operation timing for threshold logging.
 *
 * Works with {@link ThresholdLoggingTracer} to identify and log slow operations
 * that exceed configured thresholds.
 *
 */
export declare class ThresholdLoggingSpan implements RequestSpan {
    readonly _name: string;
    readonly _tracer: ThresholdLoggingTracer;
    _parentSpan: ThresholdLoggingSpan | undefined;
    _startTime: HiResTime;
    _endTime: HiResTime | undefined;
    _attributes: {
        [key: string]: AttributeValue;
    };
    _status: SpanStatus;
    _totalDuration: number;
    _serverDuration: number | undefined;
    _totalServerDuration: number;
    _dispatchDuration: number | undefined;
    _totalDispatchDuration: number;
    _encodeDuration: number | undefined;
    _totalEncodeDuration: number;
    _localId: string | undefined;
    _operationId: string | undefined;
    _peerAddress: string | undefined;
    _peerPort: number | undefined;
    _remoteAddress: string | undefined;
    _remotePort: number | undefined;
    _serviceType: ServiceType | undefined;
    _snapshot: ThresholdLoggingSpanSnapshot | undefined;
    /**
     * Creates a new threshold logging span.
     *
     * @param name - The name of the operation being traced.
     * @param tracer - The span's tracer.
     * @param parentSpan - Optional parent span for hierarchical tracing.
     * @param startTime - Optional start time; defaults to current time if not provided.
     */
    constructor(name: string, tracer: ThresholdLoggingTracer, parentSpan?: ThresholdLoggingSpan, startTime?: TimeInput);
    /**
     * Gets the dispatch duration of the request, in microseconds.
     *
     * @internal
     */
    get dispatchDuration(): number | undefined;
    /**
     * Sets the dispatch duration of the request, in microseconds.
     *
     * @internal
     */
    set dispatchDuration(duration: number);
    /**
     * Gets the duration spent encoding the request, in microseconds.
     *
     * @internal
     */
    get encodeDuration(): number | undefined;
    /**
     * Sets the duration spent encoding the request, in microseconds.
     *
     * @internal
     */
    set encodeDuration(duration: number);
    /**
     * Gets the local ID of the request's dispatch span.
     *
     * @internal
     */
    get localId(): string | undefined;
    /**
     * Gets the local socket of the request's dispatch span.
     *
     * @internal
     */
    get localSocket(): string | undefined;
    /**
     * Gets the name of the span.
     */
    get name(): string;
    /**
     * Gets the operation ID of the request's dispatch span.
     *
     * @internal
     */
    get operationId(): string | undefined;
    /**
     * Gets the peer address of the request's dispatch span.
     *
     * @internal
     */
    get peerAddress(): string | undefined;
    /**
     * Gets the peer port of the request's dispatch span.
     *
     * @internal
     */
    get peerPort(): number | undefined;
    /**
     * Gets the remote socket of the request's dispatch span.
     *
     * @internal
     */
    get remoteSocket(): string | undefined;
    /**
     * Gets the server duration of the request, in microseconds.
     *
     * @internal
     */
    get serverDuration(): number | undefined;
    /**
     * Gets the Couchbase service type handling this operation.
     *
     * @internal
     */
    get serviceType(): ServiceType | undefined;
    /**
     * Gets the snapshot of the span containing all relevant information for threshold logging.
     *
     * @internal
     */
    get snapshot(): ThresholdLoggingSpanSnapshot | undefined;
    /**
     * Gets the total dispatch duration of the request, in microseconds.
     *
     * @internal
     */
    get totalDispatchDuration(): number;
    /**
     * Gets the total encoding duration of the request, in microseconds.
     *
     * @internal
     */
    get totalEncodeDuration(): number;
    /**
     * Gets the total duration of the request, in microseconds.
     *
     * @internal
     */
    get totalDuration(): number;
    /**
     * Gets the total server duration of the request, in microseconds.
     *
     * @internal
     */
    get totalServerDuration(): number;
    /**
     * Sets a single attribute on the span.
     *
     * @param key - The attribute key.
     * @param value - The attribute value.
     */
    setAttribute(key: string, value: AttributeValue): void;
    /**
     * Adds a timestamped event to the span.
     */
    addEvent(): void;
    /**
     * Sets the status of the span.
     *
     * @param status - The span status containing code and optional message.
     */
    setStatus(status: SpanStatus): void;
    /**
     * Marks the span as complete and calculates the total duration.
     *
     * The total duration is computed from the start time to the end time
     * and stored in microseconds.
     *
     * @param endTime - Optional end time; defaults to current time if not provided.
     */
    end(endTime?: TimeInput): void;
    /**
     * Converts various time input formats to HiResTime.
     *
     * @param input - Time input (Date, number, HiResTime, or undefined for current time).
     * @returns {HiResTime} High-resolution time value.
     */
    private _getTime;
}
/**
 * A RequestTracer implementation that identifies and logs slow operations.
 */
export declare class ThresholdLoggingTracer implements RequestTracer {
    readonly _emitInterval: number;
    readonly _sampleSize: number;
    readonly _recordRequestArguments: boolean;
    readonly _recordSubDocSpecs: boolean;
    readonly _serviceThresholds: Map<ServiceType, number>;
    readonly _reporter: ThresholdLoggingReporter;
    /**
     * Creates a new threshold logging tracer.
     *
     * @param logger - The logger used by the reporter; falls back to
     *                 {@link createDefaultLogger} when omitted.
     * @param config - Tracing configuration; see {@link ThresholdLoggingOptions} for
     *                 the per-field defaults applied when a value is omitted.
     */
    constructor(logger?: CouchbaseLogger, config?: ThresholdLoggingOptions | null);
    /**
     * Gets the tracer's ThresholdLoggingReporter.
     *
     * @internal
     */
    get reporter(): ThresholdLoggingReporter;
    /**
     * Whether request arguments (KV document keys, query parameter values) are
     * recorded as span attributes.
     *
     * @see ThresholdLoggingOptions.recordRequestArguments
     */
    get recordRequestArguments(): boolean;
    /**
     * Whether sub-document paths (`couchbase.subdoc.specs`) are recorded on KV
     * spans.
     *
     * @see ThresholdLoggingOptions.recordSubDocSpecs
     */
    get recordSubDocSpecs(): boolean;
    /**
     * @internal
     */
    [inspect.custom](): Record<string, any>;
    /**
     * @internal
     */
    toJSON(): Record<string, any>;
    /**
     * Exposes only the tracer's configuration. The reporter is deliberately
     * omitted: it holds a periodic-flush timer handle (`setInterval`), a circular
     * structure that breaks `JSON.stringify` and produces noisy `util.inspect`
     * output. Custom tracers should do the same — see the observability guide.
     *
     * @internal
     */
    private _toConfigSnapshot;
    /**
     * Gets the tracer's service thresholds.
     *
     * @internal
     */
    get serviceThresholds(): Map<ServiceType, number>;
    /**
     * Stops the threshold logging reporter and cleans up resources.
     *
     * This method should be called when shutting down the application or when
     * the tracer is no longer needed to ensure the periodic reporting timer
     * is properly cleared.
     */
    cleanup(): void;
    /**
     * Creates a new threshold logging span to trace an operation.
     *
     * @param name - The name of the operation being traced.
     * @param parentSpan - Optional parent span for hierarchical tracing.
     * @param startTime - Optional start time; defaults to current time if not provided.
     * @returns {ThresholdLoggingSpan} A new ThresholdLoggingSpan instance.
     */
    requestSpan(name: string, parentSpan?: ThresholdLoggingSpan, startTime?: TimeInput): RequestSpan;
    /**
     * Checks if an operation exceeded its threshold and collects diagnostic information.
     *
     * If the operation's duration exceeds the configured threshold for its service type,
     * detailed timing and connection information is extracted from the span and its
     * associated core spans (network dispatch spans) and added to the reporter's queue.
     *
     * @param span - The completed threshold logging span to check.
     * @param coreSpans - Optional array of low-level network dispatch spans containing.
     *                    detailed timing and connection information.
     *
     * @internal
     */
    checkThreshold(spanSnapshot: ThresholdLoggingSpanSnapshot): void;
    /**
     * Converts the request span and all child spans into single ThresholdLogRecord.
     *
     * @param requestSpan - The request span.
     * @param spanTotalDuration - The request spans duration.
     * @returns {ThresholdLogRecord} The converted spans to a single ThresholdLogRecord.
     *
     * @internal
     */
    _buildThresholdLogRecord(spanSnapshot: ThresholdLoggingSpanSnapshot, spanTotalDuration: number): ThresholdLogRecord;
    /**
     * Gets the configured threshold for a specific service type.
     *
     * @param serviceType - The Couchbase service type.
     * @returns The threshold in microseconds (millisecond config value * 1_000).
     *
     * @internal
     */
    _getServiceTypeThreshold(serviceType: ServiceType): number | undefined;
}
export {};