142 lines
4.9 KiB
TypeScript
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();
|