couchbase 4.6.1 → 4.7.0-dev.1

package/dist/loggingmeter.js

@@ -0,0 +1,226 @@
+"use strict";
+/**
+ * @internal
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LoggingMeter = void 0;
+const hdr = __importStar(require("hdr-histogram-js"));
+const errors_1 = require("./errors");
+const observabilitytypes_1 = require("./observabilitytypes");
+/**
+ * Internal class for recording metric values using HDR histograms.
+ *
+ * @internal
+ */
+class LoggingValueRecorder {
+    constructor() {
+        this._percentiles = [50.0, 90.0, 99.0, 99.9, 100.0];
+        this._histogram = hdr.build({
+            lowestDiscernibleValue: 1, // 1 microsecond
+            highestTrackableValue: 30000000, // 30 seconds
+            numberOfSignificantValueDigits: 3,
+        });
+    }
+    /**
+     * Records a metric value.
+     *
+     * @param value - The value to record (typically latency in microseconds).
+     */
+    recordValue(value) {
+        this._histogram.recordValue(value);
+    }
+    /**
+     * Gets the current percentile values and resets the histogram.
+     *
+     * @returns The percentile report containing total count and percentile values.
+     */
+    getPercentilesAndReset() {
+        const mappedPercentiles = {};
+        for (const p of this._percentiles) {
+            mappedPercentiles[p.toString()] = this._histogram.getValueAtPercentile(p);
+        }
+        const result = {
+            total_count: this._histogram.totalCount,
+            percentiles_us: mappedPercentiles,
+        };
+        this._histogram.reset();
+        return result;
+    }
+}
+/**
+ * Internal class for periodically emitting meter reports.
+ *
+ * @internal
+ */
+class LoggingMeterReporter {
+    constructor(loggingMeter, emitInterval, logger) {
+        this._loggingMeter = loggingMeter;
+        this._emitInterval = emitInterval;
+        this._logger = logger;
+        this._stopped = false;
+    }
+    /**
+     * @internal
+     */
+    start() {
+        this._timerId = setInterval(this.report.bind(this), this._emitInterval);
+        // let the process exit even if the reporter has not been shutdown
+        this._timerId.unref();
+        this._stopped = false;
+    }
+    /**
+     * @internal
+     */
+    stop() {
+        if (this._stopped) {
+            return;
+        }
+        this._stopped = true;
+        clearInterval(this._timerId);
+    }
+    /**
+     * @internal
+     */
+    report() {
+        const report = this._loggingMeter.createReport();
+        if (report) {
+            this._logger.info(JSON.stringify(report));
+        }
+    }
+    /**
+     * @internal
+     */
+    toJSON() {
+        return {};
+    }
+}
+/**
+ * A logging-based meter implementation that records metrics using HDR histograms
+ * and periodically reports percentile statistics.
+ *
+ * @internal
+ */
+class LoggingMeter {
+    /**
+     * Creates a new LoggingMeter with the specified flush interval.
+     *
+     * @param logger - The logger to be used by the LoggingMeter.
+     * @param emitInterval - The interval in milliseconds between reports (default: 600000ms = 10 minutes).
+     */
+    constructor(logger, emitInterval) {
+        this._recorders = new Map();
+        this._emitInterval = emitInterval !== null && emitInterval !== void 0 ? emitInterval : 600000; // Default to 10 minutes
+        // Initialize recorders map for each service type
+        for (const serviceType of Object.values(observabilitytypes_1.ServiceName)) {
+            this._recorders.set(serviceType, new Map());
+        }
+        this._reporter = new LoggingMeterReporter(this, this._emitInterval, logger);
+        this._reporter.start();
+    }
+    /**
+     * Gets the meter's LoggingMeterReporter.
+     *
+     * @internal
+     */
+    get reporter() {
+        return this._reporter;
+    }
+    /**
+     * Gets or creates a value recorder for the specified metric name and tags.
+     *
+     * @param _name - Unused.
+     * @param tags - Key-value pairs that categorize the metric.
+     * @returns A value recorder for recording values.
+     */
+    valueRecorder(_name, tags) {
+        // The ObservabilityHandler, at least for now, only passes in OpAttributeName.MeterNameOpDuration for the name
+        // for OTel compat. However, for the loging meter we care about the opName.
+        const serviceTag = tags[observabilitytypes_1.OpAttributeName.Service];
+        if (!Object.values(observabilitytypes_1.ServiceName).includes(serviceTag)) {
+            throw new errors_1.MeterError(new Error(`Invalid service type: ${serviceTag}`));
+        }
+        const service = serviceTag;
+        const opMap = this._recorders.get(service);
+        const opName = tags[observabilitytypes_1.OpAttributeName.OperationName];
+        let recorder = opMap.get(opName);
+        if (!recorder) {
+            recorder = new LoggingValueRecorder();
+            opMap.set(opName, recorder);
+        }
+        return recorder;
+    }
+    /**
+     * Creates a report of all recorded metrics and resets the histograms.
+     *
+     * @returns The logging meter report with percentile statistics.
+     */
+    createReport() {
+        const report = {
+            meta: {
+                emit_interval_s: this._emitInterval / 1000,
+            },
+            operations: {},
+        };
+        for (const [serviceType, opMap] of this._recorders.entries()) {
+            const svcReport = {};
+            for (const [opName, recorder] of opMap.entries()) {
+                const percentileReport = recorder.getPercentilesAndReset();
+                if (percentileReport.total_count > 0) {
+                    svcReport[opName] = percentileReport;
+                }
+            }
+            if (Object.keys(svcReport).length > 0) {
+                report.operations[serviceType] = svcReport;
+            }
+        }
+        if (Object.keys(report.operations).length === 0) {
+            return null;
+        }
+        return report;
+    }
+    /**
+     * 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() {
+        try {
+            this._reporter.stop();
+        }
+        catch (_e) {
+            // Don't raise exceptions during shutdown
+        }
+    }
+    /**
+     * @internal
+     */
+    toJSON() {
+        return { emitInterval: this._emitInterval };
+    }
+}
+exports.LoggingMeter = LoggingMeter;

