@clickhouse/clickstack-node 0.0.0-stage → 1.0.0-rc.1

package/dist/lifecycle.cjs

@@ -0,0 +1,249 @@
+const require_state = require("./state.cjs");
+const require_env = require("./env.cjs");
+let node_worker_threads = require("node:worker_threads");
+let _opentelemetry_api = require("@opentelemetry/api");
+let _opentelemetry_core = require("@opentelemetry/core");
+let node_util = require("node:util");
+let node_os = require("node:os");
+let _opentelemetry_api_logs = require("@opentelemetry/api-logs");
+// src/lifecycle.ts
+const DEFAULT_TIMEOUT_MILLIS = 5e3;
+const SENTRY_SEND_MILLIS = 2e3;
+const INVOCATION_MARGIN_MILLIS = 500;
+const SIGNALS = ["SIGTERM", "SIGINT"];
+function bounded(work, ms, keepAlive) {
+	let timer;
+	const deadline = new Promise((resolve) => {
+		timer = setTimeout(resolve, ms, false);
+		if (!keepAlive) timer.unref();
+	});
+	const settled = Promise.resolve().then(work).then(() => true);
+	return Promise.race([settled, deadline]).then((inTime) => {
+		clearTimeout(timer);
+		if (!inTime) require_env.report("warn", `flush or shutdown did not finish within ${String(ms)} ms`);
+		return inTime;
+	});
+}
+function timeoutOf(timeoutMillis) {
+	if (timeoutMillis !== void 0 && timeoutMillis > 0) return Math.min(timeoutMillis, 2147483647);
+	const deadline = require_state.getState().invocationDeadline;
+	return deadline === void 0 ? DEFAULT_TIMEOUT_MILLIS : Math.max(1, Math.min(DEFAULT_TIMEOUT_MILLIS, deadline - Date.now()));
+}
+function sdkShutdown() {
+	const state = require_state.getState();
+	const sdk = state.sdk;
+	if (sdk === void 0) return Promise.resolve();
+	return state.shutdownPromise ??= (async () => {
+		await state.flushInFlight;
+		try {
+			await sdk.shutdown();
+		} catch (error) {
+			require_env.report("warn", "shutdown failed", error);
+		}
+		state.unsubscribeUndici?.();
+	})();
+}
+/**
+* Records when the current AWS Lambda invocation must return, so flushes end in time.
+*
+* @param context - The invocation context; anything without `getRemainingTimeInMillis` is ignored.
+*/
+function recordInvocationDeadline(context) {
+	const remaining = context?.getRemainingTimeInMillis?.();
+	if (typeof remaining === "number") require_state.getState().invocationDeadline = Date.now() + remaining - INVOCATION_MARGIN_MILLIS;
+}
+/**
+* Exports the spans, metrics and log records the SDK has buffered, without stopping it.
+*
+* @remarks
+* Calls `forceFlush` on the global tracer, meter and logger providers. Before `init`, or with
+* `OTEL_SDK_DISABLED=true`, it resolves at once; after {@link shutdown} it waits for the shutdown.
+* Failures and timeouts are reported through the OpenTelemetry `diag` logger. Inside a
+* {@link withFlush} invocation the default bound also ends before the invocation's deadline.
+*
+* @param timeoutMillis - Upper bound in milliseconds, 5000 by default; zero, negative and NaN
+*   mean the default.
+* @returns A promise that resolves when every provider has flushed or the bound has passed. It
+*   never rejects.
+* @public
+*/
+async function flush(timeoutMillis) {
+	const state = require_state.getState();
+	if (state.sdk === void 0) return;
+	const ms = timeoutOf(timeoutMillis);
+	const pending = state.shutdownPromise;
+	if (pending !== void 0) {
+		await bounded(() => pending, ms, false);
+		return;
+	}
+	const tracer = _opentelemetry_api.trace.getTracerProvider();
+	const providers = [
+		tracer.getDelegate?.() ?? tracer,
+		_opentelemetry_api.metrics.getMeterProvider(),
+		_opentelemetry_api_logs.logs.getLoggerProvider()
+	];
+	const work = Promise.all(providers.map(async (provider) => {
+		const p = provider;
+		if (typeof p.forceFlush !== "function") return;
+		try {
+			await p.forceFlush({ timeoutMillis: ms });
+		} catch (error) {
+			require_env.report("warn", "flush failed", error);
+		}
+	}));
+	state.flushInFlight = Promise.all([state.flushInFlight, work]);
+	await bounded(() => work, ms, false);
+}
+/**
+* Flushes and stops the SDK started by `init`; telemetry recorded afterwards is dropped.
+*
+* @remarks
+* Later calls, and the automatic shutdown on `beforeExit`, SIGTERM, SIGINT and uncaught
+* exceptions, share the first call's work. Scripts that end with `process.exit()`, and app signal
+* handlers that exit, should await it first, because `process.exit()` skips `beforeExit`.
+*
+* @param timeoutMillis - Upper bound in milliseconds, 5000 by default; zero, negative and NaN
+*   mean the default.
+* @returns A promise that resolves when the SDK has shut down or the bound has passed. It never
+*   rejects.
+* @example
+* ```ts
+* process.on('SIGTERM', async () => {
+*   await server.close();
+*   await shutdown();
+*   process.exit(0);
+* });
+* ```
+* @public
+*/
+async function shutdown(timeoutMillis) {
+	if (require_state.getState().sdk === void 0) return;
+	await bounded(sdkShutdown, timeoutOf(timeoutMillis), false);
+}
+/**
+* Wraps an async serverless handler so buffered telemetry is exported before each invocation
+* returns.
+*
+* @remarks
+* Awaits the handler, then {@link flush} in a `finally` block, so telemetry is also exported when
+* the handler throws. Flushes during the invocation end 500 ms before its deadline
+* (`context.getRemainingTimeInMillis()`). On its first call it installs console capture again if
+* the AWS Lambda runtime replaced the console methods after the preload ran. Callback-style
+* handlers are not supported.
+*
+* @typeParam E - The invocation event type.
+* @typeParam C - The runtime context type, for example the AWS Lambda `Context`.
+* @typeParam R - The value the handler's promise resolves to.
+* @param handler - The async handler to wrap.
+* @returns A handler with the same parameters and result.
+* @example
+* With `NODE_OPTIONS=--import @clickhouse/clickstack-node/register` set on the function:
+* ```ts
+* import { withFlush } from '@clickhouse/clickstack-node';
+*
+* export const handler = withFlush(async (event: { name?: string }) => {
+*   console.log('greeting', event.name);
+*   return { statusCode: 200, body: 'ok' };
+* });
+* ```
+* @public
+*/
+function withFlush(handler) {
+	let firstCall = true;
+	return async function flushingHandler(event, context) {
+		const state = require_state.getState();
+		try {
+			recordInvocationDeadline(context);
+			if (firstCall) {
+				firstCall = false;
+				const current = console.log;
+				if (state.repatchConsole !== void 0 && current !== state.consoleLog) {
+					state.repatchConsole();
+					state.consoleLog = console.log;
+				}
+			}
+		} catch (error) {
+			require_env.report("warn", "could not prepare the invocation", error);
+		}
+		try {
+			return await handler(event, context);
+		} finally {
+			await flush();
+		}
+	};
+}
+function writeFatal(error) {
+	try {
+		const body = typeof error === "string" ? error : (0, node_util.inspect)(error, {
+			customInspect: false,
+			depth: 5
+		});
+		process.getBuiltinModule("node:fs").writeSync(2, `${body}\n\nNode.js ${process.version}\n`);
+	} catch {}
+}
+function signalExitListeners() {
+	const v4 = globalThis[Symbol.for("signal-exit emitter")];
+	const v3 = process.__signal_exit_emitter__;
+	return [v4?.count, v3?.count].reduce((sum, count) => sum + (typeof count === "number" ? count : 0), 0);
+}
+/**
+* Installs the `beforeExit`, SIGTERM, SIGINT and `uncaughtException` handlers, once per thread.
+* Signal and crash handlers go on the main thread only: workers never receive signals, and a
+* worker crash listener would hide the parent's `error` event.
+*/
+function installLifecycle() {
+	let terminating = false;
+	let terminatingSince = 0;
+	if ((0, _opentelemetry_core.getStringFromEnv)("AWS_LAMBDA_FUNCTION_NAME") === void 0) process.once("beforeExit", () => {
+		if (terminating) return;
+		bounded(sdkShutdown, DEFAULT_TIMEOUT_MILLIS, false).then((inTime) => {
+			if (!inTime) process.exit();
+		});
+	});
+	if (!node_worker_threads.isMainThread) return;
+	const onSignal = (signal) => {
+		if (terminating) {
+			if (Date.now() - terminatingSince > 1e3) process.exit(128 + node_os.constants.signals[signal]);
+			return;
+		}
+		if (process.listeners(signal).filter((listener) => listener !== onSignal).length > signalExitListeners()) {
+			process.removeListener(signal, onSignal);
+			flush();
+			return;
+		}
+		terminating = true;
+		terminatingSince = Date.now();
+		bounded(sdkShutdown, DEFAULT_TIMEOUT_MILLIS, true).then(() => {
+			for (const name of SIGNALS) process.removeListener(name, onSignal);
+			try {
+				process.kill(process.pid, signal);
+			} catch {}
+			process.exit(128 + node_os.constants.signals[signal]);
+		});
+	};
+	for (const signal of SIGNALS) process.prependListener(signal, onSignal);
+	const onUncaughtException = (error) => {
+		try {
+			const listeners = process.listeners("uncaughtException");
+			const isSentry = (listener) => "_errorHandler" in listener && listener._errorHandler === true;
+			if (listeners.some((listener) => listener !== onUncaughtException && listener.name !== "domainUncaughtExceptionClear" && !isSentry(listener))) return;
+			process.exitCode = 1;
+			if (terminating) return;
+			writeFatal(error);
+			terminating = true;
+			terminatingSince = Date.now();
+			const sentry = listeners.some(isSentry) ? new Promise((resolve) => setTimeout(resolve, SENTRY_SEND_MILLIS)) : void 0;
+			Promise.all([bounded(sdkShutdown, DEFAULT_TIMEOUT_MILLIS, true), sentry]).then(() => {
+				process.exit(1);
+			});
+		} catch {
+			process.exit(1);
+		}
+	};
+	process.prependListener("uncaughtException", onUncaughtException);
+}
+exports.flush = flush;
+exports.installLifecycle = installLifecycle;
+exports.recordInvocationDeadline = recordInvocationDeadline;
+exports.shutdown = shutdown;
+exports.withFlush = withFlush;

