/**
 * Copyright (c) 2025 Databricks Contributors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/**
 * Driver name constant for telemetry
 */
export declare const DRIVER_NAME = "nodejs-sql-driver";
/**
 * Event types emitted by the telemetry system
 */
export declare enum TelemetryEventType {
    CONNECTION_OPEN = "connection.open",
    CONNECTION_CLOSE = "connection.close",
    STATEMENT_START = "statement.start",
    STATEMENT_COMPLETE = "statement.complete",
    CLOUDFETCH_CHUNK = "cloudfetch.chunk",
    ERROR = "telemetry.error"
}
/**
 * Configuration for telemetry components
 */
export interface TelemetryConfiguration {
    /** Whether telemetry is enabled */
    enabled?: boolean;
    /** Maximum number of metrics to batch before flushing */
    batchSize?: number;
    /** Interval in milliseconds to flush metrics */
    flushIntervalMs?: number;
    /** Maximum retry attempts for export (attempts *after* the initial call) */
    maxRetries?: number;
    /** Minimum backoff delay in ms for retry backoff */
    backoffBaseMs?: number;
    /** Maximum backoff delay in ms (includes jitter) */
    backoffMaxMs?: number;
    /** Upper bound of added jitter in ms */
    backoffJitterMs?: number;
    /** Whether to use authenticated export endpoint */
    authenticatedExport?: boolean;
    /** Circuit breaker failure threshold */
    circuitBreakerThreshold?: number;
    /** Circuit breaker timeout in milliseconds */
    circuitBreakerTimeout?: number;
    /** Maximum number of pending metrics buffered before dropping oldest */
    maxPendingMetrics?: number;
    /** Maximum number of error events buffered per statement before dropping oldest */
    maxErrorsPerStatement?: number;
    /** TTL in ms after which abandoned statement aggregations are evicted */
    statementTtlMs?: number;
    /**
     * Maximum wall-clock time `close()` will wait for the final flush HTTP POST
     * before abandoning it and returning. Bounds shutdown latency so callers
     * doing `await client.close(); process.exit(0)` are not held up by a
     * misbehaving telemetry endpoint.
     */
    closeTimeoutMs?: number;
    /** Hard cap on per-statement aggregation map size; oldest evicted on overflow. */
    maxStatementMetrics?: number;
}
/**
 * Default telemetry configuration values
 */
export declare const DEFAULT_TELEMETRY_CONFIG: Readonly<Required<TelemetryConfiguration>>;
/**
 * Runtime telemetry event emitted by the driver
 */
export interface TelemetryEvent {
    /** Type of the event */
    eventType: TelemetryEventType;
    /**
     * Backend that produced the event. Populated once non-Thrift backends start
     * emitting telemetry so dashboards can slice latency / error rate /
     * cloudfetch effectiveness by backend without a metrics-schema migration.
     * Optional for back-compat with already-emitted Thrift-only events.
     */
    backend?: 'thrift' | 'kernel';
    /** Timestamp when the event occurred (milliseconds since epoch) */
    timestamp: number;
    /** Session ID for correlation */
    sessionId?: string;
    /** Statement ID for correlation */
    statementId?: string;
    /** Workspace ID */
    workspaceId?: string;
    /** Driver configuration */
    driverConfig?: DriverConfiguration;
    /** Type of operation (SELECT, INSERT, etc.) */
    operationType?: string;
    /** Execution latency in milliseconds */
    latencyMs?: number;
    /** Result format (inline, cloudfetch, arrow) */
    resultFormat?: string;
    /** Number of result chunks */
    chunkCount?: number;
    /** Total bytes downloaded */
    bytesDownloaded?: number;
    /** Number of poll operations */
    pollCount?: number;
    /** Chunk index in the result set */
    chunkIndex?: number;
    /** Number of bytes in this chunk */
    bytes?: number;
    /** Whether compression was used */
    compressed?: boolean;
    /** Error name/type */
    errorName?: string;
    /** Error message */
    errorMessage?: string;
    /** Stack trace, captured at emission site; redacted before export */
    errorStack?: string;
    /** Whether the error is terminal (non-retryable) */
    isTerminal?: boolean;
}
/**
 * Aggregated telemetry metric for export to Databricks
 */