package/dist/metrics.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @internal
+ */
+/**
+ * Abstract interface for recording metric values.
+ *
+ * Implementations should record values that will be aggregated and tracked over time,
+ * typically for latency or performance metrics.
+ */
+export interface ValueRecorder {
+    /**
+     * Records a single value.
+     *
+     * @param value - The value to record (typically latency in microseconds).
+     */
+    recordValue(value: number): void;
+}
+/**
+ * Abstract interface for creating and managing value recorders.
+ *
+ * Implementations should allow creating value recorders with specific names
+ * and tags for organizing and categorizing metrics.
+ */
+export interface Meter {
+    /**
+     * Gets or creates a value recorder with the specified name and tags.
+     *
+     * @param name - The name of the recorder (typically operation name).
+     * @param tags - Key-value pairs that categorize the metric (e.g., service, operation).
+     * @returns {ValueRecorder} A value recorder for recording values.
+     */
+    valueRecorder(name: string, tags: Record<string, any>): ValueRecorder;
+}

package/dist/metrics.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * @internal
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/observability.d.ts

@@ -0,0 +1,60 @@
+import { CppObservableRequests, CppObservableResponse, ObservableBindingFunc } from './binding';
+import { ValueRecorder, Meter } from './metrics';
+import { ObservableRequestHandler } from './observabilityhandler';
+import { RequestSpan, RequestTracer } from './tracing';
+/**
+ * @internal
+ */
+export declare class NoOpSpan implements RequestSpan {
+    /**
+     * @internal
+     */
+    setAttribute(): void;
+    /**
+     * @internal
+     */
+    addEvent(): void;
+    /**
+     * @internal
+     */
+    setStatus(): void;
+    /**
+     * @internal
+     */
+    end(): void;
+    /**
+     * @internal
+     */
+    get name(): string;
+}
+/**
+ * @internal
+ */
+export declare class NoOpTracer implements RequestTracer {
+    /**
+     * @internal
+     */
+    requestSpan(): RequestSpan;
+}
+/**
+ * @internal
+ */
+export declare function wrapObservableBindingCall<TReq extends CppObservableRequests, TResp extends CppObservableResponse>(fn: ObservableBindingFunc<TReq, TResp>, req: TReq, obsReqHandler: ObservableRequestHandler): Promise<[Error | null, TResp]>;
+/**
+ * @internal
+ */
+export declare class NoOpValueRecorder implements ValueRecorder {
+    /**
+     * @internal
+     */
+    recordValue(_value: number): void;
+}
+/**
+ * @internal
+ */
+export declare class NoOpMeter implements Meter {
+    /**
+     * @internal
+     */
+    valueRecorder(_name: string, _tags: Record<string, string>): ValueRecorder;
+}

