@google-cloud/spanner/build/src/metrics/metrics-tracer.d.ts

Cloud Spanner Client Library for Node.js

import { status as Status } from '@grpc/grpc-js';
import { Counter, Histogram } from '@opentelemetry/api';
/**
 * MetricAttemptTracer tracks the start time and status of a single gRPC attempt.
 *
 * This class is used to record the timestamp when an attempt begins and to store
 * the status code of the attempt upon completion. It is to be used
 * by MetricsTracer to monitor and report metrics for each individual gRPC call attempt.
 */
declare class MetricAttemptTracer {
    private _startTime;
    status: string;
    constructor();
    /**
     * Returns the start time of the attempt.
     */
    get startTime(): Date;
}
/**
 * MetricOperationTracer tracks the lifecycle and metadata of a single gRPC spanner operation,
 * which may consist of multiple attempts.
 *
 * This class is responsible for:
 * - Recording the start time of the operation.
 * - Tracking the number of attempts made for the operation.
 * - Holding a reference to the current attempt's tracer (MetricAttemptTracer).
 * - Storing the final status code of the operation.
 *
 * Usage:
 * - Call `start()` to reset the operation's start time.
 * - Call `createNewAttempt()` to begin tracking a new attempt within the operation.
 * - Access `currentAttempt` to retrieve the current MetricAttemptTracer instance.
 * - Access `attemptCount` to get the number of attempts made so far.
 * - Access `startTime` to get the operation's start time.
 * - Set or read `status` to track the operation's final status code.
 */
declare class MetricOperationTracer {
    private _attemptCount;
    private _startTime;
    private _currentAttempt;
    constructor();
    /**
     * Returns the number of attempts made for this operation.
     */
    get attemptCount(): number;
    /**
     * Returns the current MetricAttemptTracer instance for the ongoing attempt.
     */
    get currentAttempt(): MetricAttemptTracer | null;
    /**
     * Returns the start time of the operation.
     */
    get startTime(): Date;
    /**
     * Increments the attempt count and creates a new MetricAttemptTracer
     * for tracking the next attempt within this operation.
     */
    createNewAttempt(): void;
}
/**
 * MetricsTracer is responsible for recording and managing metrics related to
 * gRPC Spanner operations and attempts counters, and latencies,
 * as well as Google Front End (GFE)/AFE metrics such as latency and connectivity errors.
 *
 * This class provides methods to record the start and completion of operations
 * and attempts, extract GFE/AFE latency from response headers.
 * It also handles setting of required Spanner metric attributes to
 * be later consumed by the SpannerMetricsExporter.
 */
