Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/apps/worker/src/otel.ts
T
2026-07-08 16:15:37 +02:00

142 lines
4.9 KiB
TypeScript

/**
* 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<string, string> | 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<string, string> | undefined {
if (!raw) return undefined;
const out: Record<string, string> = {};
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();