package/dist/lifecycle.d.cts

@@ -0,0 +1,68 @@
+/**
+ * Exports the spans, metrics and log records the SDK has buffered, without stopping it.
+ *
+ * @remarks
+ * Calls `forceFlush` on the global tracer, meter and logger providers. Before `init`, or with
+ * `OTEL_SDK_DISABLED=true`, it resolves at once; after {@link shutdown} it waits for the shutdown.
+ * Failures and timeouts are reported through the OpenTelemetry `diag` logger. Inside a
+ * {@link withFlush} invocation the default bound also ends before the invocation's deadline.
+ *
+ * @param timeoutMillis - Upper bound in milliseconds, 5000 by default; zero, negative and NaN
+ *   mean the default.
+ * @returns A promise that resolves when every provider has flushed or the bound has passed. It
+ *   never rejects.
+ * @public
+ */
+export declare function flush(timeoutMillis?: number): Promise<void>;
+/**
+ * Flushes and stops the SDK started by `init`; telemetry recorded afterwards is dropped.
+ *
+ * @remarks
+ * Later calls, and the automatic shutdown on `beforeExit`, SIGTERM, SIGINT and uncaught
+ * exceptions, share the first call's work. Scripts that end with `process.exit()`, and app signal
+ * handlers that exit, should await it first, because `process.exit()` skips `beforeExit`.
+ *
+ * @param timeoutMillis - Upper bound in milliseconds, 5000 by default; zero, negative and NaN
+ *   mean the default.
+ * @returns A promise that resolves when the SDK has shut down or the bound has passed. It never
+ *   rejects.
+ * @example
+ * ```ts
+ * process.on('SIGTERM', async () => {
+ *   await server.close();
+ *   await shutdown();
+ *   process.exit(0);
+ * });
+ * ```
+ * @public
+ */
+export declare function shutdown(timeoutMillis?: number): Promise<void>;
+/**
+ * Wraps an async serverless handler so buffered telemetry is exported before each invocation
+ * returns.
+ *
+ * @remarks
+ * Awaits the handler, then {@link flush} in a `finally` block, so telemetry is also exported when
+ * the handler throws. Flushes during the invocation end 500 ms before its deadline
+ * (`context.getRemainingTimeInMillis()`). On its first call it installs console capture again if
+ * the AWS Lambda runtime replaced the console methods after the preload ran. Callback-style
+ * handlers are not supported.
+ *
+ * @typeParam E - The invocation event type.
+ * @typeParam C - The runtime context type, for example the AWS Lambda `Context`.
+ * @typeParam R - The value the handler's promise resolves to.
+ * @param handler - The async handler to wrap.
+ * @returns A handler with the same parameters and result.
+ * @example
+ * With `NODE_OPTIONS=--import @clickhouse/clickstack-node/register` set on the function:
+ * ```ts
+ * import { withFlush } from '@clickhouse/clickstack-node';
+ *
+ * export const handler = withFlush(async (event: { name?: string }) => {
+ *   console.log('greeting', event.name);
+ *   return { statusCode: 200, body: 'ok' };
+ * });
+ * ```
+ * @public
+ */
+export declare function withFlush<E, C, R>(handler: (event: E, context: C) => Promise<R>): (event: E, context: C) => Promise<R>;

