/** * Sentry bootstrap for the BullMQ worker process. * * Exposes {@link initWorkerSentry} (called from `index.ts` as the very first * statement) and {@link workerErrorReporter} (an `ErrorReporter` facade that * `startWorkerRuntime` and any other code-path can use to forward unhandled * errors to Sentry). * * When `SENTRY_DSN_WORKER` is empty or unset every export becomes a no-op * so local development and Sentry-less staging environments keep working * unchanged. * * @see docs/improvement-plan/02-observability/sentry-wiring-api-worker.md */ import { createNoopErrorReporter, createSentryErrorReporter, type ErrorReporter } from "@hivegrid/error-reporter"; export interface WorkerSentryConfig { dsn: string | undefined; environment: string | undefined; release: string | undefined; tracesSampleRate: number; profilesSampleRate: number; } const DEFAULT_TRACES_SAMPLE_RATE_PROD = 0.1; const DEFAULT_TRACES_SAMPLE_RATE_DEV = 1.0; const DEFAULT_PROFILES_SAMPLE_RATE = 0.0; export function parseSampleRate(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 readWorkerSentryConfig(env: NodeJS.ProcessEnv = process.env): WorkerSentryConfig { const nodeEnv = env.NODE_ENV || "development"; const tracesDefault = nodeEnv === "production" ? DEFAULT_TRACES_SAMPLE_RATE_PROD : DEFAULT_TRACES_SAMPLE_RATE_DEV; return { dsn: env.SENTRY_DSN_WORKER || undefined, environment: env.SENTRY_ENVIRONMENT || nodeEnv || undefined, release: env.SENTRY_RELEASE || undefined, tracesSampleRate: parseSampleRate(env.SENTRY_TRACES_SAMPLE_RATE, tracesDefault), profilesSampleRate: parseSampleRate(env.SENTRY_PROFILES_SAMPLE_RATE, DEFAULT_PROFILES_SAMPLE_RATE), }; } let cachedReporter: ErrorReporter | undefined; let cachedConfig: WorkerSentryConfig | undefined; /** * Idempotent. The first call builds the Sentry-backed reporter (or the * no-op reporter when `SENTRY_DSN_WORKER` is empty); subsequent calls * return the cached instance. The Sentry SDK is loaded lazily through * the adapter in `@hivegrid/error-reporter`, so unit tests that do not * import this module never touch `@sentry/node` at all. */ export function initWorkerSentry(config: WorkerSentryConfig = readWorkerSentryConfig()): ErrorReporter { if (cachedReporter) { return cachedReporter; } cachedConfig = config; if (!config.dsn) { cachedReporter = createNoopErrorReporter(); return cachedReporter; } cachedReporter = createSentryErrorReporter({ dsn: config.dsn, environment: config.environment, release: config.release, tracesSampleRate: config.tracesSampleRate, profilesSampleRate: config.profilesSampleRate, maxBreadcrumbs: 50, }); return cachedReporter; } /** * Reporter facade. Lazy on first access so `apps/worker/src/index.ts` * controls when initialisation happens. */ export const workerErrorReporter: ErrorReporter = { report(event) { const reporter = cachedReporter ?? initWorkerSentry(); return reporter.report(event); }, }; /** Test-only: reset the cached reporter/config so multiple test cases can call init. */ export function __resetWorkerSentryForTests(): void { cachedReporter = undefined; cachedConfig = undefined; } /** Test-only: read the cached config (or undefined if not initialised). */ export function __getWorkerSentryConfigForTests(): WorkerSentryConfig | undefined { return cachedConfig; }