package/dist/observability.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NoOpMeter = exports.NoOpValueRecorder = exports.wrapObservableBindingCall = exports.NoOpTracer = exports.NoOpSpan = void 0;
+const bindingutilities_1 = require("./bindingutilities");
+/**
+ * @internal
+ */
+class NoOpSpan {
+    /**
+     * @internal
+     */
+    setAttribute() { }
+    /**
+     * @internal
+     */
+    addEvent() { }
+    /**
+     * @internal
+     */
+    setStatus() { }
+    /**
+     * @internal
+     */
+    end() { }
+    /**
+     * @internal
+     */
+    get name() {
+        return '';
+    }
+}
+exports.NoOpSpan = NoOpSpan;
+/**
+ * @internal
+ */
+class NoOpTracer {
+    /**
+     * @internal
+     */
+    requestSpan() {
+        return new NoOpSpan();
+    }
+}
+exports.NoOpTracer = NoOpTracer;
+/**
+ * @internal
+ */
+async function wrapObservableBindingCall(fn, req, obsReqHandler) {
+    return await new Promise((resolve) => {
+        req.wrapper_span_name = obsReqHandler.wrapperSpanName;
+        fn(req, (cppErr, res) => {
+            let err = null;
+            if (cppErr) {
+                err = (0, bindingutilities_1.errorFromCpp)(cppErr);
+                obsReqHandler.processCoreSpan(cppErr.cpp_core_span);
+            }
+            else {
+                obsReqHandler.processCoreSpan(res.cpp_core_span);
+            }
+            resolve([err, res]);
+        });
+    });
+}
+exports.wrapObservableBindingCall = wrapObservableBindingCall;
+/**
+ * @internal
+ */
+class NoOpValueRecorder {
+    /**
+     * @internal
+     */
+    recordValue(_value) { }
+}
+exports.NoOpValueRecorder = NoOpValueRecorder;
+/**
+ * @internal
+ */
+class NoOpMeter {
+    /**
+     * @internal
+     */
+    valueRecorder(_name, _tags) {
+        return new NoOpValueRecorder();
+    }
+}
+exports.NoOpMeter = NoOpMeter;

package/dist/observabilityhandler.d.ts

