export type TracingOptions = { serviceName: string; /** Falls back to OTEL_EXPORTER_OTLP_ENDPOINT environment variable when not provided. */ otlpEndpoint?: string; enabled?: boolean; /** * Internal hooks used by tests to substitute the OpenTelemetry SDK without installing it. * Production callers should never supply these. */ loadSdk?: () => Promise; loadOtlpExporter?: () => Promise; /** * Optional logger used to surface the dynamic-import fallback. Defaults to `console.warn`. */ onMissingDependency?: (message: string) => void; }; export type NodeSdkLikeModule = { NodeSDK: new (options: { serviceName?: string; traceExporter?: unknown }) => NodeSdkInstance; }; export type NodeSdkInstance = { start: () => void | Promise; shutdown: () => Promise; }; export type OtlpExporterLikeModule = { OTLPTraceExporter: new (options: { url?: string }) => unknown; }; type TracingState = { sdk: NodeSdkInstance; }; let activeState: TracingState | undefined; /** * Initializes an OpenTelemetry NodeSDK with an OTLP HTTP trace exporter. Both `@opentelemetry/sdk-node` * and `@opentelemetry/exporter-trace-otlp-http` are loaded via dynamic import so they stay optional * peer dependencies: when either is missing the helper logs a single warning and becomes a no-op. * * Safe to call multiple times — repeated calls after a successful start are ignored. */ export async function initializeTracing(options: TracingOptions): Promise { const onMissing = options.onMissingDependency ?? defaultMissingDependencyLogger; if (options.enabled === false) { return; } if (activeState) { return; } const endpoint = options.otlpEndpoint ?? readEnv("OTEL_EXPORTER_OTLP_ENDPOINT"); if (!endpoint) { onMissing("@toolctrl/error-reporter: OTEL_EXPORTER_OTLP_ENDPOINT is not set; tracing skeleton stays disabled."); return; } const sdkLoader = options.loadSdk ?? loadSdkFromNodeModules; const exporterLoader = options.loadOtlpExporter ?? loadOtlpExporterFromNodeModules; let sdkModule: NodeSdkLikeModule | undefined; let exporterModule: OtlpExporterLikeModule | undefined; try { sdkModule = await sdkLoader(); } catch { sdkModule = undefined; } try { exporterModule = await exporterLoader(); } catch { exporterModule = undefined; } if (!sdkModule || !exporterModule) { onMissing("@toolctrl/error-reporter: @opentelemetry/sdk-node or @opentelemetry/exporter-trace-otlp-http is not installed; tracing skeleton stays disabled."); return; } try { const traceExporter = new exporterModule.OTLPTraceExporter({ url: endpoint }); const sdk = new sdkModule.NodeSDK({ serviceName: options.serviceName, traceExporter, }); await sdk.start(); activeState = { sdk }; } catch (cause) { onMissing(`@toolctrl/error-reporter: failed to start OpenTelemetry NodeSDK (${describeCause(cause)}); tracing skeleton stays disabled.`); } } export async function shutdownTracing(): Promise { if (!activeState) { return; } const current = activeState; activeState = undefined; try { await current.sdk.shutdown(); } catch { // Shutdown failures must not crash the runtime tear-down path. } } async function loadSdkFromNodeModules(): Promise { try { const moduleName = "@opentelemetry/sdk-node"; const loaded = (await import(/* @vite-ignore */ moduleName)) as NodeSdkLikeModule | { default?: NodeSdkLikeModule }; if (loaded && typeof (loaded as NodeSdkLikeModule).NodeSDK === "function") { return loaded as NodeSdkLikeModule; } if (loaded && typeof (loaded as { default?: NodeSdkLikeModule }).default?.NodeSDK === "function") { return (loaded as { default: NodeSdkLikeModule }).default; } return undefined; } catch { return undefined; } } async function loadOtlpExporterFromNodeModules(): Promise { try { const moduleName = "@opentelemetry/exporter-trace-otlp-http"; const loaded = (await import(/* @vite-ignore */ moduleName)) as OtlpExporterLikeModule | { default?: OtlpExporterLikeModule }; if (loaded && typeof (loaded as OtlpExporterLikeModule).OTLPTraceExporter === "function") { return loaded as OtlpExporterLikeModule; } if (loaded && typeof (loaded as { default?: OtlpExporterLikeModule }).default?.OTLPTraceExporter === "function") { return (loaded as { default: OtlpExporterLikeModule }).default; } return undefined; } catch { return undefined; } } function readEnv(name: string): string | undefined { const env = typeof process !== "undefined" ? process.env : undefined; if (!env) { return undefined; } const raw = env[name]; if (!raw || raw.trim().length === 0) { return undefined; } return raw.trim(); } function defaultMissingDependencyLogger(message: string): void { const consoleRef: Console | undefined = typeof globalThis !== "undefined" ? (globalThis as { console?: Console }).console : undefined; consoleRef?.warn?.(message); } function describeCause(cause: unknown): string { if (cause instanceof Error) { return cause.message; } return String(cause); }