166 lines
5.2 KiB
TypeScript
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);
|
|
}
|