@valkey/valkey-glide
Version:
General Language Independent Driver for the Enterprise (GLIDE) for Valkey
190 lines (189 loc) • 8.89 kB
TypeScript
/**
* Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
*/
import { OpenTelemetryConfig } from ".";
/**
* Extended OpenTelemetry configuration that includes JS-side options
* not representable in the native (NAPI) config.
*
* Pass this to {@link OpenTelemetry.init} instead of the plain `OpenTelemetryConfig`.
*/
export interface GlideOpenTelemetryConfig extends OpenTelemetryConfig {
/**
* Optional callback that returns the active parent span context for each command.
*
* When a {@link GlideSpanContext} is returned, the GLIDE command span will be created
* as a child of that context, enabling end-to-end distributed tracing.
*
* The callback is invoked synchronously before each sampled command. Keep the
* implementation lightweight — avoid I/O, async work, or expensive computation.
*
* @example
* ```typescript
* import { trace } from "@opentelemetry/api";
*
* OpenTelemetry.init({
* traces: { endpoint: "http://localhost:4318/v1/traces" },
* parentSpanContextProvider: () => {
* const span = trace.getActiveSpan();
* if (!span) return undefined;
* const ctx = span.spanContext();
* return {
* traceId: ctx.traceId,
* spanId: ctx.spanId,
* traceFlags: ctx.traceFlags,
* traceState: ctx.traceState?.toString(),
* };
* },
* });
* ```
*/
parentSpanContextProvider?: () => GlideSpanContext | undefined;
}
/**
* Represents the trace context of a remote span, used for parent span context propagation.
*
* When a user's application has an active OTel span (e.g., from an HTTP request handler),
* this context allows GLIDE command spans to appear as children of that span in tracing UIs.
*/
export interface GlideSpanContext {
/** The trace ID as a 32-character lowercase hex string. */
traceId: string;
/** The span ID as a 16-character lowercase hex string. */
spanId: string;
/** Trace flags (e.g., 1 for sampled). */
traceFlags: number;
/** Optional W3C trace state (e.g., "vendorname1=opaqueValue1,vendorname2=opaqueValue2"). */
traceState?: string;
}
/**
* ⚠️ OpenTelemetry can only be initialized once per process. Calling `OpenTelemetry.init()` more than once will be ignored.
* If you need to change configuration, restart the process with new settings.
* ### OpenTelemetry
*
* - **openTelemetryConfig**: Use {@link GlideOpenTelemetryConfig} to configure OpenTelemetry exporters and options.
* - **traces**: (optional) Configure trace exporting.
* - **endpoint**: The collector endpoint for traces. Supported protocols:
* - `http://` or `https://` for HTTP/HTTPS
* - `grpc://` for gRPC
* - `file://` for local file export (see below)
* - **samplePercentage**: (optional) The percentage of requests to sample and create a span for, used to measure command duration. Must be between 0 and 100. Defaults to 1 if not specified.
* Note: There is a tradeoff between sampling percentage and performance. Higher sampling percentages will provide more detailed telemetry data but will impact performance.
* It is recommended to keep this number low (1-5%) in production environments unless you have specific needs for higher sampling rates.
* - **metrics**: (optional) Configure metrics exporting.
* - **endpoint**: The collector endpoint for metrics. Same protocol rules as above.
* - **flushIntervalMs**: (optional) Interval in milliseconds for flushing data to the collector. Must be a positive integer. Defaults to 5000ms if not specified.
* - **parentSpanContextProvider**: (optional) Callback returning the active parent span context. See {@link GlideOpenTelemetryConfig.parentSpanContextProvider}.
*
* #### File Exporter Details
* - For `file://` endpoints:
* - The path must start with `file://` (e.g., `file:///tmp/otel` or `file:///tmp/otel/traces.json`).
* - If the path is a directory or lacks a file extension, data is written to `signals.json` in that directory.
* - If the path includes a filename with an extension, that file is used as-is.
* - The parent directory must already exist; otherwise, initialization will fail with an InvalidInput error.
* - If the target file exists, new data is appended (not overwritten).
*
* #### Validation Rules
* - `flushIntervalMs` must be a positive integer.
* - `samplePercentage` must be between 0 and 100.
* - File exporter paths must start with `file://` and have an existing parent directory.
* - Invalid configuration will throw an error synchronously when calling `OpenTelemetry.init()`.
*/
export declare class OpenTelemetry {
private static _instance;
private static openTelemetryConfig;
private static spanContextFn;
private static readonly TRACE_ID_REGEX;
private static readonly SPAN_ID_REGEX;
/**
* Singleton class for managing OpenTelemetry configuration and operations.
* This class provides a centralized way to initialize OpenTelemetry and control
* sampling behavior at runtime.
*
* Example usage:
* ```typescript
* import { OpenTelemetry, GlideOpenTelemetryConfig } from "@valkey/valkey-glide";
* import { trace } from "@opentelemetry/api";
*
* const config: GlideOpenTelemetryConfig = {
* traces: {
* endpoint: "http://localhost:4318/v1/traces",
* samplePercentage: 10,
* },
* metrics: {
* endpoint: "http://localhost:4318/v1/metrics",
* },
* flushIntervalMs: 1000,
* parentSpanContextProvider: () => {
* const span = trace.getActiveSpan();
* if (!span) return undefined;
* const ctx = span.spanContext();
* return { traceId: ctx.traceId, spanId: ctx.spanId, traceFlags: ctx.traceFlags };
* },
* };
* OpenTelemetry.init(config);
* ```
*
* @remarks
* OpenTelemetry can only be initialized once per process. Subsequent calls to
* init() will be ignored. This is by design, as OpenTelemetry is a global
* resource that should be configured once at application startup.
*
* Initialize the OpenTelemetry instance
* @param openTelemetryConfig - The OpenTelemetry configuration
*/
static init(openTelemetryConfig: GlideOpenTelemetryConfig): void;
private static internalInit;
/**
* Check if the OpenTelemetry instance is initialized
* @returns True if the OpenTelemetry instance is initialized, false otherwise
*/
static isInitialized(): boolean;
/**
* Get the sample percentage for traces
* @returns The sample percentage for traces only if OpenTelemetry is initialized and the traces config is set, otherwise undefined.
*/
static getSamplePercentage(): number | undefined;
/**
* Determines if the current request should be sampled for OpenTelemetry tracing.
* Uses the configured sample percentage to randomly decide whether to create a span for this request.
* @returns true if the request should be sampled, false otherwise
*/
static shouldSample(): boolean;
/**
* Set the percentage of requests to be sampled and traced. Must be a value between 0 and 100.
* This setting only affects traces, not metrics.
* @param percentage - The sample percentage 0-100
* @throws Error if OpenTelemetry is not initialized or traces config is not set
* @remarks
* This method can be called at runtime to change the sampling percentage without reinitializing OpenTelemetry.
*/
static setSamplePercentage(percentage: number): void;
/**
* Register or replace the callback that returns the active parent span context.
*
* This allows changing the provider at runtime (e.g., switching tracing contexts
* in a multi-tenant application). The initial provider can also be set via
* {@link GlideOpenTelemetryConfig.parentSpanContextProvider} in `init()`.
*
* @param fn - A function returning a `GlideSpanContext` or `undefined`, or `null` to clear.
*
* @example
* ```typescript
* import { trace } from "@opentelemetry/api";
*
* OpenTelemetry.setParentSpanContextProvider(() => {
* const span = trace.getActiveSpan();
* if (!span) return undefined;
* const ctx = span.spanContext();
* return {
* traceId: ctx.traceId,
* spanId: ctx.spanId,
* traceFlags: ctx.traceFlags,
* traceState: ctx.traceState?.toString(),
* };
* });
* ```
*/
static setParentSpanContextProvider(fn: (() => GlideSpanContext | undefined) | null): void;
}