package/dist/lifecycle.d.mts

@@ -0,0 +1,68 @@
+/**
+ * Exports the spans, metrics and log records the SDK has buffered, without stopping it.
+ *
+ * @remarks
+ * Calls `forceFlush` on the global tracer, meter and logger providers. Before `init`, or with
+ * `OTEL_SDK_DISABLED=true`, it resolves at once; after {@link shutdown} it waits for the shutdown.
+ * Failures and timeouts are reported through the OpenTelemetry `diag` logger. Inside a
+ * {@link withFlush} invocation the default bound also ends before the invocation's deadline.
+ *
+ * @param timeoutMillis - Upper bound in milliseconds, 5000 by default; zero, negative and NaN
+ *   mean the default.
+ * @returns A promise that resolves when every provider has flushed or the bound has passed. It
+ *   never rejects.
+ * @public
+ */
+export declare function flush(timeoutMillis?: number): Promise<void>;
+/**
+ * Flushes and stops the SDK started by `init`; telemetry recorded afterwards is dropped.
+ *
+ * @remarks
+ * Later calls, and the automatic shutdown on `beforeExit`, SIGTERM, SIGINT and uncaught
+ * exceptions, share the first call's work. Scripts that end with `process.exit()`, and app signal
+ * handlers that exit, should await it first, because `process.exit()` skips `beforeExit`.
+ *
+ * @param timeoutMillis - Upper bound in milliseconds, 5000 by default; zero, negative and NaN
+ *   mean the default.
+ * @returns A promise that resolves when the SDK has shut down or the bound has passed. It never
+ *   rejects.
+ * @example
+ * ```ts
+ * process.on('SIGTERM', async () => {
+ *   await server.close();
+ *   await shutdown();
+ *   process.exit(0);
+ * });
+ * ```
+ * @public
+ */
+export declare function shutdown(timeoutMillis?: number): Promise<void>;
+/**
+ * Wraps an async serverless handler so buffered telemetry is exported before each invocation
+ * returns.
+ *
+ * @remarks
+ * Awaits the handler, then {@link flush} in a `finally` block, so telemetry is also exported when
+ * the handler throws. Flushes during the invocation end 500 ms before its deadline
+ * (`context.getRemainingTimeInMillis()`). On its first call it installs console capture again if
+ * the AWS Lambda runtime replaced the console methods after the preload ran. Callback-style
+ * handlers are not supported.
+ *
+ * @typeParam E - The invocation event type.
+ * @typeParam C - The runtime context type, for example the AWS Lambda `Context`.
+ * @typeParam R - The value the handler's promise resolves to.
+ * @param handler - The async handler to wrap.
+ * @returns A handler with the same parameters and result.
+ * @example
+ * With `NODE_OPTIONS=--import @clickhouse/clickstack-node/register` set on the function:
+ * ```ts
+ * import { withFlush } from '@clickhouse/clickstack-node';
+ *
+ * export const handler = withFlush(async (event: { name?: string }) => {
+ *   console.log('greeting', event.name);
+ *   return { statusCode: 200, body: 'ok' };
+ * });
+ * ```
+ * @public
+ */
+export declare function withFlush<E, C, R>(handler: (event: E, context: C) => Promise<R>): (event: E, context: C) => Promise<R>;

