@clickhouse/clickstack-node 0.0.0-stage → 1.0.0

package/dist/body/undici.mjs

@@ -0,0 +1,87 @@
+import { warnOnce } from "../env.mjs";
+import { BodyCapture, headerMap, reportFailure, responseHasNoBody } from "./rules.mjs";
+import { subscribe, unsubscribe } from "node:diagnostics_channel";
+// src/body/undici.ts
+const side = (headers, contentLength) => ({
+	capture: new BodyCapture(),
+	meta: {
+		contentType: headers.get("content-type"),
+		contentEncoding: headers.get("content-encoding"),
+		contentLength
+	}
+});
+/**
+* Tells whether the undici that Node bundles publishes the body diagnostics channels.
+*
+* @returns `true` from undici 7.11, which Node bundles from 24.4.
+*/
+function hasBodyChannels() {
+	const [major = 0, minor = 0] = (process.versions["undici"] ?? "0").split(".").map(Number);
+	return major > 7 || major === 7 && minor >= 11;
+}
+/**
+* Creates the fetch body capture from the undici body diagnostics channels, which Node bundles
+* from 24.4 (undici 7.11). Call it before `instrumentation-undici` is constructed: that
+* instrumentation ends the span in its own trailers and error subscribers, and subscribers run
+* in subscription order, so ours must come first to write while the span is open.
+*
+* @returns The capture, or `undefined` (with one warning) when this Node has no body channels.
+*/
+function createUndiciBodyCapture() {
+	if (!hasBodyChannels()) {
+		warnOnce("undici-bodies", `fetch bodies are captured from Node.js 24.4; ${process.version} has no undici body channels`);
+		return;
+	}
+	const exchanges = /* @__PURE__ */ new WeakMap();
+	const listeners = [];
+	const listen = (name, handle) => {
+		const listener = (message) => {
+			try {
+				const { request } = message;
+				handle(request, message);
+			} catch (err) {
+				reportFailure(err);
+			}
+		};
+		subscribe(name, listener);
+		listeners.push([name, listener]);
+	};
+	const chunk = (direction) => (request, message) => {
+		exchanges.get(request)?.[direction]?.capture.add(message.chunk);
+	};
+	const finish = (cut) => (request) => {
+		const ex = exchanges.get(request);
+		exchanges.delete(request);
+		if (!ex?.span.isRecording()) return;
+		for (const direction of ["request", "response"]) {
+			const s = ex[direction];
+			if (s !== void 0) ex.span.setAttributes(s.capture.attributes(direction, {
+				...s.meta,
+				complete: !cut
+			}));
+		}
+	};
+	listen("undici:request:bodyChunkSent", chunk("request"));
+	listen("undici:request:bodyChunkReceived", chunk("response"));
+	listen("undici:request:trailers", finish(false));
+	listen("undici:request:error", finish(true));
+	return {
+		requestHook(span, request) {
+			if (!span.isRecording()) return;
+			exchanges.set(request, {
+				span,
+				request: side(headerMap(request.headers), request.contentLength)
+			});
+		},
+		responseHook(_span, { request, response }) {
+			const ex = exchanges.get(request);
+			if (ex === void 0 || responseHasNoBody(request.method, response.statusCode)) return;
+			const headers = headerMap(response.headers);
+			ex.response = side(headers, headers.get("content-length"));
+		},
+		unsubscribe() {
+			for (const [name, listener] of listeners) unsubscribe(name, listener);
+		}
+	};
+}
+export { createUndiciBodyCapture, hasBodyChannels };

package/dist/compose.cjs