export declare class MetricsTracer {
    private _instrumentAttemptCounter;
    private _instrumentAttemptLatency;
    private _instrumentOperationCounter;
    private _instrumentOperationLatency;
    private _instrumentGfeConnectivityErrorCount;
    private _instrumentGfeLatency;
    private _instrumentAfeConnectivityErrorCount;
    private _instrumentAfeLatency;
    enabled: boolean;
    private _database;
    private _instance;
    private _projectId;
    private _methodName;
    private _request;
    /**
     * The current MetricOperationTracer instance tracking the ongoing operation.
     */
    currentOperation: MetricOperationTracer | null;
    /**
     * Stores client and resource attributes for labeling metrics.
     */
    private _clientAttributes;
    gfeLatency: number | null;
    afeLatency: number | null;
    /**
     * Constructs a new MetricsTracer.
     *
     * @param _instrumentAttemptCounter Counter for attempt count metrics.
     * @param _instrumentAttemptLatency Histogram for attempt latency metrics.
     * @param _instrumentOperationCounter Counter for operation count metrics.
     * @param _instrumentOperationLatency Histogram for operation latency metrics.
     * @param _instrumentGfeConnectivityErrorCount Counter for GFE connectivity errors.
     * @param _instrumentGfeLatency Histogram for GFE latency metrics.
     * @param _instrumentAfeConnectivityErrorCount Counter for AFE connectivity errors.
     * @param _instrumentAfeLatency Histogram for AFE latency metrics.
     * @param enabled Whether metrics recording is enabled.
     */
    constructor(_instrumentAttemptCounter: Counter | null, _instrumentAttemptLatency: Histogram | null, _instrumentOperationCounter: Counter | null, _instrumentOperationLatency: Histogram | null, _instrumentGfeConnectivityErrorCount: Counter | null, _instrumentGfeLatency: Histogram | null, _instrumentAfeConnectivityErrorCount: Counter | null, _instrumentAfeLatency: Histogram | null, enabled: boolean, _database: string, _instance: string, _projectId: string, _methodName: string, _request: string);
    /**
     * Returns the difference in milliseconds between two Date objects.
     * @param start The start time.
     * @param end The end time.
     * @returns The time difference in milliseconds.
     */
    private _getMillisecondTimeDifference;
    /**
     * Gets the current client and resource attributes for metrics.
     */
    get clientAttributes(): {
        [key: string]: string;
    };
    /**
     * Gets the attempt counter OTEL instrument.
     */
    get instrumentAttemptCounter(): Counter<import("@opentelemetry/api").Attributes> | null;
    /**
     * Gets the attempt latency histogram OTEL instrument.
     */
    get instrumentAttemptLatency(): Histogram<import("@opentelemetry/api").Attributes> | null;
    /**
     * Gets the operation counter OTEL instrument.
     */
    get instrumentOperationCounter(): Counter<import("@opentelemetry/api").Attributes> | null;
    /**
     * Gets the operation latency histogram OTEL instrument.
     */
    get instrumentOperationLatency(): Histogram<import("@opentelemetry/api").Attributes> | null;
    /**
     * Records the start of a new attempt within the current operation.
     * Increments the attempt count and creates a new MetricAttemptTracer.
     */
    recordAttemptStart(): void;
    /**
     * Records the completion of the current attempt, including its status and latency.
     * These statuses code are defined in grpc.status
     * @param status The status code of the attempt (default: Status.OK).
     */
    recordAttemptCompletion(statusCode?: Status): void;
    /**
     * Records the start of a new operation, resetting the operation tracer and start time.
     */
    recordOperationStart(): void;
    /**
     * Records the completion of the current operation, including its status,
     * latency, and attempt count. Also clears the current tracer from the factory.
     */
    recordOperationCompletion(): void;
    /**
     * Extracts the GFE latency value (in milliseconds) from a 'server-timing' header string.
     * Returns null if the header is missing or does not contain a valid latency value.
     *
     * @param header The 'server-timing' header string.
     * @returns The extracted GFE latency in milliseconds, or null if not found.
     */
    extractGfeLatency(header: string): number | null;
    /**
     * Extracts the AFE latency value (in milliseconds) from a 'server-timing' header string.
     * Returns null if the header is missing or does not contain a valid latency value.
     *
     * @param header The 'server-timing' header string.
     * @returns The extracted AFE latency in milliseconds, or null if not found.
     */
    extractAfeLatency(header: string): number | null;
    /**
     * Records the provided GFE latency.
     * @param latency The GFE latency in milliseconds.
     */
    recordGfeLatency(statusCode: Status): void;
    /**
     * Increments the GFE connectivity error count metric.
     */
    recordGfeConnectivityErrorCount(statusCode: Status): void;
    /**
     * Increments the AFE connectivity error count metric.
     */
    recordAfeConnectivityErrorCount(statusCode: Status): void;
    /**
     * Records the provided AFE latency.
     * @param latency The AFE latency in milliseconds.
     */
    recordAfeLatency(statusCode: Status): void;
    /**
     * Creates and returns a set of OTEL attributes for operation-level metrics.
     * @returns The operation attributes object.
     */
    private _createOperationOtelAttributes;
    /**
     * Creates and returns a set of OTEL attributes for attempt-level metrics.
     * The overall operation status is set at this time based on the last
     * attempt's status.
     * @returns The attempt attributes object.
     */
    private _createAttemptOtelAttributes;
}
export {};