export interface TelemetryMetric {
    /** Type of metric */
    metricType: 'connection' | 'statement' | 'error';
    /** Timestamp when the metric was created (milliseconds since epoch) */
    timestamp: number;
    /** Session ID for correlation */
    sessionId?: string;
    /** Statement ID for correlation */
    statementId?: string;
    /** Workspace ID */
    workspaceId?: string;
    /** Driver configuration (included in all metrics for context) */
    driverConfig?: DriverConfiguration;
    /** Execution latency in milliseconds */
    latencyMs?: number;
    /** Type of operation (SELECT, INSERT, etc.) */
    operationType?: string;
    /** Result format (inline, cloudfetch, arrow) */
    resultFormat?: string;
    /** Number of result chunks */
    chunkCount?: number;
    /** Latency of the first chunk fetch in milliseconds */
    chunkInitialLatencyMs?: number;
    /** Latency of the slowest chunk fetch in milliseconds */
    chunkSlowestLatencyMs?: number;
    /** Sum of all chunk fetch latencies in milliseconds */
    chunkSumLatencyMs?: number;
    /** Total bytes downloaded */
    bytesDownloaded?: number;
    /** Number of poll operations */
    pollCount?: number;
    /** Whether compression was used */
    compressed?: boolean;
    /** Error name/type */
    errorName?: string;
    /** Error message */
    errorMessage?: string;
    /** Stack trace, captured at emission site; redacted before export */
    errorStack?: string;
}
/**
 * Driver configuration metadata collected once per connection
 */
export interface DriverConfiguration {
    /** Driver version */
    driverVersion: string;
    /** Driver name */
    driverName: string;
    /**
     * Backend in use for this connection. Populated when the driver selects a
     * non-Thrift backend so per-connection slicing in metrics is possible.
     * Optional for back-compat with snapshots taken before this field landed.
     */
    backend?: 'thrift' | 'kernel';
    /** Node.js version */
    nodeVersion: string;
    /** Platform (linux, darwin, win32) */
    platform: string;
    /** OS version */
    osVersion: string;
    /** OS architecture (x64, arm64, etc.) */
    osArch: string;
    /** Runtime vendor (Node.js Foundation) */
    runtimeVendor: string;
    /** Locale name (e.g., en_US) */
    localeName: string;
    /** Character set encoding (e.g., UTF-8) */
    charSetEncoding: string;
    /**
     * Process name. Producers MUST pass only a basename (no absolute path) —
     * `sanitizeProcessName()` is applied at export time as a defence in depth.
     */
    processName: string;
    /** Authentication type (pat, external-browser, oauth-m2m, custom) */
    authType: string;
    /** Whether CloudFetch is enabled */
    cloudFetchEnabled: boolean;
    /** Whether LZ4 compression is enabled */
    lz4Enabled: boolean;
    /** Whether Arrow format is enabled */
    arrowEnabled: boolean;
    /** Whether direct results are enabled */
    directResultsEnabled: boolean;
    /** Socket timeout in milliseconds */
    socketTimeout: number;
    /** Maximum retry attempts */
    retryMaxAttempts: number;
    /** Number of concurrent CloudFetch downloads */
    cloudFetchConcurrentDownloads: number;
    /** HTTP path for API calls */
    httpPath?: string;
    /** Whether metric view metadata is enabled */
    enableMetricViewMetadata?: boolean;
    /** Whether an HTTP/SOCKS proxy is configured on the connection */
    useProxy?: boolean;
}
/**
 * Per-statement metrics aggregated from multiple events
 */
export interface StatementMetrics {
    /** Statement ID */
    statementId: string;
    /** Session ID */
    sessionId: string;
    /** Type of operation */
    operationType?: string;
    /** Start timestamp (milliseconds since epoch) */
    startTime: number;
    /** Total execution latency in milliseconds */
    executionLatencyMs?: number;
    /** Number of poll operations */
    pollCount: number;
    /** Total poll latency in milliseconds */
    pollLatencyMs: number;
    /** Result format (inline, cloudfetch, arrow) */
    resultFormat?: string;
    /** Number of CloudFetch chunks downloaded */
    chunkCount: number;
    /** Latency of the first chunk fetch in milliseconds */
    chunkInitialLatencyMs?: number;
    /** Latency of the slowest chunk fetch in milliseconds */
    chunkSlowestLatencyMs?: number;
    /** Sum of all chunk fetch latencies in milliseconds */
    chunkSumLatencyMs?: number;
    /** Total bytes downloaded */
    totalBytesDownloaded: number;
    /** Whether compression was used */
    compressionEnabled?: boolean;
}