@@ -0,0 +1,107 @@
+const require_env = require("./env.cjs");
+const require_rules = require("./body/rules.cjs");
+const require_http = require("./body/http.cjs");
+const require_undici = require("./body/undici.cjs");
+const require_lifecycle = require("./lifecycle.cjs");
+let _opentelemetry_core = require("@opentelemetry/core");
+// src/compose.ts
+const HTTP = "@opentelemetry/instrumentation-http";
+const UNDICI = "@opentelemetry/instrumentation-undici";
+const LAMBDA = "@opentelemetry/instrumentation-aws-lambda";
+const HEADERS_ENV = "OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_";
+const SANITIZE_DEFAULT = [
+	"authorization",
+	"cookie",
+	"set-cookie",
+	"proxy-authorization",
+	"x-api-key"
+];
+function chain(ours, user) {
+	return function(...args) {
+		try {
+			ours(...args);
+		} catch (err) {
+			require_rules.reportFailure(err);
+		}
+		user?.apply(this, args);
+	};
+}
+/**
+* Returns a copy of the user's instrumentation config with the header lists from
+* `OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_*` and, when body capture is on, our body hooks
+* merged into the http and undici entries, and a hook that records each AWS Lambda invocation's
+* deadline. The bundle passes each entry to the instrumentation
+* constructor as is, so this is the only place to merge.
+*
+* @param user - The `instrumentations` option.
+* @param bodies - Whether body capture is on.
+* @returns The composed map and the fetch body unsubscribe function, if any.
+*/
+function composeInstrumentationConfig(user, bodies) {
+	const sanitize = new Set(((0, _opentelemetry_core.getStringListFromEnv)(`${HEADERS_ENV}SANITIZE_FIELDS`) ?? SANITIZE_DEFAULT).map((n) => n.toLowerCase()));
+	const names = (list, code) => {
+		const all = [...(0, _opentelemetry_core.getStringListFromEnv)(HEADERS_ENV + list) ?? [], ...code ?? []];
+		const kept = /* @__PURE__ */ new Set();
+		for (const name of all.map((n) => n.toLowerCase())) if (!sanitize.has(name)) kept.add(name);
+		else require_env.warnOnce(`sanitized:${name}`, `header "${name}" is on the sanitize list and is not captured`);
+		return [...kept];
+	};
+	const http = user?.[HTTP] ?? {};
+	const hh = http.headersToSpanAttributes;
+	const httpEntry = {
+		...http,
+		headersToSpanAttributes: {
+			server: {
+				requestHeaders: names("SERVER_REQUEST", hh?.server?.requestHeaders),
+				responseHeaders: names("SERVER_RESPONSE", hh?.server?.responseHeaders)
+			},
+			client: {
+				requestHeaders: names("CLIENT_REQUEST", hh?.client?.requestHeaders),
+				responseHeaders: names("CLIENT_RESPONSE", hh?.client?.responseHeaders)
+			}
+		}
+	};
+	const undici = user?.[UNDICI] ?? {};
+	const uh = undici.headersToSpanAttributes;
+	const requestHeaders = names("CLIENT_REQUEST", uh?.requestHeaders);
+	const responseHeaders = names("CLIENT_RESPONSE", uh?.responseHeaders);
+	const undiciEntry = {
+		...undici,
+		headersToSpanAttributes: {
+			...requestHeaders.length > 0 ? { requestHeaders } : {},
+			...responseHeaders.length > 0 ? { responseHeaders } : {}
+		}
+	};
+	let unsubscribe;
+	if (bodies) {
+		const hooks = require_http.createHttpBodyHooks();
+		httpEntry.requestHook = chain(hooks.requestHook, http.requestHook);
+		httpEntry.responseHook = chain(hooks.responseHook, http.responseHook);
+		httpEntry.applyCustomAttributesOnSpan = chain((span) => {
+			hooks.finalize(span);
+		}, http.applyCustomAttributesOnSpan);
+		const fetchBodies = require_undici.createUndiciBodyCapture();
+		if (fetchBodies !== void 0) {
+			undiciEntry.requestHook = chain(fetchBodies.requestHook, undici.requestHook);
+			undiciEntry.responseHook = chain(fetchBodies.responseHook, undici.responseHook);
+			unsubscribe = fetchBodies.unsubscribe;
+		}
+	}
+	const lambda = user?.[LAMBDA] ?? {};
+	const lambdaEntry = {
+		...lambda,
+		requestHook: chain((_span, { context }) => {
+			require_lifecycle.recordInvocationDeadline(context);
+		}, lambda.requestHook)
+	};
+	return {
+		map: {
+			...user,
+			[HTTP]: httpEntry,
+			[UNDICI]: undiciEntry,
+			[LAMBDA]: lambdaEntry
+		},
+		unsubscribe
+	};
+}
+exports.composeInstrumentationConfig = composeInstrumentationConfig;