package/dist/lifecycle.mjs

@@ -0,0 +1,245 @@
+import { getState } from "./state.mjs";
+import { report } from "./env.mjs";
+import { isMainThread } from "node:worker_threads";
+import { metrics, trace } from "@opentelemetry/api";
+import { getStringFromEnv } from "@opentelemetry/core";
+import { inspect } from "node:util";
+import { constants } from "node:os";
+import { logs } from "@opentelemetry/api-logs";
+// src/lifecycle.ts
+const DEFAULT_TIMEOUT_MILLIS = 5e3;
+const SENTRY_SEND_MILLIS = 2e3;
+const INVOCATION_MARGIN_MILLIS = 500;
+const SIGNALS = ["SIGTERM", "SIGINT"];
+function bounded(work, ms, keepAlive) {
+	let timer;
+	const deadline = new Promise((resolve) => {
+		timer = setTimeout(resolve, ms, false);
+		if (!keepAlive) timer.unref();
+	});
+	const settled = Promise.resolve().then(work).then(() => true);
+	return Promise.race([settled, deadline]).then((inTime) => {
+		clearTimeout(timer);
+		if (!inTime) report("warn", `flush or shutdown did not finish within ${String(ms)} ms`);
+		return inTime;
+	});
+}
+function timeoutOf(timeoutMillis) {
+	if (timeoutMillis !== void 0 && timeoutMillis > 0) return Math.min(timeoutMillis, 2147483647);
+	const deadline = getState().invocationDeadline;
+	return deadline === void 0 ? DEFAULT_TIMEOUT_MILLIS : Math.max(1, Math.min(DEFAULT_TIMEOUT_MILLIS, deadline - Date.now()));
+}
+function sdkShutdown() {
+	const state = getState();
+	const sdk = state.sdk;
+	if (sdk === void 0) return Promise.resolve();
+	return state.shutdownPromise ??= (async () => {
+		await state.flushInFlight;
+		try {
+			await sdk.shutdown();
+		} catch (error) {
+			report("warn", "shutdown failed", error);
+		}
+		state.unsubscribeUndici?.();
+	})();
+}
+/**
+* Records when the current AWS Lambda invocation must return, so flushes end in time.
+*
+* @param context - The invocation context; anything without `getRemainingTimeInMillis` is ignored.
+*/
+function recordInvocationDeadline(context) {
+	const remaining = context?.getRemainingTimeInMillis?.();
+	if (typeof remaining === "number") getState().invocationDeadline = Date.now() + remaining - INVOCATION_MARGIN_MILLIS;
+}
+/**
+* Exports the spans, metrics and log records the SDK has buffered, without stopping it.
+*
+* @remarks
+* Calls `forceFlush` on the global tracer, meter and logger providers. Before `init`, or with
+* `OTEL_SDK_DISABLED=true`, it resolves at once; after {@link shutdown} it waits for the shutdown.
+* Failures and timeouts are reported through the OpenTelemetry `diag` logger. Inside a
+* {@link withFlush} invocation the default bound also ends before the invocation's deadline.
+*
+* @param timeoutMillis - Upper bound in milliseconds, 5000 by default; zero, negative and NaN
+*   mean the default.
+* @returns A promise that resolves when every provider has flushed or the bound has passed. It
+*   never rejects.
+* @public
+*/
+async function flush(timeoutMillis) {
+	const state = getState();
+	if (state.sdk === void 0) return;
+	const ms = timeoutOf(timeoutMillis);
+	const pending = state.shutdownPromise;
+	if (pending !== void 0) {
+		await bounded(() => pending, ms, false);
+		return;
+	}
+	const tracer = trace.getTracerProvider();
+	const providers = [
+		tracer.getDelegate?.() ?? tracer,
+		metrics.getMeterProvider(),
+		logs.getLoggerProvider()
+	];
+	const work = Promise.all(providers.map(async (provider) => {
+		const p = provider;
+		if (typeof p.forceFlush !== "function") return;
+		try {
+			await p.forceFlush({ timeoutMillis: ms });
+		} catch (error) {
+			report("warn", "flush failed", error);
+		}
+	}));
+	state.flushInFlight = Promise.all([state.flushInFlight, work]);
+	await bounded(() => work, ms, false);
+}
+/**
+* Flushes and stops the SDK started by `init`; telemetry recorded afterwards is dropped.
+*
+* @remarks
+* Later calls, and the automatic shutdown on `beforeExit`, SIGTERM, SIGINT and uncaught
+* exceptions, share the first call's work. Scripts that end with `process.exit()`, and app signal
+* handlers that exit, should await it first, because `process.exit()` skips `beforeExit`.
+*
+* @param timeoutMillis - Upper bound in milliseconds, 5000 by default; zero, negative and NaN
+*   mean the default.
+* @returns A promise that resolves when the SDK has shut down or the bound has passed. It never
+*   rejects.
+* @example
+* ```ts
+* process.on('SIGTERM', async () => {
+*   await server.close();
+*   await shutdown();
+*   process.exit(0);
+* });
+* ```
+* @public
+*/
+async function shutdown(timeoutMillis) {
+	if (getState().sdk === void 0) return;
+	await bounded(sdkShutdown, timeoutOf(timeoutMillis), false);
+}
+/**
+* Wraps an async serverless handler so buffered telemetry is exported before each invocation
+* returns.
+*
+* @remarks
+* Awaits the handler, then {@link flush} in a `finally` block, so telemetry is also exported when
+* the handler throws. Flushes during the invocation end 500 ms before its deadline
+* (`context.getRemainingTimeInMillis()`). On its first call it installs console capture again if
+* the AWS Lambda runtime replaced the console methods after the preload ran. Callback-style
+* handlers are not supported.
+*
+* @typeParam E - The invocation event type.
+* @typeParam C - The runtime context type, for example the AWS Lambda `Context`.
+* @typeParam R - The value the handler's promise resolves to.
+* @param handler - The async handler to wrap.
+* @returns A handler with the same parameters and result.
+* @example
+* With `NODE_OPTIONS=--import @clickhouse/clickstack-node/register` set on the function:
+* ```ts
+* import { withFlush } from '@clickhouse/clickstack-node';
+*
+* export const handler = withFlush(async (event: { name?: string }) => {
+*   console.log('greeting', event.name);
+*   return { statusCode: 200, body: 'ok' };
+* });
+* ```
+* @public
+*/
+function withFlush(handler) {
+	let firstCall = true;
+	return async function flushingHandler(event, context) {
+		const state = getState();
+		try {
+			recordInvocationDeadline(context);
+			if (firstCall) {
+				firstCall = false;
+				const current = console.log;
+				if (state.repatchConsole !== void 0 && current !== state.consoleLog) {
+					state.repatchConsole();
+					state.consoleLog = console.log;
+				}
+			}
+		} catch (error) {
+			report("warn", "could not prepare the invocation", error);
+		}
+		try {
+			return await handler(event, context);
+		} finally {
+			await flush();
+		}
+	};
+}
+function writeFatal(error) {
+	try {
+		const body = typeof error === "string" ? error : inspect(error, {
+			customInspect: false,
+			depth: 5
+		});
+		process.getBuiltinModule("node:fs").writeSync(2, `${body}\n\nNode.js ${process.version}\n`);
+	} catch {}
+}
+function signalExitListeners() {
+	const v4 = globalThis[Symbol.for("signal-exit emitter")];
+	const v3 = process.__signal_exit_emitter__;
+	return [v4?.count, v3?.count].reduce((sum, count) => sum + (typeof count === "number" ? count : 0), 0);
+}
+/**
+* Installs the `beforeExit`, SIGTERM, SIGINT and `uncaughtException` handlers, once per thread.
+* Signal and crash handlers go on the main thread only: workers never receive signals, and a
+* worker crash listener would hide the parent's `error` event.
+*/
+function installLifecycle() {
+	let terminating = false;
+	let terminatingSince = 0;
+	if (getStringFromEnv("AWS_LAMBDA_FUNCTION_NAME") === void 0) process.once("beforeExit", () => {
+		if (terminating) return;
+		bounded(sdkShutdown, DEFAULT_TIMEOUT_MILLIS, false).then((inTime) => {
+			if (!inTime) process.exit();
+		});
+	});
+	if (!isMainThread) return;
+	const onSignal = (signal) => {
+		if (terminating) {
+			if (Date.now() - terminatingSince > 1e3) process.exit(128 + constants.signals[signal]);
+			return;
+		}
+		if (process.listeners(signal).filter((listener) => listener !== onSignal).length > signalExitListeners()) {
+			process.removeListener(signal, onSignal);
+			flush();
+			return;
+		}
+		terminating = true;
+		terminatingSince = Date.now();
+		bounded(sdkShutdown, DEFAULT_TIMEOUT_MILLIS, true).then(() => {
+			for (const name of SIGNALS) process.removeListener(name, onSignal);
+			try {
+				process.kill(process.pid, signal);
+			} catch {}
+			process.exit(128 + constants.signals[signal]);
+		});
+	};
+	for (const signal of SIGNALS) process.prependListener(signal, onSignal);
+	const onUncaughtException = (error) => {
+		try {
+			const listeners = process.listeners("uncaughtException");
+			const isSentry = (listener) => "_errorHandler" in listener && listener._errorHandler === true;
+			if (listeners.some((listener) => listener !== onUncaughtException && listener.name !== "domainUncaughtExceptionClear" && !isSentry(listener))) return;
+			process.exitCode = 1;
+			if (terminating) return;
+			writeFatal(error);
+			terminating = true;
+			terminatingSince = Date.now();
+			const sentry = listeners.some(isSentry) ? new Promise((resolve) => setTimeout(resolve, SENTRY_SEND_MILLIS)) : void 0;
+			Promise.all([bounded(sdkShutdown, DEFAULT_TIMEOUT_MILLIS, true), sentry]).then(() => {
+				process.exit(1);
+			});
+		} catch {
+			process.exit(1);
+		}
+	};
+	process.prependListener("uncaughtException", onUncaughtException);
+}
+export { flush, installLifecycle, recordInvocationDeadline, shutdown, withFlush };

