feat(scope)!: add scoped mode; remove OTEL_INSTRUMENT_FETCH env var (#11)

Add a scoped/embeddable mode to `setupOtel()` via a new `register: false`
option, backed by an internal provider holder (`src/scope.ts`). In scoped mode
the library builds and holds its own tracer/logger providers and routes
`withSpan` / `createLogger` / `createInstrumentedFetch` through them, leaving the
host app's global OpenTelemetry untouched. The shared context manager and W3C
propagator are still installed if absent (needed for span nesting and trace
propagation), and auto fetch instrumentation defaults off in scoped mode (it
wraps the process-global `fetch`). `OtelHandle` now also exposes
`tracerProvider` / `loggerProvider` so embedders can build extra tracers or
attach processors.

Remove the `OTEL_INSTRUMENT_FETCH` environment variable (shipped in 2.1.0). It
only toggled the process-global fetch wrap on/off and never addressed the
underlying provider-takeover problem that scoped mode now solves. Fetch
instrumentation is still controlled by the `setupOtel({ instrumentFetch })`
option, and individual clients can be traced with `createInstrumentedFetch()`.

BREAKING CHANGE: the OTEL_INSTRUMENT_FETCH environment variable is removed. Use
the `instrumentFetch` option to toggle fetch instrumentation, or `register:
false` for scoped mode.

Author: underthestars-zhy

.github/workflows/integration.yml

@@ -31,11 +31,6 @@ jobs:
           node-version: ${{ matrix.node-version }}
       - run: bun install --frozen-lockfile
 
-      # The OTEL_INSTRUMENT_FETCH=false case runs in a child process that imports
-      # the built bundle (so it runs unchanged under both node and bun).
-      - name: Build
-        run: bun run build
-
       - name: Start OTel Collector
         working-directory: tests/integration
         run: |

README.md

@@ -47,7 +47,7 @@ If `OTEL_EXPORTER_OTLP_ENDPOINT` (or the `endpoint` option) is unset, `setupOtel
 
 | Function                                      | Description                                                                                                |
 | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `setupOtel(options): OtelHandle`              | Boots OTLP/HTTP traces + logs. Idempotent. Returns `{ shutdown(): Promise<void> }`.                        |
+| `setupOtel(options): OtelHandle`              | Boots OTLP/HTTP traces + logs. Idempotent. Returns `{ shutdown(), tracerProvider, loggerProvider }`. Pass `register: false` for scoped mode (no global takeover). |
 | `isOtelActive(): boolean`                     | Returns `true` if `setupOtel` has already run in this process.                                             |
 | `instrumentFetch(options?): FetchInstrumentation` | Low-level wrap of `globalThis.fetch` for CLIENT spans + W3C propagation. Returns `{ unpatch() }`. `setupOtel` calls this on Bun; on Node it prefers native undici. |
 | `createInstrumentedFetch(baseFetch?, options?): typeof fetch` | Returns a NEW instrumented fetch (CLIENT spans + W3C propagation) wrapping `baseFetch` (default `globalThis.fetch`) without touching the global. For SDKs that take a `fetch` option. |
@@ -113,7 +113,6 @@ Standard OpenTelemetry env vars always take precedence over `SetupOtelOptions`:
 | `OTEL_EXPORTER_OTLP_HEADERS`              | `key=value,key=value` headers; merged with `options.headers` (env wins). |
 | `DEPLOYMENT_ENV`                          | Attached as `deployment.environment` resource attribute. Defaults to `development`. Also drives the default log level. |
 | `LOG_LEVEL`                               | Minimum log level: `debug` \| `info` \| `warn` \| `error` \| `silent`. Overrides `setLogLevel()` / `setupOtel({ logLevel })`. |
-| `OTEL_INSTRUMENT_FETCH`                   | Toggle outbound `fetch` tracing: `true` / `1` on, `false` / `0` off. Overrides `instrumentFetch` and the default. |
 
 ## Automatic fetch instrumentation
 
@@ -137,8 +136,7 @@ The strategy depends on the runtime (`mode: "auto"`, the default):
 Options (`instrumentFetch`):
 
 - **`true` / `false`:** force on (even without an endpoint) / off. Defaults to on when a traces
-  endpoint is configured. The `OTEL_INSTRUMENT_FETCH` env var overrides this (`true`/`1` to force on,
-  `false`/`0` to disable) — toggle fetch tracing in production without a code change.
+  endpoint is configured.
 - **`mode`:** `"auto"` (default — native on Node, wrap on Bun) or `"global"` (wrap on both runtimes).
   Choose `"global"` when you want identical spans everywhere and the built-in PII scrubbing of error
   messages kept on Node (see caveats).
@@ -193,6 +191,36 @@ SDKs per-instance, disable the global path with `setupOtel({ instrumentFetch: fa
 per-instance wrapping for SDKs you accept doubling on). **Bun has no such issue** — its global wrap only
 affects `globalThis.fetch`, so a separately-passed instrumented fetch is counted once.
 
+## Scoped mode (embedding in a library)
+
+By default `setupOtel()` registers the process-global OpenTelemetry tracer/logger providers — the
+convenient app-level setup. If you're building a **library** that ships its own telemetry, that would
+take over the host application's OpenTelemetry. Pass `register: false` to run **scoped**:
+
+```ts
+const otel = setupOtel({ serviceName: "my-lib", register: false });
+
+// withSpan / createLogger emit into the library's own providers...
+await withSpan("work", async () => {
+  /* ... */
+});
+// ...and the host app's global tracer/logger providers are left untouched.
+```
+
+In scoped mode:
+
+- **No global takeover.** `setupOtel()` does not call `setGlobalTracerProvider` / `setGlobalLoggerProvider`;
+  the library's spans and logs flow to its own providers while the host keeps its global OTel.
+- **The top-level helpers still work** — `withSpan`, `createLogger`, and `createInstrumentedFetch` resolve
+  through the library's providers automatically.
+- **Shared context is preserved.** A W3C propagator and an `AsyncLocalStorageContextManager` are installed
+  only if absent, so span nesting and `traceparent` propagation work — and if the host already set them, the
+  library shares the host's (spans nest across the boundary).
+- **Auto fetch instrumentation defaults off** (wrapping `globalThis.fetch` is process-wide, and native undici
+  can only read the global provider). Trace a specific client with `createInstrumentedFetch()` instead.
+- **The handle exposes the providers** — `otel.tracerProvider` / `otel.loggerProvider` — if you need to build
+  extra tracers or wire additional processors.
+
 ## Running on Node vs Bun
 
 The same code runs unmodified on both. Pick whichever you prefer:

docs/configuration.mdx

@@ -183,14 +183,6 @@ setupOtel({
 });
 ```
 
-Or disable it from the environment — no code change or redeploy of app logic required:
-
-```bash
-OTEL_INSTRUMENT_FETCH=false
-```
-
-`OTEL_INSTRUMENT_FETCH` accepts `true` / `1` (force on) and `false` / `0` (disable), and takes precedence over both the `instrumentFetch` option and the default. The object form (`mode`, `ignore`) still configures _how_ fetch is traced whenever instrumentation is on.
-
 You can force it on even without an exporter endpoint:
 
 ```ts
@@ -236,7 +228,6 @@ The package always excludes its own OTLP trace and log exporter endpoints from f
 | OTLP headers | `OTEL_EXPORTER_OTLP_HEADERS` | `setupOtel({ headers })` |
 | Log level | `LOG_LEVEL` | `setupOtel({ logLevel })` or `setLogLevel()` |
 | Deployment environment | `DEPLOYMENT_ENV` | `development` |
-| Fetch instrumentation | `OTEL_INSTRUMENT_FETCH` | `setupOtel({ instrumentFetch })` or default |
 
 ## Best practices
 

docs/guides/fetch-instrumentation.mdx

@@ -19,22 +19,6 @@ When a traces endpoint is configured, setup instruments fetch by default. The st
 
 The standalone `instrumentFetch()` export always performs the `globalThis.fetch` wrap, and `createInstrumentedFetch()` wraps a single fetch instance (for SDKs) without touching the global.
 
-## Enabling and disabling
-
-Pass `instrumentFetch: false` to turn it off, or `true` to force it on even without an endpoint:
-
-```ts
-setupOtel({ serviceName: "orders-api", instrumentFetch: false });
-```
-
-The `OTEL_INSTRUMENT_FETCH` environment variable overrides both the option and the default — `true` / `1` forces it on, `false` / `0` disables it. Because env wins over code (matching the rest of the package's configuration), you can silence noisy or expensive fetch spans in production without changing application code:
-
-```bash
-OTEL_INSTRUMENT_FETCH=false
-```
-
-The env var only flips the on/off decision; when instrumentation stays on, the object form still applies — `OTEL_INSTRUMENT_FETCH=true` alongside `instrumentFetch: { mode: "global", ignore }` keeps your `mode` and `ignore`.
-
 ## What each fetch span contains
 
 For an outbound request, fetch instrumentation creates a span with:
@@ -141,8 +125,6 @@ If fetch is already wrapped by this package, a second call does not stack anothe
 
 The implementation uses a global symbol marker to remember the original fetch. That guard works even if two copies of the package are loaded, such as Bun consuming TypeScript source while another path consumes the built ESM bundle.
 
-`setupOtel()` is idempotent too: the first call wins, so a later `setupOtel({ instrumentFetch: false })` cannot turn off instrumentation that an earlier call already enabled. Decide on the first call, or use `OTEL_INSTRUMENT_FETCH`, which is read whenever setup actually runs.
-
 ## Restoring fetch
 
 The returned handle exposes `unpatch()`.

src/instrument-fetch.ts

@@ -4,8 +4,6 @@ import {
   propagation,
   SpanKind,
   SpanStatusCode,
-  type Tracer,
-  trace,
 } from "@opentelemetry/api";
 import {
   ATTR_ERROR_TYPE,
@@ -16,6 +14,7 @@ import {
   ATTR_URL_FULL,
 } from "@opentelemetry/semantic-conventions";
 import { sanitizeErrorMessage } from "./sanitize";
+import { resolveTracer } from "./scope";
 import { PHOTON_OTEL_VERSION } from "./version";
 
 export interface FetchSpanOptions {
@@ -72,15 +71,6 @@ const PATCH_MARKER = Symbol.for("@photon-ai/otel.fetch.original");
 const HTTP_ERROR_STATUS_MIN = 400;
 const DEFAULT_PORTS: Record<string, number> = { "https:": 443, "http:": 80 };
 
-let scopedTracer: Tracer | undefined;
-
-function getTracer(): Tracer {
-  if (!scopedTracer) {
-    scopedTracer = trace.getTracer("@photon-ai/otel", PHOTON_OTEL_VERSION);
-  }
-  return scopedTracer;
-}
-
 function setGlobalFetch(fn: FetchFn): void {
   // `preconnect` (Bun) is copied onto wrappers by preserveProps; the cast just
   // tells TypeScript the runtime object satisfies the full `fetch` type.
@@ -201,44 +191,43 @@ function buildWrappedFetch(
       return original(input, init);
     }
     const name = method.toUpperCase();
-    return getTracer().startActiveSpan(
-      name,
-      { kind: SpanKind.CLIENT },
-      async (span) => {
-        if (staticAttributes) {
-          span.setAttributes(staticAttributes);
-        }
-        span.setAttributes(fetchAttributes(name, url));
-        try {
-          const headers = buildPropagatedHeaders(input, init);
-          const response = await callOriginal(original, input, init, headers);
-          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 as Error);
-          const errorObj = err instanceof Error ? err : undefined;
-          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();
-        }
+    return resolveTracer(
+      "@photon-ai/otel",
+      PHOTON_OTEL_VERSION
+    ).startActiveSpan(name, { kind: SpanKind.CLIENT }, async (span) => {
+      if (staticAttributes) {
+        span.setAttributes(staticAttributes);
+      }
+      span.setAttributes(fetchAttributes(name, url));
+      try {
+        const headers = buildPropagatedHeaders(input, init);
+        const response = await callOriginal(original, input, init, headers);
+        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 as Error);
+        const errorObj = err instanceof Error ? err : undefined;
+        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();
       }
-    );
+    });
   };
 }
 

src/logger.ts

@@ -1,5 +1,6 @@
 import { context as otelContext } from "@opentelemetry/api";
-import { type Logger, logs, SeverityNumber } from "@opentelemetry/api-logs";
+import { SeverityNumber } from "@opentelemetry/api-logs";
+import { resolveLogger } from "./scope";
 import { PHOTON_OTEL_VERSION } from "./version";
 
 export type LogAttrs = Record<string, string | number | boolean | undefined>;
@@ -59,15 +60,6 @@ export function getLogLevel(): LogLevel {
   return resolveLevel();
 }
 
-let scopedLogger: Logger | undefined;
-
-function getLogger(): Logger {
-  if (!scopedLogger) {
-    scopedLogger = logs.getLogger("@photon-ai/otel", PHOTON_OTEL_VERSION);
-  }
-  return scopedLogger;
-}
-
 function filterUndefined(
   attrs?: LogAttrs
 ): Record<string, string | number | boolean> {
@@ -129,7 +121,7 @@ function emit(
     attributes["exception.message"] = String(error);
   }
 
-  getLogger().emit({
+  resolveLogger("@photon-ai/otel", PHOTON_OTEL_VERSION).emit({
     severityNumber,
     severityText,
     body: message,

src/scope.ts

@@ -0,0 +1,53 @@
+import { type Tracer, type TracerProvider, trace } from "@opentelemetry/api";
+import {
+  type Logger,
+  type LoggerProvider,
+  logs,
+} from "@opentelemetry/api-logs";
+
+/**
+ * Holds the tracer/logger providers the active `setupOtel()` built. This lets
+ * the library's own helpers (`withSpan`, `createLogger`, the fetch wrap) emit
+ * into those providers even in scoped mode (`register: false`), where the
+ * global OTel provider registry is deliberately left untouched so the library
+ * can coexist with a host app's own OpenTelemetry setup.
+ *
+ * Resolution prefers the held provider and falls back to the global API, so
+ * helpers used before `setupOtel()` (or after `shutdown()`) behave exactly as
+ * they did when they read `trace.getTracer()` / `logs.getLogger()` directly.
+ */
+let heldTracerProvider: TracerProvider | undefined;
+let heldLoggerProvider: LoggerProvider | undefined;
+
+export function setActiveProviders(providers: {
+  tracerProvider: TracerProvider;
+  loggerProvider: LoggerProvider;
+}): void {
+  heldTracerProvider = providers.tracerProvider;
+  heldLoggerProvider = providers.loggerProvider;
+}
+
+export function clearActiveProviders(): void {
+  heldTracerProvider = undefined;
+  heldLoggerProvider = undefined;
+}
+
+/**
+ * The active tracer: the provider `setupOtel()` built when set, else the global
+ * one. Resolved per call — `getTracer` is memoized inside the provider, so this
+ * is cheap and never pins a stale provider across setup/shutdown cycles.
+ */
+export function resolveTracer(name: string, version?: string): Tracer {
+  return (heldTracerProvider ?? trace.getTracerProvider()).getTracer(
+    name,
+    version
+  );
+}
+
+/** The active logger: the held provider when set, else the global one. */
+export function resolveLogger(name: string, version?: string): Logger {
+  return (heldLoggerProvider ?? logs.getLoggerProvider()).getLogger(
+    name,
+    version
+  );
+}