package/dist/compose.mjs

@@ -0,0 +1,107 @@
+import { warnOnce } from "./env.mjs";
+import { reportFailure } from "./body/rules.mjs";
+import { createHttpBodyHooks } from "./body/http.mjs";
+import { createUndiciBodyCapture } from "./body/undici.mjs";
+import { recordInvocationDeadline } from "./lifecycle.mjs";
+import { getStringListFromEnv } from "@opentelemetry/core";
+// src/compose.ts
+const HTTP = "@opentelemetry/instrumentation-http";
+const UNDICI = "@opentelemetry/instrumentation-undici";
+const LAMBDA = "@opentelemetry/instrumentation-aws-lambda";
+const HEADERS_ENV = "OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_";
+const SANITIZE_DEFAULT = [
+	"authorization",
+	"cookie",
+	"set-cookie",
+	"proxy-authorization",
+	"x-api-key"
+];
+function chain(ours, user) {
+	return function(...args) {
+		try {
+			ours(...args);
+		} catch (err) {
+			reportFailure(err);
+		}
+		user?.apply(this, args);
+	};
+}
+/**
+* Returns a copy of the user's instrumentation config with the header lists from
+* `OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_*` and, when body capture is on, our body hooks
+* merged into the http and undici entries, and a hook that records each AWS Lambda invocation's
+* deadline. The bundle passes each entry to the instrumentation
+* constructor as is, so this is the only place to merge.
+*
+* @param user - The `instrumentations` option.
+* @param bodies - Whether body capture is on.
+* @returns The composed map and the fetch body unsubscribe function, if any.
+*/
+function composeInstrumentationConfig(user, bodies) {
+	const sanitize = new Set((getStringListFromEnv(`${HEADERS_ENV}SANITIZE_FIELDS`) ?? SANITIZE_DEFAULT).map((n) => n.toLowerCase()));
+	const names = (list, code) => {
+		const all = [...getStringListFromEnv(HEADERS_ENV + list) ?? [], ...code ?? []];
+		const kept = /* @__PURE__ */ new Set();
+		for (const name of all.map((n) => n.toLowerCase())) if (!sanitize.has(name)) kept.add(name);
+		else warnOnce(`sanitized:${name}`, `header "${name}" is on the sanitize list and is not captured`);
+		return [...kept];
+	};
+	const http = user?.[HTTP] ?? {};
+	const hh = http.headersToSpanAttributes;
+	const httpEntry = {
+		...http,
+		headersToSpanAttributes: {
+			server: {
+				requestHeaders: names("SERVER_REQUEST", hh?.server?.requestHeaders),
+				responseHeaders: names("SERVER_RESPONSE", hh?.server?.responseHeaders)
+			},
+			client: {
+				requestHeaders: names("CLIENT_REQUEST", hh?.client?.requestHeaders),
+				responseHeaders: names("CLIENT_RESPONSE", hh?.client?.responseHeaders)
+			}
+		}
+	};
+	const undici = user?.[UNDICI] ?? {};
+	const uh = undici.headersToSpanAttributes;
+	const requestHeaders = names("CLIENT_REQUEST", uh?.requestHeaders);
+	const responseHeaders = names("CLIENT_RESPONSE", uh?.responseHeaders);
+	const undiciEntry = {
+		...undici,
+		headersToSpanAttributes: {
+			...requestHeaders.length > 0 ? { requestHeaders } : {},
+			...responseHeaders.length > 0 ? { responseHeaders } : {}
+		}
+	};
+	let unsubscribe;
+	if (bodies) {
+		const hooks = createHttpBodyHooks();
+		httpEntry.requestHook = chain(hooks.requestHook, http.requestHook);
+		httpEntry.responseHook = chain(hooks.responseHook, http.responseHook);
+		httpEntry.applyCustomAttributesOnSpan = chain((span) => {
+			hooks.finalize(span);
+		}, http.applyCustomAttributesOnSpan);
+		const fetchBodies = createUndiciBodyCapture();
+		if (fetchBodies !== void 0) {
+			undiciEntry.requestHook = chain(fetchBodies.requestHook, undici.requestHook);
+			undiciEntry.responseHook = chain(fetchBodies.responseHook, undici.responseHook);
+			unsubscribe = fetchBodies.unsubscribe;
+		}
+	}
+	const lambda = user?.[LAMBDA] ?? {};
+	const lambdaEntry = {
+		...lambda,
+		requestHook: chain((_span, { context }) => {
+			recordInvocationDeadline(context);
+		}, lambda.requestHook)
+	};
+	return {
+		map: {
+			...user,
+			[HTTP]: httpEntry,
+			[UNDICI]: undiciEntry,
+			[LAMBDA]: lambdaEntry
+		},
+		unsubscribe
+	};
+}
+export { composeInstrumentationConfig };

