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

Cloud Spanner Client Library for Node.js

import { MeterProvider, MetricReader } from '@opentelemetry/sdk-metrics';
import { Counter, Histogram } from '@opentelemetry/api';
import { MetricsTracer } from './metrics-tracer';
/**
 * Factory class for creating and managing MetricsTracer instances and OTEL metric instruments.
 *
 * The MetricsTracerFactory is responsible for:
 * - Creating and managing a singleton instance for metrics collection.
 * - Initializing and providing OTEL MeterProvider.
 * - Generating and storing client-specific metadata (UID, hash, name, location, projectId).
 * - Creating and tracking MetricsTracer instances for individual gRPC Spanner operations.
 * - Providing utility methods for extracting resource attributes and managing tracers.
 *
 * This class is designed to be used as a singleton. Metrics collection can be enabled or disabled
 * globally via the static `enabled` property, that is set from the SpannerClient.
 */
export declare class MetricsTracerFactory {
    private static _instance;
    private _meterProvider;
    private _instrumentAttemptCounter;
    private _instrumentAttemptLatency;
    private _instrumentOperationCounter;
    private _instrumentOperationLatency;
    private _instrumentGfeConnectivityErrorCount;
    private _instrumentGfeLatency;
    private _instrumentAfeConnectivityErrorCount;
    private _instrumentAfeLatency;
    private _clientHash;
    private _clientName;
    private _clientUid;
    private _location;
    private _projectId;
    private _currentOperationTracers;
    private _currentOperationLastUpdatedMs;
    private _intervalTracerCleanup;
    static enabled: boolean;
    /**
     * Private constructor to enforce singleton pattern.
     * Initializes client metadata and detects client location if metrics are enabled.
     * Location will default to global if host machine is not a GCE or GKE instance.
     * @param projectId The GCP project ID used by the Spanner Client.
     */
    private constructor();
    /**
     * Returns the singleton instance of MetricsTracerFactory.
     * If metrics are disabled, returns null.
     * The instance is created only once, and enabling/disabling metrics can only be done on the initial call.
     * @param projectId Optional GCP project ID for the factory instantiation. Does nothing for subsequent calls.
     * @returns The singleton MetricsTracerFactory instance or null if disabled.
     */
    static getInstance(projectId: string): MetricsTracerFactory | null;
    /**
     * Returns the MeterProvider, creating it and metric instruments if not already initialized.
     * Client-wide attributes that are known at this time are cached to be provided to all MetricsTracers.
     * @param readers Optional array of MetricReader instances to attach to the MeterProvider.
     * @returns The OTEL MeterProvider instance.
     */
    getMeterProvider(readers?: MetricReader[]): MeterProvider;
    /**
     * Resets the singleton instance of the MetricsTracerFactory.
     */
    static resetInstance(projectId?: string): Promise<void>;
    /**
     * Resets the MeterProvider.
     */
    resetMeterProvider(): Promise<void>;
    /**
     * Returns the attempt latency histogram instrument.
     */
    get instrumentAttemptLatency(): Histogram;
    /**
     * Returns the attempt counter instrument.
     */
    get instrumentAttemptCounter(): Counter;
    /**
     * Returns the operation latency histogram instrument.
     */
    get instrumentOperationLatency(): Histogram;
    /**
     * Returns the operation counter instrument.
     */
    get instrumentOperationCounter(): Counter;
    /**
     * Returns the GFE connectivity error count counter instrument.
     */
    get instrumentGfeConnectivityErrorCount(): Counter;
    /**
     * Returns the GFE latency histogram instrument.
     */
    get instrumentGfeLatency(): Histogram;
    /**
     * Returns the Client UID.
     */
    get clientUid(): string;
    /**
     * Returns the Client Name.
     */
    get clientName(): string;
    /**
     * Creates a new MetricsTracer for a given resource name and method, and stores it for later retrieval.
     * Returns null if metrics are disabled.
     * @param formattedName The formatted resource name (e.g., full database path).
     * @param method The gRPC method name.
     * @returns A new MetricsTracer instance or null if metrics are disabled.
     */
    createMetricsTracer(method: string, formattedName: string, requestId: string): MetricsTracer | null;
    /**
     * Takes a formatted name and parses the project, instance, and database.
     * @param formattedName The formatted resource name (e.g., full database path).
     * @returns An object containing project, instance, and database strings.
     */
    getInstanceAttributes(formattedName: string): {
        project: string;
        instance: string;
        database: string;
    };
    /**
     * Retrieves the current MetricsTracer for a given request id.
     * Returns null if no tracer exists for the request.
     * Does not implicitly create MetricsTracers as that should be done
     * explicitly using the createMetricsTracer function.
     * request id is expected to be as set in the gRPC metadata.
     * @param requestId The request id of the gRPC call set under 'x-goog-spanner-request-id'.
     * @returns The MetricsTracer instance or null if not found.
     */
    getCurrentTracer(requestId: string): MetricsTracer | null;
    /**
     * Removes the MetricsTracer associated with the given request id.
     * @param requestId The request id of the gRPC call set under 'x-goog-spanner-request-id'.
     */
    clearCurrentTracer(requestId: string): void;
    private _extractOperationRequest;
    /**
     * Creates and initializes all metric instruments (counters and histograms) for the MeterProvider.
     * Instruments are only created if metrics are enabled.
     */
    private _createMetricInstruments;
    /**
     * Generates a unique identifier for the client_uid metric field. The identifier is composed of a
     * UUID, the process ID (PID), and the hostname.
     * @returns A unique string identifier for the client.
     */
    private static _generateClientUId;
    /**
     * Generates a 6-digit zero-padded lowercase hexadecimal hash using the 10 most significant bits
     * of a 64-bit hash value.
     *
     * The primary purpose of this function is to generate a hash value for the `client_hash`
     * resource label using `client_uid` metric field. The range of values is chosen to be small
     * enough to keep the cardinality of the Resource targets under control. Note: If at later time
     * the range needs to be increased, it can be done by increasing the value of `kPrefixLength` to
     * up to 24 bits without changing the format of the returned value.
     * @param clientUid The client UID string to hash.
     * @returns A 6-digit hexadecimal hash string.
     */
    private static _generateClientHash;
    /**
     * Gets the location (region) of the client, otherwise returns to the "global" region.
     * Uses GcpDetectorSync to detect the region from the environment.
     * @returns The detected region string, or "global" if not found.
     */
    private static _detectClientLocation;
    private _cleanMetricsTracers;
}