Reorganize repo structure and standards references
This commit is contained in:
1 parent
3cb93a81be
commit
be2054274d
5885 files changed
+2588
-195
No files matched your search
@@ -0,0 +1,141 @@
|
||||
/**
|
||||
* 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 "@toolctrl/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 = "boilerplate-worker";
|
||||
const DEFAULT_SERVICE_NAMESPACE = "toolctrl";
|
||||
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();
|
||||
Reference in new issue
Block a user