package/dist/config.cjs

@@ -0,0 +1,27 @@
+const require_env = require("./env.cjs");
+let _opentelemetry_core = require("@opentelemetry/core");
+// src/config.ts
+const HEADERS = "OTEL_EXPORTER_OTLP_HEADERS";
+/**
+* Writes the options that have an environment variable to `process.env` where it is unset.
+*
+* @param options - The `init` options.
+*/
+function applyOptions(options) {
+	if (!((0, _opentelemetry_core.getStringFromEnv)("OTEL_RESOURCE_ATTRIBUTES") ?? "").split(",").some((a) => a.split("=")[0]?.trim() === "service.name")) require_env.setDefault("OTEL_SERVICE_NAME", options.serviceName);
+	require_env.setDefault("OTEL_EXPORTER_OTLP_ENDPOINT", options.endpoint);
+	if (options.httpBodyCapture !== void 0) require_env.setDefault("CLICKSTACK_CAPTURE_HTTP_BODY", String(options.httpBodyCapture));
+	const apiKey = options.apiKey?.trim();
+	if (!apiKey) return;
+	const header = `authorization=${encodeURIComponent(apiKey)}`;
+	const current = (0, _opentelemetry_core.getStringFromEnv)(HEADERS);
+	if (current !== void 0 && current !== header) require_env.warnOnce("api-key", `${HEADERS} is set, so the apiKey option is ignored`);
+	require_env.setDefault(HEADERS, header);
+	if ([
+		"",
+		"_TRACES",
+		"_METRICS",
+		"_LOGS"
+	].every((s) => (0, _opentelemetry_core.getStringFromEnv)(`OTEL_EXPORTER_OTLP${s}_ENDPOINT`) === void 0)) require_env.warnOnce("no-endpoint", "apiKey is set but OTEL_EXPORTER_OTLP_ENDPOINT is not");
+}
+exports.applyOptions = applyOptions;

package/dist/config.d.cts

@@ -0,0 +1,61 @@
+import { InstrumentationConfigMap } from "@opentelemetry/auto-instrumentations-node";
+import { Instrumentation } from "@opentelemetry/instrumentation";
+/**
+ * Options for `init`. Options with an environment variable are written to `process.env` only
+ * when that variable is unset, so an operator's setting always wins and child processes inherit
+ * the value. Every other setting comes from the standard `OTEL_*` variables.
+ *
+ * @public
+ */
+export interface ClickStackNodeOptions {
+  /**
+   * The `service.name` resource attribute. Written to `OTEL_SERVICE_NAME`, unless
+   * `OTEL_RESOURCE_ATTRIBUTES` sets `service.name`.
+   *
+   * @defaultValue upstream: `unknown_service:` followed by the Node.js executable name
+   */
+  serviceName?: string | undefined;
+  /**
+   * Base URL of the OTLP/HTTP receiver, without `/v1/traces`. Written to
+   * `OTEL_EXPORTER_OTLP_ENDPOINT`.
+   *
+   * @defaultValue upstream: `http://localhost:4318`
+   */
+  endpoint?: string | undefined;
+  /**
+   * `deployment.environment.name`, such as `production` or `staging`. Set on the resource, not
+   * written to the environment. A value for the same key in `OTEL_RESOURCE_ATTRIBUTES` wins.
+   *
+   * @defaultValue none
+   */
+  environment?: string | undefined;
+  /**
+   * ClickStack ingestion key, sent as the `authorization` header. Trimmed, percent-encoded and
+   * written to `OTEL_EXPORTER_OTLP_HEADERS` as `authorization=<key>`. Ignored with one warning
+   * when that variable already holds something else.
+   *
+   * @defaultValue none
+   */
+  apiKey?: string | undefined;
+  /**
+   * Records HTTP request and response bodies on `node:http` spans, and on `fetch` spans from
+   * Node.js 24.4. Bodies can contain personal data and add storage cost. Written to
+   * `CLICKSTACK_CAPTURE_HTTP_BODY`.
+   *
+   * @defaultValue `false`
+   */
+  httpBodyCapture?: boolean | undefined;
+  /**
+   * Configuration for the auto-instrumentations bundle, in the shape of
+   * `getNodeAutoInstrumentations()`. Hooks given here run after this package's hooks.
+   *
+   * @defaultValue `{}`
+   */
+  instrumentations?: InstrumentationConfigMap | undefined;
+  /**
+   * Instrumentation instances to add to the bundle's, for libraries the bundle does not cover.
+   *
+   * @defaultValue `[]`
+   */
+  additionalInstrumentations?: Instrumentation[] | undefined;
+}

