couchbase 4.6.1 → 4.7.0

package/dist/thresholdlogging.d.ts

@@ -0,0 +1,301 @@
+import { HiResTime } from './binding';
+import { TracingConfig } from './cluster';
+import { ServiceType } from './generaltypes';
+import { CouchbaseLogger } from './logger';
+import { AttributeValue, SpanStatus, TimeInput } from './observabilitytypes';
+import { RequestSpan, RequestTracer } from './tracing';
+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 _serviceThresholds: Map<ServiceType, number>;
+    readonly _reporter: ThresholdLoggingReporter;
+    /**
+     * Creates a new threshold logging tracer.
+     *
+     * @param logger - The logger to be used by the ThresholdLoggingReporter.
+     * @param config - Tracing configuration with thresholds and reporting settings.
+     *                 If null, default values are used for all settings.
+     */
+    constructor(logger: CouchbaseLogger, config: TracingConfig | null);
+    /**
+     * Gets the tracer's ThresholdLoggingReporter.
+     *
+     * @internal
+     */
+    get reporter(): ThresholdLoggingReporter;
+    /**
+     * 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 * 1000).
+     *
+     * @internal
+     */
+    _getServiceTypeThreshold(serviceType: ServiceType): number;
+}
+export {};