package/dist/register.cjs

@@ -0,0 +1,12 @@
+const require_init = require("./init.cjs");
+// src/register.ts
+/**
+* Zero-code entry: starts the SDK from environment variables only, as `init()` without options.
+* Worker threads are skipped; call `init()` inside a worker to instrument it.
+*
+* @example
+* ```sh
+* NODE_OPTIONS="--import @clickhouse/clickstack-node/register" node app.mjs
+* ```
+*/
+if (require("node:worker_threads").isMainThread) require_init.init();

package/dist/register.d.cts

@@ -0,0 +1 @@
+export {}

package/dist/register.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/register.mjs

@@ -0,0 +1,14 @@
+import { init } from "./init.mjs";
+import { isMainThread } from "node:worker_threads";
+// src/register.ts
+/**
+* Zero-code entry: starts the SDK from environment variables only, as `init()` without options.
+* Worker threads are skipped; call `init()` inside a worker to instrument it.
+*
+* @example
+* ```sh
+* NODE_OPTIONS="--import @clickhouse/clickstack-node/register" node app.mjs
+* ```
+*/
+if (isMainThread) init();
+export {};

package/dist/semconv.cjs

@@ -0,0 +1,16 @@
+// src/semconv.ts
+/** `http.request.body.size`: semantic-conventions v1.43.0, development. */
+const ATTR_HTTP_REQUEST_BODY_SIZE = "http.request.body.size";
+/** `http.response.body.size`: semantic-conventions v1.43.0, development. */
+const ATTR_HTTP_RESPONSE_BODY_SIZE = "http.response.body.size";
+/**
+* `http.request.body.content`: development. Added on semantic-conventions `main`
+* by PR #3521 (commit bcd7e291081f, 2026-08-14); not in a release as of v1.44.0.
+*/
+const ATTR_HTTP_REQUEST_BODY_CONTENT = "http.request.body.content";
+/** `http.response.body.content`: same source as {@link ATTR_HTTP_REQUEST_BODY_CONTENT}. */
+const ATTR_HTTP_RESPONSE_BODY_CONTENT = "http.response.body.content";
+exports.ATTR_HTTP_REQUEST_BODY_CONTENT = ATTR_HTTP_REQUEST_BODY_CONTENT;
+exports.ATTR_HTTP_REQUEST_BODY_SIZE = ATTR_HTTP_REQUEST_BODY_SIZE;
+exports.ATTR_HTTP_RESPONSE_BODY_CONTENT = ATTR_HTTP_RESPONSE_BODY_CONTENT;
+exports.ATTR_HTTP_RESPONSE_BODY_SIZE = ATTR_HTTP_RESPONSE_BODY_SIZE;