package/dist/config.d.mts

@@ -0,0 +1,61 @@
+import { InstrumentationConfigMap } from "@opentelemetry/auto-instrumentations-node";
+import { Instrumentation } from "@opentelemetry/instrumentation";
+/**
+ * Options for `init`. Options with an environment variable are written to `process.env` only
+ * when that variable is unset, so an operator's setting always wins and child processes inherit
+ * the value. Every other setting comes from the standard `OTEL_*` variables.
+ *
+ * @public
+ */
+export interface ClickStackNodeOptions {
+  /**
+   * The `service.name` resource attribute. Written to `OTEL_SERVICE_NAME`, unless
+   * `OTEL_RESOURCE_ATTRIBUTES` sets `service.name`.
+   *
+   * @defaultValue upstream: `unknown_service:` followed by the Node.js executable name
+   */
+  serviceName?: string | undefined;
+  /**
+   * Base URL of the OTLP/HTTP receiver, without `/v1/traces`. Written to
+   * `OTEL_EXPORTER_OTLP_ENDPOINT`.
+   *
+   * @defaultValue upstream: `http://localhost:4318`
+   */
+  endpoint?: string | undefined;
+  /**
+   * `deployment.environment.name`, such as `production` or `staging`. Set on the resource, not
+   * written to the environment. A value for the same key in `OTEL_RESOURCE_ATTRIBUTES` wins.
+   *
+   * @defaultValue none
+   */
+  environment?: string | undefined;
+  /**
+   * ClickStack ingestion key, sent as the `authorization` header. Trimmed, percent-encoded and
+   * written to `OTEL_EXPORTER_OTLP_HEADERS` as `authorization=<key>`. Ignored with one warning
+   * when that variable already holds something else.
+   *
+   * @defaultValue none
+   */
+  apiKey?: string | undefined;
+  /**
+   * Records HTTP request and response bodies on `node:http` spans, and on `fetch` spans from
+   * Node.js 24.4. Bodies can contain personal data and add storage cost. Written to
+   * `CLICKSTACK_CAPTURE_HTTP_BODY`.
+   *
+   * @defaultValue `false`
+   */
+  httpBodyCapture?: boolean | undefined;
+  /**
+   * Configuration for the auto-instrumentations bundle, in the shape of
+   * `getNodeAutoInstrumentations()`. Hooks given here run after this package's hooks.
+   *
+   * @defaultValue `{}`
+   */
+  instrumentations?: InstrumentationConfigMap | undefined;
+  /**
+   * Instrumentation instances to add to the bundle's, for libraries the bundle does not cover.
+   *
+   * @defaultValue `[]`
+   */
+  additionalInstrumentations?: Instrumentation[] | undefined;
+}

package/dist/config.mjs

