/** * OpenTelemetry bootstrap for the BullMQ worker process. * * MUST be imported as the very first statement in `apps/worker/src/index.ts` * so the auto-instrumentations can hook BullMQ, Prisma, Redis, http and * friends before they are required for the first time. * * Default sampler ratio is 0.2 (vs. 0.1 in the API) — worker jobs are * less frequent than HTTP requests but each represents a meaningful unit * of work, so the per-trace marginal value is higher. * * No-op when `OTEL_EXPORTER_OTLP_ENDPOINT` is empty/unset. * * @see docs/improvement-plan/02-observability/opentelemetry.md (Step 5 + 6) */ import { hostname } from "node:os"; import { diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api"; import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node"; import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http"; import { resourceFromAttributes } from "@opentelemetry/resources"; import { NodeSDK } from "@opentelemetry/sdk-node"; import { BatchSpanProcessor, ParentBasedSampler, TraceIdRatioBasedSampler } from "@opentelemetry/sdk-trace-base"; import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions"; import { PIISpanProcessor } from "@hivegrid/observability"; export interface WorkerOtelConfig { endpoint: string | undefined; headers: Record | undefined; serviceName: string; serviceVersion: string | undefined; serviceInstanceId: string; deploymentEnvironment: string | undefined; serviceNamespace: string; tracesSamplerArg: number; debug: boolean; } const DEFAULT_SERVICE_NAME = "hivegrid-worker"; const DEFAULT_SERVICE_NAMESPACE = "hivegrid"; const DEFAULT_TRACES_SAMPLER_ARG = 0.2; export function parseSamplerArg(raw: string | undefined, fallback: number): number { if (raw === undefined || raw === null || raw === "") return fallback; const parsed = Number(raw); if (!Number.isFinite(parsed)) return fallback; if (parsed < 0) return 0; if (parsed > 1) return 1; return parsed; } export function parseOtlpHeaders(raw: string | undefined): Record | undefined { if (!raw) return undefined; const out: Record = {}; for (const pair of raw.split(",")) { const eq = pair.indexOf("="); if (eq < 0) continue; const key = pair.slice(0, eq).trim(); const value = pair.slice(eq + 1).trim(); if (!key) continue; out[key] = value; } return Object.keys(out).length > 0 ? out : undefined; } export function readWorkerOtelConfig(env: NodeJS.ProcessEnv = process.env): WorkerOtelConfig { return { endpoint: env.OTEL_EXPORTER_OTLP_ENDPOINT || undefined, headers: parseOtlpHeaders(env.OTEL_EXPORTER_OTLP_HEADERS), serviceName: env.OTEL_SERVICE_NAME || DEFAULT_SERVICE_NAME, serviceVersion: env.SENTRY_RELEASE || env.APP_REVISION || undefined, serviceInstanceId: `${hostname()}-${process.pid}`, deploymentEnvironment: env.SENTRY_ENVIRONMENT || env.NODE_ENV || undefined, serviceNamespace: DEFAULT_SERVICE_NAMESPACE, tracesSamplerArg: parseSamplerArg(env.OTEL_TRACES_SAMPLER_ARG, DEFAULT_TRACES_SAMPLER_ARG), debug: env.OTEL_LOG_LEVEL?.toLowerCase() === "debug", }; } let cachedSdk: NodeSDK | undefined; let cachedConfig: WorkerOtelConfig | undefined; export function initWorkerOtel(config: WorkerOtelConfig = readWorkerOtelConfig()): NodeSDK | undefined { if (cachedSdk) return cachedSdk; cachedConfig = config; if (!config.endpoint) return undefined; if (config.debug) { diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.DEBUG); } const exporter = new OTLPTraceExporter({ url: config.endpoint, headers: config.headers, }); const resource = resourceFromAttributes({ [ATTR_SERVICE_NAME]: config.serviceName, ...(config.serviceVersion ? { [ATTR_SERVICE_VERSION]: config.serviceVersion } : {}), "service.instance.id": config.serviceInstanceId, ...(config.deploymentEnvironment ? { "deployment.environment": config.deploymentEnvironment } : {}), "service.namespace": config.serviceNamespace, }); const sampler = new ParentBasedSampler({ root: new TraceIdRatioBasedSampler(config.tracesSamplerArg), }); const sdk = new NodeSDK({ resource, sampler, spanProcessors: [new PIISpanProcessor(new BatchSpanProcessor(exporter))], instrumentations: [ getNodeAutoInstrumentations({ "@opentelemetry/instrumentation-fs": { enabled: false }, }), ], }); sdk.start(); cachedSdk = sdk; process.on("beforeExit", () => { void sdk.shutdown().catch(() => undefined); }); return sdk; } export function __resetWorkerOtelForTests(): void { cachedSdk = undefined; cachedConfig = undefined; } export function __getWorkerOtelConfigForTests(): WorkerOtelConfig | undefined { return cachedConfig; } // Auto-init at module-load time so importing this file from index.ts boots OTel. initWorkerOtel();