Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/packages/error-reporter/src/tracing.ts
T

166 lines
5.2 KiB
TypeScript

export type TracingOptions = {
serviceName: string;
/** Falls back to OTEL_EXPORTER_OTLP_ENDPOINT environment variable when not provided. */
otlpEndpoint?: string;
enabled?: boolean;
/**
* Internal hooks used by tests to substitute the OpenTelemetry SDK without installing it.
* Production callers should never supply these.
*/
loadSdk?: () => Promise<NodeSdkLikeModule | undefined>;
loadOtlpExporter?: () => Promise<OtlpExporterLikeModule | undefined>;
/**
* Optional logger used to surface the dynamic-import fallback. Defaults to `console.warn`.
*/
onMissingDependency?: (message: string) => void;
};
export type NodeSdkLikeModule = {
NodeSDK: new (options: { serviceName?: string; traceExporter?: unknown }) => NodeSdkInstance;
};
export type NodeSdkInstance = {
start: () => void | Promise<void>;
shutdown: () => Promise<void>;
};
export type OtlpExporterLikeModule = {
OTLPTraceExporter: new (options: { url?: string }) => unknown;
};
type TracingState = {
sdk: NodeSdkInstance;
};
let activeState: TracingState | undefined;
/**
* Initializes an OpenTelemetry NodeSDK with an OTLP HTTP trace exporter. Both `@opentelemetry/sdk-node`
* and `@opentelemetry/exporter-trace-otlp-http` are loaded via dynamic import so they stay optional
* peer dependencies: when either is missing the helper logs a single warning and becomes a no-op.
*
* Safe to call multiple times — repeated calls after a successful start are ignored.
*/
export async function initializeTracing(options: TracingOptions): Promise<void> {
const onMissing = options.onMissingDependency ?? defaultMissingDependencyLogger;
if (options.enabled === false) {
return;
}
if (activeState) {
return;
}
const endpoint = options.otlpEndpoint ?? readEnv("OTEL_EXPORTER_OTLP_ENDPOINT");
if (!endpoint) {
onMissing("@toolctrl/error-reporter: OTEL_EXPORTER_OTLP_ENDPOINT is not set; tracing skeleton stays disabled.");
return;
}
const sdkLoader = options.loadSdk ?? loadSdkFromNodeModules;
const exporterLoader = options.loadOtlpExporter ?? loadOtlpExporterFromNodeModules;
let sdkModule: NodeSdkLikeModule | undefined;
let exporterModule: OtlpExporterLikeModule | undefined;
try {
sdkModule = await sdkLoader();
} catch {
sdkModule = undefined;
}
try {
exporterModule = await exporterLoader();
} catch {
exporterModule = undefined;
}
if (!sdkModule || !exporterModule) {
onMissing("@toolctrl/error-reporter: @opentelemetry/sdk-node or @opentelemetry/exporter-trace-otlp-http is not installed; tracing skeleton stays disabled.");
return;
}
try {
const traceExporter = new exporterModule.OTLPTraceExporter({ url: endpoint });
const sdk = new sdkModule.NodeSDK({
serviceName: options.serviceName,
traceExporter,
});
await sdk.start();
activeState = { sdk };
} catch (cause) {
onMissing(`@toolctrl/error-reporter: failed to start OpenTelemetry NodeSDK (${describeCause(cause)}); tracing skeleton stays disabled.`);
}
}
export async function shutdownTracing(): Promise<void> {
if (!activeState) {
return;
}
const current = activeState;
activeState = undefined;
try {
await current.sdk.shutdown();
} catch {
// Shutdown failures must not crash the runtime tear-down path.
}
}
async function loadSdkFromNodeModules(): Promise<NodeSdkLikeModule | undefined> {
try {
const moduleName = "@opentelemetry/sdk-node";
const loaded = (await import(/* @vite-ignore */ moduleName)) as NodeSdkLikeModule | { default?: NodeSdkLikeModule };
if (loaded && typeof (loaded as NodeSdkLikeModule).NodeSDK === "function") {
return loaded as NodeSdkLikeModule;
}
if (loaded && typeof (loaded as { default?: NodeSdkLikeModule }).default?.NodeSDK === "function") {
return (loaded as { default: NodeSdkLikeModule }).default;
}
return undefined;
} catch {
return undefined;
}
}
async function loadOtlpExporterFromNodeModules(): Promise<OtlpExporterLikeModule | undefined> {
try {
const moduleName = "@opentelemetry/exporter-trace-otlp-http";
const loaded = (await import(/* @vite-ignore */ moduleName)) as OtlpExporterLikeModule | { default?: OtlpExporterLikeModule };
if (loaded && typeof (loaded as OtlpExporterLikeModule).OTLPTraceExporter === "function") {
return loaded as OtlpExporterLikeModule;
}
if (loaded && typeof (loaded as { default?: OtlpExporterLikeModule }).default?.OTLPTraceExporter === "function") {
return (loaded as { default: OtlpExporterLikeModule }).default;
}
return undefined;
} catch {
return undefined;
}
}
function readEnv(name: string): string | undefined {
const env = typeof process !== "undefined" ? process.env : undefined;
if (!env) {
return undefined;
}
const raw = env[name];
if (!raw || raw.trim().length === 0) {
return undefined;
}
return raw.trim();
}
function defaultMissingDependencyLogger(message: string): void {
const consoleRef: Console | undefined = typeof globalThis !== "undefined" ? (globalThis as { console?: Console }).console : undefined;
consoleRef?.warn?.(message);
}
function describeCause(cause: unknown): string {
if (cause instanceof Error) {
return cause.message;
}
return String(cause);
}