@@ -0,0 +1,27 @@
+import { setDefault, warnOnce } from "./env.mjs";
+import { getStringFromEnv } from "@opentelemetry/core";
+// src/config.ts
+const HEADERS = "OTEL_EXPORTER_OTLP_HEADERS";
+/**
+* Writes the options that have an environment variable to `process.env` where it is unset.
+*
+* @param options - The `init` options.
+*/
+function applyOptions(options) {
+	if (!(getStringFromEnv("OTEL_RESOURCE_ATTRIBUTES") ?? "").split(",").some((a) => a.split("=")[0]?.trim() === "service.name")) setDefault("OTEL_SERVICE_NAME", options.serviceName);
+	setDefault("OTEL_EXPORTER_OTLP_ENDPOINT", options.endpoint);
+	if (options.httpBodyCapture !== void 0) setDefault("CLICKSTACK_CAPTURE_HTTP_BODY", String(options.httpBodyCapture));
+	const apiKey = options.apiKey?.trim();
+	if (!apiKey) return;
+	const header = `authorization=${encodeURIComponent(apiKey)}`;
+	const current = getStringFromEnv(HEADERS);
+	if (current !== void 0 && current !== header) warnOnce("api-key", `${HEADERS} is set, so the apiKey option is ignored`);
+	setDefault(HEADERS, header);
+	if ([
+		"",
+		"_TRACES",
+		"_METRICS",
+		"_LOGS"
+	].every((s) => getStringFromEnv(`OTEL_EXPORTER_OTLP${s}_ENDPOINT`) === void 0)) warnOnce("no-endpoint", "apiKey is set but OTEL_EXPORTER_OTLP_ENDPOINT is not");
+}
+export { applyOptions };

package/dist/env.cjs

@@ -0,0 +1,88 @@
+const require_state = require("./state.cjs");
+let _opentelemetry_api = require("@opentelemetry/api");
+let _opentelemetry_core = require("@opentelemetry/core");
+// src/env.ts
+const API_REGISTRY = Symbol.for("opentelemetry.js.api.1");
+/**
+* Returns the global registry of `@opentelemetry/api`, shared by every copy of the api.
+*
+* @returns The registered APIs, such as `diag` and `trace`, or `undefined` when none is.
+*/
+function apiRegistry() {
+	return globalThis[API_REGISTRY];
+}
+/**
+* Writes `value` to `process.env[name]` only when the variable is unset or blank, so an
+* operator-set value always wins over a code option.
+*
+* @param name - Environment variable name.
+* @param value - Value to write; `undefined` writes nothing.
+*/
+function setDefault(name, value) {
+	if (value !== void 0 && (0, _opentelemetry_core.getStringFromEnv)(name) === void 0) process.env[name] = value;
+}
+/**
+* Runs `call` so that what it reports through `diag` is printed. Until NodeSDK starts there is no
+* diag logger unless the app installed one, and `diag` would drop everything, so a console logger
+* at `OTEL_LOG_LEVEL` (default warn) is registered for the call and removed, as upstream's own
+* register entry does around the auto-instrumentations bundle.
+*
+* @param call - The work to run.
+* @returns What `call` returns.
+*/
+function withStartupLogger(call) {
+	if (apiRegistry()?.diag !== void 0) return call();
+	const sink = new _opentelemetry_api.DiagConsoleLogger();
+	const logger = {
+		error: (message, ...args) => {
+			if (!message.includes("\"@opentelemetry/instrumentation-console\"")) sink.error(message, ...args);
+		},
+		warn: sink.warn,
+		info: sink.info,
+		debug: sink.debug,
+		verbose: sink.verbose
+	};
+	_opentelemetry_api.diag.setLogger(logger, {
+		logLevel: (0, _opentelemetry_core.diagLogLevelFromString)((0, _opentelemetry_core.getStringFromEnv)("OTEL_LOG_LEVEL")) ?? _opentelemetry_api.DiagLogLevel.WARN,
+		suppressOverrideMessage: true
+	});
+	try {
+		return call();
+	} finally {
+		_opentelemetry_api.diag.disable();
+	}
+}
+/**
+* Writes a message, prefixed with `clickstack-node:`, through `diag`, also before NodeSDK starts.
+* Never throws.
+*
+* @param level - Diag level.
+* @param message - Message without the prefix.
+* @param args - Extra values passed to the logger.
+*/
+function report(level, message, ...args) {
+	try {
+		withStartupLogger(() => {
+			_opentelemetry_api.diag[level](`clickstack-node: ${message}`, ...args);
+		});
+	} catch {}
+}
+/**
+* Reports a warning through {@link report}, once per key per thread.
+*
+* @param key - Deduplication key.
+* @param message - Message without the prefix.
+* @param args - Extra values passed to the logger.
+*/
+function warnOnce(key, message, ...args) {
+	const state = require_state.getState();
+	state.warned ??= /* @__PURE__ */ new Set();
+	if (state.warned.has(key)) return;
+	state.warned.add(key);
+	report("warn", message, ...args);
+}
+exports.apiRegistry = apiRegistry;
+exports.report = report;
+exports.setDefault = setDefault;
+exports.warnOnce = warnOnce;
+exports.withStartupLogger = withStartupLogger;

