@photon-ai/otel 1.0.0 → 2.0.1

package/dist/index.js

@@ -1,324 +1,574 @@
-// src/logger.ts
-import { context as otelContext } from "@opentelemetry/api";
-import { logs, SeverityNumber } from "@opentelemetry/api-logs";
-
-// src/version.ts
-var PHOTON_OTEL_VERSION = "0.1.0";
-
-// src/logger.ts
-var LEVEL_SEVERITY = {
-  debug: SeverityNumber.DEBUG,
-  // 5
-  info: SeverityNumber.INFO,
-  // 9
-  warn: SeverityNumber.WARN,
-  // 13
-  error: SeverityNumber.ERROR,
-  // 17
-  silent: Number.POSITIVE_INFINITY
+import { createRequire } from "node:module";
+import { SpanKind, SpanStatusCode, context, propagation, trace } from "@opentelemetry/api";
+import { ATTR_ERROR_TYPE, ATTR_HTTP_REQUEST_METHOD, ATTR_HTTP_RESPONSE_STATUS_CODE, ATTR_SERVER_ADDRESS, ATTR_SERVER_PORT, ATTR_URL_FULL } from "@opentelemetry/semantic-conventions";
+import { SeverityNumber, logs } from "@opentelemetry/api-logs";
+import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks";
+import { CompositePropagator, W3CBaggagePropagator, W3CTraceContextPropagator } from "@opentelemetry/core";
+import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { BatchLogRecordProcessor, LoggerProvider } from "@opentelemetry/sdk-logs";
+import { BasicTracerProvider, BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
+//#region src/sanitize.ts
+const PHONE_PATTERN = /\+?\d[\d\s()\-.]{6,18}\d/g;
+const EMAIL_PATTERN = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g;
+/**
+* Mask a phone number, keeping the leading `+` (if any) plus the first 3 digits
+* and the last 4 digits visible. Example: `+13315553374` -> `+133xxxxx3374`.
+*
+* Inputs that don't have enough digits to safely mask are returned as
+* `xxxx` to avoid leaking the entire short value.
+*/
+function sanitizePhone(input) {
+	const hasPlus = input.startsWith("+");
+	const digits = input.replace(/\D/g, "");
+	if (digits.length < 8) return hasPlus ? "+xxxx" : "xxxx";
+	const head = digits.slice(0, 3);
+	const tail = digits.slice(-4);
+	const middleLength = digits.length - head.length - tail.length;
+	return `${hasPlus ? "+" : ""}${head}${"x".repeat(middleLength)}${tail}`;
+}
+/**
+* Mask an email address, keeping the first 2 chars of the local part, the
+* first char of the domain, and the TLD. Example:
+* `foo.bar@example.com` -> `fo***@e***.com`.
+*/
+function sanitizeEmail(input) {
+	const atIndex = input.lastIndexOf("@");
+	if (atIndex < 1) return "***";
+	const local = input.slice(0, atIndex);
+	const domain = input.slice(atIndex + 1);
+	const dotIndex = domain.lastIndexOf(".");
+	if (dotIndex < 1) return "***";
+	return `${local.slice(0, 2)}***@${domain.slice(0, 1)}***${domain.slice(dotIndex)}`;
+}
+/**
+* Replace every phone number and email address inside a free-form string with
+* its sanitized form. Used to scrub `Error.message` values before attaching
+* them to span status.
+*/
+function sanitizeErrorMessage(input) {
+	return input.replace(EMAIL_PATTERN, (match) => sanitizeEmail(match)).replace(PHONE_PATTERN, (match) => sanitizePhone(match));
+}
+//#endregion
+//#region src/version.ts
+const PHOTON_OTEL_VERSION = "1.1.0";
+//#endregion
+//#region src/instrument-fetch.ts
+/**
+* Stored on the wrapper via the global symbol registry (`Symbol.for`) so the
+* double-wrap guard holds even when two copies of this module load — which can
+* happen because the `bun` export condition serves `src/` while `default`
+* serves `dist/`.
+*/
+const PATCH_MARKER = Symbol.for("@photon-ai/otel.fetch.original");
+const HTTP_ERROR_STATUS_MIN = 400;
+const DEFAULT_PORTS = {
+	"https:": 443,
+	"http:": 80
 };
-var levelOverride;
+let scopedTracer$1;
+function getTracer$1() {
+	if (!scopedTracer$1) scopedTracer$1 = trace.getTracer("@photon-ai/otel", PHOTON_OTEL_VERSION);
+	return scopedTracer$1;
+}
+function setGlobalFetch(fn) {
+	globalThis.fetch = fn;
+}
+function getPatchOriginal(fn) {
+	return fn[PATCH_MARKER];
+}
+function setPatchOriginal(fn, original) {
+	fn[PATCH_MARKER] = original;
+}
+/** Copy extra own properties (e.g. Bun's `fetch.preconnect`) onto the wrapper. */
+function preserveProps(from, to) {
+	for (const key of Object.getOwnPropertyNames(from)) {
+		if (key in to) continue;
+		const descriptor = Object.getOwnPropertyDescriptor(from, key);
+		if (descriptor) Object.defineProperty(to, key, descriptor);
+	}
+}
+function resolveRequestMeta(input, init) {
+	if (input instanceof Request) return {
+		method: input.method,
+		url: input.url
+	};
+	const url = typeof input === "string" ? input : input.toString();
+	return {
+		method: init?.method ?? "GET",
+		url
+	};
+}
+function resolvePort(parsed) {
+	if (parsed.port) return Number(parsed.port);
+	return DEFAULT_PORTS[parsed.protocol];
+}
+function toAttributes$1(attrs) {
+	const out = {};
+	for (const [key, value] of Object.entries(attrs)) if (value !== void 0) out[key] = value;
+	return out;
+}
+function fetchAttributes(method, url) {
+	const attrs = {
+		[ATTR_HTTP_REQUEST_METHOD]: method,
+		[ATTR_URL_FULL]: url
+	};
+	try {
+		const parsed = new URL(url);
+		attrs[ATTR_SERVER_ADDRESS] = parsed.hostname || void 0;
+		attrs[ATTR_SERVER_PORT] = resolvePort(parsed);
+	} catch {}
+	return toAttributes$1(attrs);
+}
+/** Build the outgoing headers and inject the active trace context into them. */
+function buildPropagatedHeaders(input, init) {
+	const headers = new Headers(input instanceof Request ? input.headers : void 0);
+	if (init?.headers) for (const [key, value] of new Headers(init.headers).entries()) headers.set(key, value);
+	propagation.inject(context.active(), headers, { set: (carrier, key, value) => {
+		carrier.set(key, value);
+	} });
+	return headers;
+}
+function callOriginal(original, input, init, headers) {
+	if (input instanceof Request) {
+		if (input.bodyUsed) {
+			for (const [key, value] of headers.entries()) input.headers.set(key, value);
+			return original(input, init);
+		}
+		return original(new Request(input, {
+			...init,
+			headers
+		}));
+	}
+	return original(input, {
+		...init,
+		headers
+	});
+}
+function buildWrappedFetch(original, options) {
+	const staticAttributes = options?.attributes;
+	return (input, init) => {
+		const { method, url } = resolveRequestMeta(input, init);
+		if (options?.ignore?.(url)) return original(input, init);
+		const name = method.toUpperCase();
+		return getTracer$1().startActiveSpan(name, { kind: SpanKind.CLIENT }, async (span) => {
+			if (staticAttributes) span.setAttributes(staticAttributes);
+			span.setAttributes(fetchAttributes(name, url));
+			try {
+				const response = await callOriginal(original, input, init, buildPropagatedHeaders(input, init));
+				span.setAttribute(ATTR_HTTP_RESPONSE_STATUS_CODE, response.status);
+				span.setStatus({ code: response.status >= HTTP_ERROR_STATUS_MIN ? SpanStatusCode.ERROR : SpanStatusCode.OK });
+				return response;
+			} catch (err) {
+				span.recordException(err);
+				const errorObj = err instanceof Error ? err : void 0;
+				span.setAttribute(ATTR_ERROR_TYPE, errorObj?.constructor.name ?? typeof err);
+				span.setStatus({
+					code: SpanStatusCode.ERROR,
+					message: errorObj ? sanitizeErrorMessage(errorObj.message) : sanitizeErrorMessage(String(err))
+				});
+				throw err;
+			} finally {
+				span.end();
+			}
+		});
+	};
+}
+/**
+* Wrap a single fetch function — not `globalThis.fetch` — so requests made
+* through the RETURNED fetch produce a CLIENT span and carry W3C trace context
+* to the downstream service.
+*
+* Built for SDKs that accept a `fetch` option, e.g.
+* `new OpenAI({ fetch: createInstrumentedFetch() })`. Unlike `instrumentFetch`,
+* it never mutates the global and has no lifecycle to unpatch — it just returns
+* a new fetch you pass where you need it.
+*
+* `baseFetch` defaults to the current `globalThis.fetch`, read at call time.
+* Idempotent: passing an already-instrumented fetch returns it unchanged.
+*
+* Always uses the global-wrap technique (the native undici instrumentation
+* cannot target a single instance), so it behaves identically on Bun and Node.
+* On Node, if `setupOtel`'s global fetch instrumentation is also active, the
+* SDK's request is captured twice — disable it (`instrumentFetch: false`) for
+* paths you instrument per-instance.
+*/
+function createInstrumentedFetch(baseFetch = globalThis.fetch, options) {
+	if (getPatchOriginal(baseFetch)) return baseFetch;
+	const wrapped = buildWrappedFetch(baseFetch, options);
+	preserveProps(baseFetch, wrapped);
+	setPatchOriginal(wrapped, baseFetch);
+	return wrapped;
+}
+/**
+* Wrap `globalThis.fetch` so every outbound request produces a CLIENT span and
+* carries W3C trace context to the downstream service.
+*
+* On Bun this is the only fetch instrumentation that works: Bun's native fetch
+* emits no `diagnostics_channel` events, so the standard `instrumentation-undici`
+* / `instrumentation-http` (and `opentelemetry-instrumentation-fetch-node`,
+* which is itself diagnostics_channel-based) produce no spans. It works
+* identically on Node, where `globalThis.fetch` is undici-backed.
+*
+* Idempotent: a second call does not stack another wrapper. Returns a handle
+* whose `unpatch()` restores the original fetch.
+*/
+function instrumentFetch(options) {
+	const current = globalThis.fetch;
+	const existingOriginal = getPatchOriginal(current);
+	if (existingOriginal) return { unpatch() {
+		if (globalThis.fetch === current) setGlobalFetch(existingOriginal);
+	} };
+	const original = current;
+	const wrapped = createInstrumentedFetch(original, options);
+	setGlobalFetch(wrapped);
+	return { unpatch() {
+		if (globalThis.fetch === wrapped) setGlobalFetch(original);
+	} };
+}
+//#endregion
+//#region src/logger.ts
+const LEVEL_SEVERITY = {
+	debug: SeverityNumber.DEBUG,
+	info: SeverityNumber.INFO,
+	warn: SeverityNumber.WARN,
+	error: SeverityNumber.ERROR,
+	silent: Number.POSITIVE_INFINITY
+};
+let levelOverride;
 function envLevel() {
-  const raw = process.env.LOG_LEVEL?.toLowerCase();
-  if (raw && raw in LEVEL_SEVERITY) {
-    return raw;
-  }
-  return;
+	const raw = process.env.LOG_LEVEL?.toLowerCase();
+	if (raw && raw in LEVEL_SEVERITY) return raw;
 }
 function defaultLevel() {
-  return (process.env.DEPLOYMENT_ENV ?? "development") === "development" ? "debug" : "info";
+	return (process.env.DEPLOYMENT_ENV ?? "development") === "development" ? "debug" : "info";
 }
+/**
+* Resolve the active level fresh on each call so that `LOG_LEVEL` changes and
+* `setLogLevel()` both take effect immediately. Resolution order (env wins, to
+* match the rest of the package's config story):
+*   1. `LOG_LEVEL` env var
+*   2. `setLogLevel()` / `setupOtel({ logLevel })`
+*   3. environment-driven default (`debug` in development, `info` otherwise)
+*/
 function resolveLevel() {
-  return envLevel() ?? levelOverride ?? defaultLevel();
+	return envLevel() ?? levelOverride ?? defaultLevel();
 }
+/**
+* Programmatically set the minimum log level. Takes effect immediately for
+* subsequent logs. `LOG_LEVEL` env var still wins if set.
+*/
 function setLogLevel(level) {
-  levelOverride = level;
+	levelOverride = level;
 }
+/** Current effective log level, after env / override / default resolution. */
 function getLogLevel() {
-  return resolveLevel();
+	return resolveLevel();
 }
-var scopedLogger;
+let scopedLogger;
 function getLogger() {
-  if (!scopedLogger) {
-    scopedLogger = logs.getLogger("@photon-ai/otel", PHOTON_OTEL_VERSION);
-  }
-  return scopedLogger;
+	if (!scopedLogger) scopedLogger = logs.getLogger("@photon-ai/otel", PHOTON_OTEL_VERSION);
+	return scopedLogger;
 }
 function filterUndefined(attrs) {
-  if (!attrs) {
-    return {};
-  }
-  const out = {};
-  for (const [k, v] of Object.entries(attrs)) {
-    if (v !== void 0) {
-      out[k] = v;
-    }
-  }
-  return out;
+	if (!attrs) return {};
+	const out = {};
+	for (const [k, v] of Object.entries(attrs)) if (v !== void 0) out[k] = v;
+	return out;
 }
 function consoleFor(severityNumber) {
-  if (severityNumber >= SeverityNumber.ERROR) {
-    return console.error;
-  }
-  if (severityNumber >= SeverityNumber.WARN) {
-    return console.warn;
-  }
-  if (severityNumber >= SeverityNumber.INFO) {
-    return console.info;
-  }
-  return console.debug;
+	if (severityNumber >= SeverityNumber.ERROR) return console.error;
+	if (severityNumber >= SeverityNumber.WARN) return console.warn;
+	if (severityNumber >= SeverityNumber.INFO) return console.info;
+	return console.debug;
 }
 function emit(severityNumber, severityText, module, message, attrs, error) {
-  if (severityNumber < LEVEL_SEVERITY[resolveLevel()]) {
-    return;
-  }
-  const userAttrs = filterUndefined(attrs);
-  const attributes = {
-    "log.module": module,
-    ...userAttrs
-  };
-  if (error instanceof Error) {
-    attributes["exception.type"] = error.name;
-    attributes["exception.message"] = error.message;
-    if (error.stack) {
-      attributes["exception.stacktrace"] = error.stack;
-    }
-  } else if (error !== void 0) {
-    attributes["exception.type"] = typeof error;
-    attributes["exception.message"] = String(error);
-  }
-  getLogger().emit({
-    severityNumber,
-    severityText,
-    body: message,
-    attributes,
-    context: otelContext.active()
-  });
-  const extras = [];
-  if (Object.keys(userAttrs).length > 0) {
-    extras.push(userAttrs);
-  }
-  if (error !== void 0) {
-    extras.push(error);
-  }
-  consoleFor(severityNumber)(`[${module}]`, severityText, message, ...extras);
+	if (severityNumber < LEVEL_SEVERITY[resolveLevel()]) return;
+	const userAttrs = filterUndefined(attrs);
+	const attributes = {
+		"log.module": module,
+		...userAttrs
+	};
+	if (error instanceof Error) {
+		attributes["exception.type"] = error.name;
+		attributes["exception.message"] = error.message;
+		if (error.stack) attributes["exception.stacktrace"] = error.stack;
+	} else if (error !== void 0) {
+		attributes["exception.type"] = typeof error;
+		attributes["exception.message"] = String(error);
+	}
+	getLogger().emit({
+		severityNumber,
+		severityText,
+		body: message,
+		attributes,
+		context: context.active()
+	});
+	const extras = [];
+	if (Object.keys(userAttrs).length > 0) extras.push(userAttrs);
+	if (error !== void 0) extras.push(error);
+	consoleFor(severityNumber)(`[${module}]`, severityText, message, ...extras);
 }
 function createLogger(module) {
-  return {
-    debug: (message, attrs, error) => emit(SeverityNumber.DEBUG, "DEBUG", module, message, attrs, error),
-    info: (message, attrs, error) => emit(SeverityNumber.INFO, "INFO", module, message, attrs, error),
-    warn: (message, attrs, error) => emit(SeverityNumber.WARN, "WARN", module, message, attrs, error),
-    error: (message, attrs, error) => emit(SeverityNumber.ERROR, "ERROR", module, message, attrs, error)
-  };
+	return {
+		debug: (message, attrs, error) => emit(SeverityNumber.DEBUG, "DEBUG", module, message, attrs, error),
+		info: (message, attrs, error) => emit(SeverityNumber.INFO, "INFO", module, message, attrs, error),
+		warn: (message, attrs, error) => emit(SeverityNumber.WARN, "WARN", module, message, attrs, error),
+		error: (message, attrs, error) => emit(SeverityNumber.ERROR, "ERROR", module, message, attrs, error)
+	};
 }
-
-// src/sanitize.ts
-var PHONE_PATTERN = /\+?\d[\d\s()\-.]{6,18}\d/g;
-var EMAIL_PATTERN = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g;
-function sanitizePhone(input) {
-  const hasPlus = input.startsWith("+");
-  const digits = input.replace(/\D/g, "");
-  if (digits.length < 8) {
-    return hasPlus ? "+xxxx" : "xxxx";
-  }
-  const head = digits.slice(0, 3);
-  const tail = digits.slice(-4);
-  const middleLength = digits.length - head.length - tail.length;
-  return `${hasPlus ? "+" : ""}${head}${"x".repeat(middleLength)}${tail}`;
+//#endregion
+//#region src/instrument-fetch-native.ts
+/**
+* Reconstruct the absolute URL undici describes from `origin` + `path`, matching
+* how the instrumentation builds `url.full`. This lets the caller's `ignore(url)`
+* predicate (and the OTLP self-trace exclusion) behave identically to the
+* global-wrap path.
+*/
+function toAbsoluteUrl(request) {
+	try {
+		return new URL(request.path, request.origin).toString();
+	} catch {
+		return `${request.origin}${request.path}`;
+	}
 }
-function sanitizeEmail(input) {
-  const atIndex = input.lastIndexOf("@");
-  if (atIndex < 1) {
-    return "***";
-  }
-  const local = input.slice(0, atIndex);
-  const domain = input.slice(atIndex + 1);
-  const dotIndex = domain.lastIndexOf(".");
-  if (dotIndex < 1) {
-    return "***";
-  }
-  const localHead = local.slice(0, 2);
-  const domainHead = domain.slice(0, 1);
-  const tld = domain.slice(dotIndex);
-  return `${localHead}***@${domainHead}***${tld}`;
+/** Node's "module isn't installed" errors carry one of these messages. */
+const MODULE_NOT_FOUND_MESSAGE = /Cannot find (module|package)/;
+/**
+* True only when `error` signals an optional package being absent, so the caller
+* can safely fall back to the `globalThis.fetch` wrap. A version mismatch or a
+* throw from the package's own initialization is a real failure and must be
+* rethrown rather than masked as "not installed".
+*/
+function isModuleNotFoundError(error) {
+	if (typeof error !== "object" || error === null) return false;
+	const { code, message } = error;
+	if (code === "MODULE_NOT_FOUND" || code === "ERR_MODULE_NOT_FOUND") return true;
+	return typeof message === "string" && MODULE_NOT_FOUND_MESSAGE.test(message);
 }
-function sanitizeErrorMessage(input) {
-  return input.replace(EMAIL_PATTERN, (match) => sanitizeEmail(match)).replace(PHONE_PATTERN, (match) => sanitizePhone(match));
+/**
+* Register `@opentelemetry/instrumentation-undici` — Node's native fetch
+* instrumentation, which reads the global tracer provider and propagator that
+* `setupOtel()` installs. Returns `undefined` when the optional packages aren't
+* installed, or when static `attributes` are requested (the undici path has no
+* hook to stamp them on every span), so the caller can fall back to the
+* `globalThis.fetch` wrap.
+*
+* The packages are referenced only through `requireFn(...)` string calls (never
+* a static `import`), so esbuild can't bundle them and Bun never loads them.
+*/
+function instrumentFetchNative(options, requireFn) {
+	if (options?.attributes && Object.keys(options.attributes).length > 0) return;
+	let UndiciInstrumentation;
+	let registerInstrumentations;
+	try {
+		const undiciModule = requireFn("@opentelemetry/instrumentation-undici");
+		const instrumentationModule = requireFn("@opentelemetry/instrumentation");
+		UndiciInstrumentation = undiciModule.UndiciInstrumentation;
+		registerInstrumentations = instrumentationModule.registerInstrumentations;
+	} catch (error) {
+		if (isModuleNotFoundError(error)) return;
+		throw error;
+	}
+	const userIgnore = options?.ignore;
+	const instrumentation = new UndiciInstrumentation({ ignoreRequestHook: userIgnore ? (request) => userIgnore(toAbsoluteUrl(request)) : void 0 });
+	registerInstrumentations({ instrumentations: [instrumentation] });
+	return { unpatch() {
+		instrumentation.disable();
+	} };
 }
-
-// src/setup.ts
-import { context, trace } from "@opentelemetry/api";
-import { logs as logs2 } from "@opentelemetry/api-logs";
-import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks";
-import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
-import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
-import { resourceFromAttributes } from "@opentelemetry/resources";
-import {
-  BatchLogRecordProcessor,
-  LoggerProvider
-} from "@opentelemetry/sdk-logs";
-import {
-  BasicTracerProvider,
-  BatchSpanProcessor
-} from "@opentelemetry/sdk-trace-base";
-var activeHandle;
-var TRAILING_SLASH = /\/$/;
+//#endregion
+//#region src/runtime.ts
+/**
+* `true` when running on Bun, `false` on Node (or any other runtime).
+*
+* This is the one place the library detects its runtime. Bun's native `fetch`
+* emits no `diagnostics_channel` events, so the official OpenTelemetry
+* instrumentations (`instrumentation-undici` / `-http`) produce no spans there
+* — we must wrap `globalThis.fetch` instead. On Node we prefer the native
+* undici instrumentation. `setupOtel()` branches on this constant.
+*
+* `process.versions.bun` is the canonical signal: it survives deletion of the
+* `Bun` global and matches the codebase's `process.*` convention. Evaluated
+* once at module load — the runtime never changes mid-process.
+*/
+const IS_BUN = typeof process !== "undefined" && process.versions?.bun !== void 0;
+//#endregion
+//#region src/setup.ts
+let activeHandle;
+const TRAILING_SLASH = /\/$/;
 function parseEnvHeaders(raw) {
-  if (!raw) {
-    return {};
-  }
-  const out = {};
-  for (const pair of raw.split(",")) {
-    const eq = pair.indexOf("=");
-    if (eq <= 0) {
-      continue;
-    }
-    const key = pair.slice(0, eq).trim();
-    const value = pair.slice(eq + 1).trim();
-    if (key) {
-      out[key] = value;
-    }
-  }
-  return out;
+	if (!raw) return {};
+	const out = {};
+	for (const pair of raw.split(",")) {
+		const eq = pair.indexOf("=");
+		if (eq <= 0) continue;
+		const key = pair.slice(0, eq).trim();
+		const value = pair.slice(eq + 1).trim();
+		if (key) out[key] = value;
+	}
+	return out;
 }
 function resolveTracesEndpoint(base) {
-  const traces = process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT;
-  if (traces) {
-    return traces;
-  }
-  const generic = process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? base;
-  return generic ? `${generic.replace(TRAILING_SLASH, "")}/v1/traces` : void 0;
+	const traces = process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT;
+	if (traces) return traces;
+	const generic = process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? base;
+	return generic ? `${generic.replace(TRAILING_SLASH, "")}/v1/traces` : void 0;
 }
 function resolveLogsEndpoint(base) {
-  const logsEndpoint = process.env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT;
-  if (logsEndpoint) {
-    return logsEndpoint;
-  }
-  const generic = process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? base;
-  return generic ? `${generic.replace(TRAILING_SLASH, "")}/v1/logs` : void 0;
+	const logsEndpoint = process.env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT;
+	if (logsEndpoint) return logsEndpoint;
+	const generic = process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? base;
+	return generic ? `${generic.replace(TRAILING_SLASH, "")}/v1/logs` : void 0;
+}
+/**
+* Normalize a URL to an `origin + path` key (trailing slash stripped) for exact
+* self-trace matching. Returns `undefined` for unparseable URLs.
+*/
+function otlpEndpointKey(url) {
+	try {
+		const parsed = new URL(url);
+		return `${parsed.origin}${parsed.pathname.replace(TRAILING_SLASH, "")}`;
+	} catch {
+		return;
+	}
+}
+function otlpEndpointKeysOf(tracesEndpoint, logsEndpoint) {
+	const keys = [];
+	for (const endpoint of [tracesEndpoint, logsEndpoint]) {
+		if (!endpoint) continue;
+		const key = otlpEndpointKey(endpoint);
+		if (key) keys.push(key);
+	}
+	return keys;
 }
+/**
+* Start fetch instrumentation unless disabled. Defaults to on when a traces
+* pipeline is configured. On Node (mode `"auto"`) this registers the native
+* `@opentelemetry/instrumentation-undici`; on Bun, or with mode `"global"`, it
+* wraps `globalThis.fetch`. Always excludes our own OTLP endpoints so the
+* exporter's traffic is never self-traced (matters on Node, where the OTLP
+* exporter can use fetch).
+*/
+function startFetchInstrumentation(option, hasTraces, tracesEndpoint, logsEndpoint) {
+	if (!(option ?? hasTraces)) return;
+	const userOptions = typeof option === "object" ? option : void 0;
+	const otlpEndpointKeys = otlpEndpointKeysOf(tracesEndpoint, logsEndpoint);
+	const ignore = (url) => {
+		const key = otlpEndpointKey(url);
+		return key !== void 0 && otlpEndpointKeys.includes(key) || (userOptions?.ignore?.(url) ?? false);
+	};
+	if ((userOptions?.mode ?? "auto") === "auto" && !IS_BUN) {
+		const native = instrumentFetchNative({
+			...userOptions,
+			ignore
+		}, createRequire(import.meta.url));
+		if (native) return native;
+	}
+	return instrumentFetch({
+		...userOptions,
+		ignore
+	});
+}
+/**
+* Boot an OTLP/HTTP-based OpenTelemetry pipeline (traces + logs).
+*
+* Idempotent: calling twice in the same process is a no-op on the second
+* call, so libraries can safely invoke this without clobbering an app-level
+* OTel setup that ran earlier.
+*
+* Standard `OTEL_EXPORTER_OTLP_*` env vars override the `endpoint` and
+* `headers` arguments — this matches the OpenTelemetry SDK config spec.
+*/
 function setupOtel(options) {
-  if (activeHandle) {
-    return activeHandle;
-  }
-  if (options.logLevel) {
-    setLogLevel(options.logLevel);
-  }
-  const tracesEndpoint = resolveTracesEndpoint(options.endpoint);
-  const logsEndpoint = resolveLogsEndpoint(options.endpoint);
-  const mergedHeaders = {
-    ...options.headers,
-    ...parseEnvHeaders(process.env.OTEL_EXPORTER_OTLP_HEADERS)
-  };
-  const hasHeaders = Object.keys(mergedHeaders).length > 0;
-  const resource = resourceFromAttributes({
-    "service.name": options.serviceName,
-    ...options.serviceVersion ? { "service.version": options.serviceVersion } : {},
-    "deployment.environment": process.env.DEPLOYMENT_ENV ?? "development",
-    ...options.resourceAttributes
-  });
-  context.setGlobalContextManager(new AsyncLocalStorageContextManager());
-  const traceProcessors = tracesEndpoint ? [
-    new BatchSpanProcessor(
-      new OTLPTraceExporter({
-        url: tracesEndpoint,
-        headers: hasHeaders ? mergedHeaders : void 0
-      })
-    )
-  ] : [];
-  const tracerProvider = new BasicTracerProvider({
-    resource,
-    spanProcessors: traceProcessors
-  });
-  trace.setGlobalTracerProvider(tracerProvider);
-  const logProcessors = logsEndpoint ? [
-    new BatchLogRecordProcessor(
-      new OTLPLogExporter({
-        url: logsEndpoint,
-        headers: hasHeaders ? mergedHeaders : void 0
-      })
-    )
-  ] : [];
-  const loggerProvider = new LoggerProvider({
-    resource,
-    processors: logProcessors
-  });
-  logs2.setGlobalLoggerProvider(loggerProvider);
-  const handle = {
-    async shutdown() {
-      await Promise.allSettled([
-        tracerProvider.shutdown(),
-        loggerProvider.shutdown()
-      ]);
-      activeHandle = void 0;
-    }
-  };
-  activeHandle = handle;
-  return handle;
+	if (activeHandle) return activeHandle;
+	if (options.logLevel) setLogLevel(options.logLevel);
+	const tracesEndpoint = resolveTracesEndpoint(options.endpoint);
+	const logsEndpoint = resolveLogsEndpoint(options.endpoint);
+	const mergedHeaders = {
+		...options.headers,
+		...parseEnvHeaders(process.env.OTEL_EXPORTER_OTLP_HEADERS)
+	};
+	const hasHeaders = Object.keys(mergedHeaders).length > 0;
+	const resource = resourceFromAttributes({
+		"service.name": options.serviceName,
+		...options.serviceVersion ? { "service.version": options.serviceVersion } : {},
+		"deployment.environment": process.env.DEPLOYMENT_ENV ?? "development",
+		...options.resourceAttributes
+	});
+	context.setGlobalContextManager(new AsyncLocalStorageContextManager());
+	propagation.setGlobalPropagator(new CompositePropagator({ propagators: [new W3CTraceContextPropagator(), new W3CBaggagePropagator()] }));
+	const traceProcessors = tracesEndpoint ? [new BatchSpanProcessor(new OTLPTraceExporter({
+		url: tracesEndpoint,
+		headers: hasHeaders ? mergedHeaders : void 0
+	}))] : [];
+	const tracerProvider = new BasicTracerProvider({
+		resource,
+		spanProcessors: traceProcessors
+	});
+	trace.setGlobalTracerProvider(tracerProvider);
+	const fetchInstrumentation = startFetchInstrumentation(options.instrumentFetch, traceProcessors.length > 0, tracesEndpoint, logsEndpoint);
+	const loggerProvider = new LoggerProvider({
+		resource,
+		processors: logsEndpoint ? [new BatchLogRecordProcessor(new OTLPLogExporter({
+			url: logsEndpoint,
+			headers: hasHeaders ? mergedHeaders : void 0
+		}))] : []
+	});
+	logs.setGlobalLoggerProvider(loggerProvider);
+	const handle = { async shutdown() {
+		fetchInstrumentation?.unpatch();
+		await Promise.allSettled([tracerProvider.shutdown(), loggerProvider.shutdown()]);
+		activeHandle = void 0;
+	} };
+	activeHandle = handle;
+	return handle;
 }
+/**
+* Read-only accessor for tests / debug paths that need to know whether
+* `setupOtel` has already run in this process.
+*/
 function isOtelActive() {
-  return activeHandle !== void 0;
+	return activeHandle !== void 0;
 }
-
-// src/with-span.ts
-import {
-  SpanStatusCode,
-  trace as trace2
-} from "@opentelemetry/api";
-var scopedTracer;
+//#endregion
+//#region src/with-span.ts
+let scopedTracer;
 function getTracer() {
-  if (!scopedTracer) {
-    scopedTracer = trace2.getTracer("@photon-ai/otel", PHOTON_OTEL_VERSION);
-  }
-  return scopedTracer;
+	if (!scopedTracer) scopedTracer = trace.getTracer("@photon-ai/otel", PHOTON_OTEL_VERSION);
+	return scopedTracer;
 }
 function toAttributes(attrs) {
-  const out = {};
-  for (const [k, v] of Object.entries(attrs)) {
-    if (v !== void 0) {
-      out[k] = v;
-    }
-  }
-  return out;
+	const out = {};
+	for (const [k, v] of Object.entries(attrs)) if (v !== void 0) out[k] = v;
+	return out;
 }
 function withSpan(name, attrsOrFn, maybeFn) {
-  const fn = typeof attrsOrFn === "function" ? attrsOrFn : maybeFn;
-  if (!fn) {
-    throw new Error("withSpan: function argument is required");
-  }
-  const attrs = typeof attrsOrFn === "function" ? void 0 : attrsOrFn;
-  return getTracer().startActiveSpan(name, async (span) => {
-    if (attrs) {
-      span.setAttributes(toAttributes(attrs));
-    }
-    try {
-      const result = await fn();
-      span.setStatus({ code: SpanStatusCode.OK });
-      return result;
-    } catch (err) {
-      span.recordException(err);
-      const errorObj = err instanceof Error ? err : void 0;
-      span.setAttribute("error.type", errorObj?.constructor.name ?? typeof err);
-      span.setStatus({
-        code: SpanStatusCode.ERROR,
-        message: errorObj ? sanitizeErrorMessage(errorObj.message) : sanitizeErrorMessage(String(err))
-      });
-      throw err;
-    } finally {
-      span.end();
-    }
-  });
-}
-export {
-  PHOTON_OTEL_VERSION,
-  createLogger,
-  getLogLevel,
-  isOtelActive,
-  sanitizeEmail,
-  sanitizeErrorMessage,
-  sanitizePhone,
-  setLogLevel,
-  setupOtel,
-  withSpan
-};
+	const fn = typeof attrsOrFn === "function" ? attrsOrFn : maybeFn;
+	if (!fn) throw new Error("withSpan: function argument is required");
+	const attrs = typeof attrsOrFn === "function" ? void 0 : attrsOrFn;
+	return getTracer().startActiveSpan(name, async (span) => {
+		if (attrs) span.setAttributes(toAttributes(attrs));
+		try {
+			const result = await fn();
+			span.setStatus({ code: SpanStatusCode.OK });
+			return result;
+		} catch (err) {
+			span.recordException(err);
+			const errorObj = err instanceof Error ? err : void 0;
+			span.setAttribute("error.type", errorObj?.constructor.name ?? typeof err);
+			span.setStatus({
+				code: SpanStatusCode.ERROR,
+				message: errorObj ? sanitizeErrorMessage(errorObj.message) : sanitizeErrorMessage(String(err))
+			});
+			throw err;
+		} finally {
+			span.end();
+		}
+	});
+}
+//#endregion
+export { PHOTON_OTEL_VERSION, createInstrumentedFetch, createLogger, getLogLevel, instrumentFetch, isOtelActive, sanitizeEmail, sanitizeErrorMessage, sanitizePhone, setLogLevel, setupOtel, withSpan };
+
 //# sourceMappingURL=index.js.map