/**
 * @fileoverview OpenTelemetry SDK initialization and lifecycle management.
 * Provides runtime-aware initialization with graceful degradation for Worker/Edge environments.
 * Supports both Node.js (full NodeSDK) and serverless runtimes (lightweight telemetry).
 * @module src/utils/telemetry/instrumentation
 */
import type { NodeSDK } from '@opentelemetry/sdk-node';
/**
 * The active OpenTelemetry `NodeSDK` instance, or `null` when telemetry is disabled,
 * the runtime is not Node/Bun, or the SDK has been shut down.
 * Node-specific SDK modules are lazy-loaded inside `initializeOpenTelemetry` to prevent
 * crashes in Worker/Edge environments where those modules are unavailable.
 */
export declare let sdk: NodeSDK | null;
/**
 * Initializes the OpenTelemetry SDK with runtime-appropriate configuration.
 * Idempotent — safe to call multiple times; subsequent calls return the existing promise or resolve immediately.
 * No-ops silently when telemetry is disabled (`OTEL_ENABLED=false`) or when running in a
 * Worker/Edge environment where `NodeSDK` is unavailable.
 *
 * In Node/Bun environments, all SDK modules (`@opentelemetry/sdk-node`, exporters,
 * auto-instrumentations) are **lazy-loaded** via `Promise.all(import(...))` to prevent
 * Worker bundle failures.
 *
 * Configures:
 * - OTLP trace exporter + `BatchSpanProcessor` (when `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` is set)
 * - OTLP metrics exporter + `PeriodicExportingMetricReader` at 15 s intervals (when `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` is set)
 * - `TraceIdRatioBasedSampler` using `config.openTelemetry.samplingRatio`
 * - Node auto-instrumentations (HTTP enabled, FS disabled)
 * - Pino instrumentation that injects `trace_id`/`span_id` into log records
 * - Cloud resource attributes via `detectCloudResource()`
 *
 * @returns Promise that resolves when initialization is complete (or was already complete)
 * @throws Error if `NodeSDK.start()` or any lazy import fails; re-thrown after resetting `sdk` to `null`
 *
 * @example
 * ```typescript
 * // In application entry point (src/index.ts)
 * await initializeOpenTelemetry();
 * ```
 */
export declare function initializeOpenTelemetry(): Promise<void>;
/**
 * Gracefully shuts down the OpenTelemetry SDK with timeout protection.
 * This function is called during the application's shutdown sequence.
 * Prevents hung processes by racing shutdown against a timeout.
 *
 * @param timeoutMs - Maximum time to wait for shutdown in milliseconds (default: 5000)
 * @throws Error if shutdown times out or fails critically
 *
 * @example
 * ```typescript
 * // During application shutdown
 * try {
 *   await shutdownOpenTelemetry();
 * } catch (error) {
 *   console.error('Failed to shutdown telemetry:', error);
 * }
 * ```
 */
export declare function shutdownOpenTelemetry(timeoutMs?: number): Promise<void>;
//# sourceMappingURL=instrumentation.d.ts.map