package/dist/env.mjs

@@ -0,0 +1,84 @@
+import { getState } from "./state.mjs";
+import { DiagConsoleLogger, DiagLogLevel, diag } from "@opentelemetry/api";
+import { diagLogLevelFromString, getStringFromEnv } from "@opentelemetry/core";
+// src/env.ts
+const API_REGISTRY = Symbol.for("opentelemetry.js.api.1");
+/**
+* Returns the global registry of `@opentelemetry/api`, shared by every copy of the api.
+*
+* @returns The registered APIs, such as `diag` and `trace`, or `undefined` when none is.
+*/
+function apiRegistry() {
+	return globalThis[API_REGISTRY];
+}
+/**
+* Writes `value` to `process.env[name]` only when the variable is unset or blank, so an
+* operator-set value always wins over a code option.
+*
+* @param name - Environment variable name.
+* @param value - Value to write; `undefined` writes nothing.
+*/
+function setDefault(name, value) {
+	if (value !== void 0 && getStringFromEnv(name) === void 0) process.env[name] = value;
+}
+/**
+* Runs `call` so that what it reports through `diag` is printed. Until NodeSDK starts there is no
+* diag logger unless the app installed one, and `diag` would drop everything, so a console logger
+* at `OTEL_LOG_LEVEL` (default warn) is registered for the call and removed, as upstream's own
+* register entry does around the auto-instrumentations bundle.
+*
+* @param call - The work to run.
+* @returns What `call` returns.
+*/
+function withStartupLogger(call) {
+	if (apiRegistry()?.diag !== void 0) return call();
+	const sink = new DiagConsoleLogger();
+	const logger = {
+		error: (message, ...args) => {
+			if (!message.includes("\"@opentelemetry/instrumentation-console\"")) sink.error(message, ...args);
+		},
+		warn: sink.warn,
+		info: sink.info,
+		debug: sink.debug,
+		verbose: sink.verbose
+	};
+	diag.setLogger(logger, {
+		logLevel: diagLogLevelFromString(getStringFromEnv("OTEL_LOG_LEVEL")) ?? DiagLogLevel.WARN,
+		suppressOverrideMessage: true
+	});
+	try {
+		return call();
+	} finally {
+		diag.disable();
+	}
+}
+/**
+* Writes a message, prefixed with `clickstack-node:`, through `diag`, also before NodeSDK starts.
+* Never throws.
+*
+* @param level - Diag level.
+* @param message - Message without the prefix.
+* @param args - Extra values passed to the logger.
+*/
+function report(level, message, ...args) {
+	try {
+		withStartupLogger(() => {
+			diag[level](`clickstack-node: ${message}`, ...args);
+		});
+	} catch {}
+}
+/**
+* Reports a warning through {@link report}, once per key per thread.
+*
+* @param key - Deduplication key.
+* @param message - Message without the prefix.
+* @param args - Extra values passed to the logger.
+*/
+function warnOnce(key, message, ...args) {
+	const state = getState();
+	state.warned ??= /* @__PURE__ */ new Set();
+	if (state.warned.has(key)) return;
+	state.warned.add(key);
+	report("warn", message, ...args);
+}
+export { apiRegistry, report, setDefault, warnOnce, withStartupLogger };