@@ -0,0 +1,176 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import { CppDocumentId, CppDurabilityLevel, CppWrapperSdkChildSpan, CppWrapperSdkSpan, HiResTime } from './binding';
+import { ObservabilityInstruments } from './observabilitytypes';
+import { AttributeValue, CppOpAttributeName, OpType, OpAttributeName, SpanStatus, ServiceName } from './observabilitytypes';
+import { HttpOpAttributesOptions } from './observabilityutilities';
+import { RequestSpan, RequestTracer } from './tracing';
+/**
+ * @internal
+ */
+export declare class ObservableRequestHandler {
+    private _opType;
+    private _requestHasEnded;
+    private readonly _tracerImpl;
+    private readonly _meterImpl;
+    constructor(opType: OpType, observabilityInstruments: ObservabilityInstruments, parentSpan?: RequestSpan);
+    /**
+     * @internal
+     */
+    get opType(): OpType;
+    /**
+     * @internal
+     */
+    get requestHasEnded(): boolean;
+    /**
+     * @internal
+     */
+    get wrapperSpanName(): string;
+    /**
+     * @internal
+     */
+    get wrappedSpan(): WrappedSpan | undefined;
+    /**
+     * @internal
+     */
+    get clusterName(): string | undefined;
+    /**
+     * @internal
+     */
+    get clusterUUID(): string | undefined;
+    /**
+     * @internal
+     */
+    end(): void;
+    /**
+     * @internal
+     */
+    endWithError(error?: any): void;
+    /**
+     * @internal
+     */
+    maybeAddEncodingSpan(encodeFn: () => [Buffer, number]): [Buffer, number];
+    /**
+     * @internal
+     */
+    maybeCreateEncodingSpan(encodeFn: () => [Buffer, number]): [Buffer, number];
+    /**
+     * @internal
+     */
+    reset(opType: OpType, parentSpan?: RequestSpan, withError?: boolean): void;
+    /**
+     * @internal
+     */
+    processCoreSpan(coreSpan?: CppWrapperSdkSpan): void;
+    /**
+     * @internal
+     */
+    setRequestHttpAttributes(options?: HttpOpAttributesOptions): void;
+    /**
+     * @internal
+     */
+    setRequestKeyValueAttributes(cppDocId: CppDocumentId, durability?: CppDurabilityLevel): void;
+}
+/**
+ * @internal
+ */
+export declare class WrappedSpan implements RequestSpan {
+    private readonly _serviceName;
+    private readonly _opType;
+    private readonly _tracer;
+    private readonly _hasMultipleEncodingSpans;
+    readonly _requestSpan: RequestSpan;
+    private _parentSpan;
+    private _endedEncodingSpans;
+    private _encodingSpan;
+    private _encodingSpans;
+    private _clusterName;
+    private _clusterUUID;
+    private _startTime;
+    private _endTimeWatermark;
+    constructor(serviceName: ServiceName, opType: OpType, tracer: RequestTracer, startTime: HiResTime, parentSpan?: RequestSpan | WrappedSpan);
+    /**
+     * @internal
+     */
+    get clusterName(): string | undefined;
+    /**
+     * @internal
+     */
+    get clusterUUID(): string | undefined;
+    /**
+     * @internal
+     */
+    get name(): string;
+    /**
+     * @internal
+     */
+    get requestSpan(): RequestSpan;
+    /**
+     * @internal
+     */
+    maybeAddEncodingSpan(encodeFn: () => [Buffer, number]): [Buffer, number];
+    /**
+     * @internal
+     */
+    maybeCreateEncodingSpan(encodeFn: () => [Buffer, number]): [Buffer, number];
+    /**
+     * @internal
+     */
+    maybeUpdateEndTimeWatermark(endTime: HiResTime): void;
+    /**
+     * @internal
+     */
+    _setAttributeOnAllSpans(attrName: OpAttributeName, attrValue: AttributeValue, skip_encoding_span?: boolean): void;
+    /**
+     * @internal
+     */
+    _maybeSetAttributeFromCoreSpan(coreSpan: CppWrapperSdkSpan, attrName: CppOpAttributeName | OpAttributeName, skip_encoding_span?: boolean): void;
+    /**
+     * @internal
+     */
+    _buildCoreSpans(coreSpans: CppWrapperSdkChildSpan[], parentSpan?: RequestSpan | WrappedSpan): void;
+    /**
+     * @internal
+     */
+    _buildDispatchCoreSpan(coreSpan: CppWrapperSdkChildSpan, parentSpan?: RequestSpan | WrappedSpan): void;
+    /**
+     * @internal
+     */
+    _buildNonDispatchCoreSpan(coreSpan: CppWrapperSdkChildSpan, parentSpan?: RequestSpan | WrappedSpan): void;
+    /**
+     * @internal
+     */
+    _endEncodingSpans(): void;
+    /**
+     * @internal
+     */
+    processCoreSpan(coreSpan: CppWrapperSdkSpan): void;
+    /**
+     * @internal
+     */
+    setClusterLabels(clusterLabels: Record<string, string | undefined>): void;
+    /**
+     * @internal
+     */
+    setRetryAttribute(retrCount?: number): void;
+    /**
+     * @internal
+     */
+    addEvent(): void;
+    /**
+     * @internal
+     */
+    end(endTime: HiResTime): void;
+    /**
+     * @internal
+     */
+    setAttribute(key: string, value: AttributeValue): void;
+    /**
+     * @internal
+     */
+    setStatus(status: SpanStatus): void;
+    /**
+     * @internal
+     */
+    _createRequestSpan(spanName: string, startTime: HiResTime, parentSpan?: RequestSpan): RequestSpan;
+}