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,165 @@
|
||||
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);
|
||||
}
|
||||
Reference in new issue
Block a user