@photon-ai/otel 1.1.0 → 2.0.1

package/README.md

@@ -7,10 +7,10 @@ Vanilla OTel works, but the setup is verbose, the logger plumbing is awkward, an
 - **`setupOtel()`** — idempotent one-call bootstrap for traces + logs. Honors all standard `OTEL_EXPORTER_OTLP_*` env vars.
 - **`createLogger(module)`** — structured logger that writes to both the OTel logger provider and `console`, with automatic trace correlation and exception capture. Every level (`debug`/`info`/`warn`/`error`) accepts `attrs` **and** an `error`, and is gated by a configurable `LOG_LEVEL`.
 - **`withSpan(name, attrs?, fn)`** — wrap any sync or async function in a span; errors are recorded and PII in the error message is scrubbed before being attached to span status.
-- **Automatic `fetch` tracing** — `setupOtel()` wraps `globalThis.fetch` so every outbound request gets a CLIENT span and W3C trace-context headers. On **Bun** this is the only fetch instrumentation that works — the standard `diagnostics_channel`-based OTel instrumentations emit nothing for Bun's native fetch — and it behaves identically on Node.
+- **Automatic `fetch` tracing** — `setupOtel()` instruments outbound `fetch` so every request gets a CLIENT span and W3C trace-context headers. On **Node** it uses the official `@opentelemetry/instrumentation-undici`; on **Bun** — whose native fetch emits nothing for the standard `diagnostics_channel`-based instrumentations — it wraps `globalThis.fetch`. Pass `instrumentFetch: { mode: "global" }` to force the wrap on both for identical spans.
 - **`sanitizeEmail` / `sanitizePhone` / `sanitizeErrorMessage`** — PII helpers you can reuse anywhere.
 
-OTLP/HTTP only (no gRPC, no proto). Works identically on Bun and Node ≥ 20.
+OTLP/HTTP only (no gRPC, no proto). Runs on Bun and Node ≥ 20.
 
 ## Install
 
@@ -49,7 +49,8 @@ If `OTEL_EXPORTER_OTLP_ENDPOINT` (or the `endpoint` option) is unset, `setupOtel
 | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
 | `setupOtel(options): OtelHandle`              | Boots OTLP/HTTP traces + logs. Idempotent. Returns `{ shutdown(): Promise<void> }`.                        |
 | `isOtelActive(): boolean`                     | Returns `true` if `setupOtel` has already run in this process.                                             |
-| `instrumentFetch(options?): FetchInstrumentation` | Wraps `globalThis.fetch` for CLIENT spans + W3C propagation. Auto-enabled by `setupOtel` when traces are configured. Returns `{ unpatch() }`. |
+| `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. |
 | `createLogger(module): PhotonLogger`          | Returns `{ info, warn, error, debug }`. Each call emits to OTel + `console`, correlates to active span.    |
 | `setLogLevel(level): void`                    | Set the minimum level emitted (`debug`/`info`/`warn`/`error`/`silent`). `LOG_LEVEL` env still wins.        |
 | `getLogLevel(): LogLevel`                     | Current effective level after env / override / default resolution.                                        |
@@ -115,28 +116,81 @@ Standard OpenTelemetry env vars always take precedence over `SetupOtelOptions`:
 
 ## Automatic fetch instrumentation
 
-`setupOtel()` patches `globalThis.fetch` to emit a CLIENT span per outbound request, carrying
-W3C `traceparent` (and baggage) headers so traces continue across services. Each span is named by
-HTTP method (`GET`, `POST`, …) and carries `http.request.method`, `url.full`, `server.address`,
-`server.port`, and `http.response.status_code`; `4xx`/`5xx` responses and thrown network errors are
-marked `ERROR`. This covers **outbound** requests only — inbound `Bun.serve`/Elysia server spans are
-separate (see [Framework integration](#framework-integration)).
-
-- **Default:** on when a traces endpoint is configured. Pass `instrumentFetch: false` to disable, or
-  `instrumentFetch: true` to force it on even without an endpoint.
-- **Filter URLs:** `instrumentFetch: { ignore: (url) => url.includes("/healthz") }`. Your own OTLP
+`setupOtel()` instruments outbound `fetch` to emit a CLIENT span per request, carrying W3C
+`traceparent` (and baggage) headers so traces continue across services. Spans are named by HTTP
+method (`GET`, `POST`, …) and carry `http.request.method`, `url.full`, `server.address`,
+`server.port`, and `http.response.status_code`. This covers **outbound** requests only — inbound
+`Bun.serve`/Elysia server spans are separate (see [Framework integration](#framework-integration)).
+
+The strategy depends on the runtime (`mode: "auto"`, the default):
+
+- **Node** uses the official `@opentelemetry/instrumentation-undici` (Node's `fetch` is undici-backed).
+  It captures all undici traffic — not just `globalThis.fetch` — emits the full HTTP-client semantic
+  conventions (`url.scheme`, `url.path`, `network.peer.*`, `user_agent.original`, …), and never
+  monkey-patches the global. It ships as an optional dependency; if it isn't installed, the library
+  falls back to the global wrap.
+- **Bun** wraps `globalThis.fetch` directly. Bun's native `fetch` emits no `diagnostics_channel`
+  events, so `@opentelemetry/instrumentation-undici` / `-http` produce no spans there — wrapping the
+  global is the only mechanism that works.
+
+Options (`instrumentFetch`):
+
+- **`true` / `false`:** force on (even without an endpoint) / off. Defaults to on when a traces
+  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).
+- **`ignore`:** `instrumentFetch: { ignore: (url) => url.includes("/healthz") }`. Your own OTLP
   endpoint is always excluded automatically, so the exporter never traces itself.
-- **Why Bun needs this:** Bun's native `fetch` emits no `diagnostics_channel` events, so
-  `@opentelemetry/instrumentation-undici` / `-http` — and `opentelemetry-instrumentation-fetch-node`,
-  which is itself `diagnostics_channel`-based — produce no spans. Wrapping the global is the only
-  mechanism that works, and it behaves identically on Node.
-- **Caveat:** `url.full` includes the query string. If your URLs carry secrets there, use `ignore`
-  or redact upstream.
+
+Caveats:
+
+- **Telemetry differs by runtime under `"auto"`.** undici (Node) emits richer attributes and follows
+  HTTP semconv for span status — a 2xx client span is left `UNSET`, and only `5xx`/network failures are
+  marked `ERROR`; the Bun wrap marks all `4xx`/`5xx` as `ERROR`. The Bun wrap also scrubs PII from the
+  error message attached to span status — **undici does not**. Use `mode: "global"` for parity.
+- **`url.full` includes the query string** on both. If your URLs carry secrets there, use `ignore` or
+  redact upstream.
+- **Native fetch tracing needs Node ≥ 20.6** (the undici instrumentation's floor); older 20.x falls
+  back to the global wrap.
 
 `setupOtel()` also installs a global W3C trace-context + baggage propagator (previously none was
 registered) — that is what makes the outbound `traceparent` injection, and any manual propagation,
 actually take effect.
 
+## Instrumenting a specific fetch (SDKs)
+
+Sometimes you don't want to touch `globalThis.fetch` — you just want one SDK's outbound calls traced.
+`createInstrumentedFetch(baseFetch?, options?)` returns a **new** fetch (CLIENT spans + W3C
+`traceparent` injection) wrapping `baseFetch` (default `globalThis.fetch`, read at call time) **without
+mutating the global**. Pass it wherever an SDK accepts a `fetch`:
+
+```ts
+import { createInstrumentedFetch } from "@photon-ai/otel";
+import OpenAI from "openai";
+
+const client = new OpenAI({
+  // tag every span from this SDK so it's distinguishable from other traffic
+  fetch: createInstrumentedFetch(undefined, {
+    attributes: { "peer.service": "openai" },
+  }),
+});
+```
+
+- Returns a fetch function directly — there's no global lifecycle, so no `unpatch()` handle.
+- Idempotent: passing an already-instrumented fetch returns it unchanged.
+- `options`: `ignore: (url) => boolean` skips spans for some URLs; `attributes` merges static attributes
+  into every span (the practical way to tell different SDKs' spans apart).
+- Always uses the wrapper technique, so it behaves identically on Bun and Node (the native undici
+  instrumentation can't target a single instance).
+
+**Avoid double-counting on Node.** If `setupOtel()`'s global fetch instrumentation is active (the
+default on Node uses undici, which captures *all* undici traffic), an SDK request made through a
+per-instance wrapper is recorded **twice** — once by the wrapper, once by undici. When instrumenting
+SDKs per-instance, disable the global path with `setupOtel({ instrumentFetch: false })` (or reserve
+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.
+
 ## Running on Node vs Bun
 
 The same code runs unmodified on both. Pick whichever you prefer:
@@ -149,6 +203,8 @@ node --experimental-strip-types src/server.ts
 
 The package uses `process.env` (not `Bun.env`) and `AsyncLocalStorageContextManager` (backed by `async_hooks`), both of which are supported natively by Bun and Node ≥ 20.
 
+The one runtime-specific behavior is fetch instrumentation — native undici on Node, a `globalThis.fetch` wrap on Bun (see [Automatic fetch instrumentation](#automatic-fetch-instrumentation)). Set `instrumentFetch: { mode: "global" }` for identical behavior on both.
+
 For Bun consumers, the `exports` map points at the TypeScript source via the `bun` condition for faster cold starts during dev. Node consumers get the pre-built ESM bundle.
 
 ## Why HTTP exporters only?

package/dist/index.d.ts

@@ -1,15 +1,62 @@
-interface InstrumentFetchOptions {
-    /**
-     * Return `true` to skip instrumenting a request whose absolute URL is passed
-     * in. Useful to drop noisy endpoints or URLs that carry secrets in their
-     * query string. The request is still performed — only the span is skipped.
-     */
-    ignore?: (url: string) => boolean;
+import { Attributes } from "@opentelemetry/api";
+
+//#region src/instrument-fetch.d.ts
+interface FetchSpanOptions {
+  /**
+   * Static attributes merged into every CLIENT span this instrumentation
+   * produces. Handy for tagging an SDK's traffic, e.g. `{ "peer.service":
+   * "openai" }`, so spans from different instrumented fetches stay
+   * distinguishable.
+   */
+  attributes?: Attributes;
+  /**
+   * Return `true` to skip instrumenting a request whose absolute URL is passed
+   * in. Useful to drop noisy endpoints or URLs that carry secrets in their
+   * query string. The request is still performed — only the span is skipped.
+   */
+  ignore?: (url: string) => boolean;
+}
+interface InstrumentFetchOptions extends FetchSpanOptions {
+  /**
+   * Which fetch-instrumentation strategy `setupOtel()` should use:
+   * - `"auto"` (default): the official `@opentelemetry/instrumentation-undici`
+   *   on Node (richer HTTP-client semantic conventions, captures all undici
+   *   traffic, no global monkey-patch), and the `globalThis.fetch` wrap on Bun
+   *   (the only thing that works there).
+   * - `"global"`: always wrap `globalThis.fetch` on both runtimes. Produces
+   *   identical spans everywhere and keeps the built-in PII scrubbing of error
+   *   messages, at the cost of the richer Node attributes. Use this when you
+   *   want Bun and Node telemetry to match exactly.
+   *
+   * Only consulted by `setupOtel()`. Calling `instrumentFetch()` directly always
+   * performs a global wrap regardless of this field.
+   */
+  mode?: "auto" | "global";
 }
 interface FetchInstrumentation {
-    /** Restore the original `globalThis.fetch`. Safe to call more than once. */
-    unpatch(): void;
+  /** Restore the original `globalThis.fetch`. Safe to call more than once. */
+  unpatch(): void;
 }
+/**
+ * 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.
+ */
+declare function createInstrumentedFetch(baseFetch?: typeof fetch, options?: FetchSpanOptions): typeof fetch;
 /**
  * Wrap `globalThis.fetch` so every outbound request produces a CLIENT span and
  * carries W3C trace context to the downstream service.
@@ -24,7 +71,8 @@ interface FetchInstrumentation {
  * whose `unpatch()` restores the original fetch.
  */
 declare function instrumentFetch(options?: InstrumentFetchOptions): FetchInstrumentation;
-
+//#endregion
+//#region src/logger.d.ts
 type LogAttrs = Record<string, string | number | boolean | undefined>;
 /**
  * Minimum severity that gets emitted (to both the OTLP record and the console).
@@ -39,13 +87,14 @@ declare function setLogLevel(level: LogLevel): void;
 /** Current effective log level, after env / override / default resolution. */
 declare function getLogLevel(): LogLevel;
 interface PhotonLogger {
-    debug(message: string, attrs?: LogAttrs, error?: unknown): void;
-    error(message: string, attrs?: LogAttrs, error?: unknown): void;
-    info(message: string, attrs?: LogAttrs, error?: unknown): void;
-    warn(message: string, attrs?: LogAttrs, error?: unknown): void;
+  debug(message: string, attrs?: LogAttrs, error?: unknown): void;
+  error(message: string, attrs?: LogAttrs, error?: unknown): void;
+  info(message: string, attrs?: LogAttrs, error?: unknown): void;
+  warn(message: string, attrs?: LogAttrs, error?: unknown): void;
 }
 declare function createLogger(module: string): PhotonLogger;
-
+//#endregion
+//#region src/sanitize.d.ts
 /**
  * Mask a phone number, keeping the leading `+` (if any) plus the first 3 digits
  * and the last 4 digits visible. Example: `+13315553374` -> `+133xxxxx3374`.
@@ -66,47 +115,48 @@ declare function sanitizeEmail(input: string): string;
  * them to span status.
  */
 declare function sanitizeErrorMessage(input: string): string;
-
+//#endregion
+//#region src/setup.d.ts
 interface SetupOtelOptions {
-    /**
-     * Default OTLP/HTTP base endpoint (e.g. `https://otel.example.com`). The
-     * `/v1/traces` and `/v1/logs` paths are appended automatically. Standard
-     * `OTEL_EXPORTER_OTLP_*` env vars always take precedence.
-     */
-    endpoint?: string;
-    /**
-     * Default OTLP headers (e.g. `{ Authorization: "Basic ..." }`). Merged with
-     * any headers parsed from `OTEL_EXPORTER_OTLP_HEADERS`; env values win on
-     * conflicts.
-     */
-    headers?: Record<string, string>;
-    /**
-     * Auto-instrument outbound `globalThis.fetch` with CLIENT spans and W3C
-     * trace-context propagation. On Bun this is the only fetch instrumentation
-     * that works (diagnostics_channel-based instrumentations emit nothing on
-     * Bun's native fetch); it works identically on Node.
-     *
-     * `true` enables with defaults; pass an object to filter URLs via `ignore`.
-     * Defaults to enabled when a traces endpoint is configured. Pass `false` to
-     * disable.
-     */
-    instrumentFetch?: boolean | InstrumentFetchOptions;
-    /**
-     * Minimum log level emitted by `createLogger()` (to both OTLP and console).
-     * The `LOG_LEVEL` env var still takes precedence. Defaults to `debug` in
-     * development and `info` otherwise.
-     */
-    logLevel?: LogLevel;
-    /**
-     * Extra resource attributes attached to every span/log alongside
-     * `service.name` / `service.version`.
-     */
-    resourceAttributes?: Record<string, string | number | boolean>;
-    serviceName: string;
-    serviceVersion?: string;
+  /**
+   * Default OTLP/HTTP base endpoint (e.g. `https://otel.example.com`). The
+   * `/v1/traces` and `/v1/logs` paths are appended automatically. Standard
+   * `OTEL_EXPORTER_OTLP_*` env vars always take precedence.
+   */
+  endpoint?: string;
+  /**
+   * Default OTLP headers (e.g. `{ Authorization: "Basic ..." }`). Merged with
+   * any headers parsed from `OTEL_EXPORTER_OTLP_HEADERS`; env values win on
+   * conflicts.
+   */
+  headers?: Record<string, string>;
+  /**
+   * Auto-instrument outbound `globalThis.fetch` with CLIENT spans and W3C
+   * trace-context propagation. On Bun this is the only fetch instrumentation
+   * that works (diagnostics_channel-based instrumentations emit nothing on
+   * Bun's native fetch); it works identically on Node.
+   *
+   * `true` enables with defaults; pass an object to filter URLs via `ignore`.
+   * Defaults to enabled when a traces endpoint is configured. Pass `false` to
+   * disable.
+   */
+  instrumentFetch?: boolean | InstrumentFetchOptions;
+  /**
+   * Minimum log level emitted by `createLogger()` (to both OTLP and console).
+   * The `LOG_LEVEL` env var still takes precedence. Defaults to `debug` in
+   * development and `info` otherwise.
+   */
+  logLevel?: LogLevel;
+  /**
+   * Extra resource attributes attached to every span/log alongside
+   * `service.name` / `service.version`.
+   */
+  resourceAttributes?: Record<string, string | number | boolean>;
+  serviceName: string;
+  serviceVersion?: string;
 }
 interface OtelHandle {
-    shutdown(): Promise<void>;
+  shutdown(): Promise<void>;
 }
 /**
  * Boot an OTLP/HTTP-based OpenTelemetry pipeline (traces + logs).
@@ -124,10 +174,13 @@ declare function setupOtel(options: SetupOtelOptions): OtelHandle;
  * `setupOtel` has already run in this process.
  */
 declare function isOtelActive(): boolean;
-
-declare const PHOTON_OTEL_VERSION = "0.1.0";
-
+//#endregion
+//#region src/version.d.ts
+declare const PHOTON_OTEL_VERSION = "1.1.0";
+//#endregion
+//#region src/with-span.d.ts
 declare function withSpan<T>(name: string, fn: () => Promise<T> | T): Promise<T>;
 declare function withSpan<T>(name: string, attrs: LogAttrs, fn: () => Promise<T> | T): Promise<T>;
-
-export { type FetchInstrumentation, type InstrumentFetchOptions, type LogAttrs, type LogLevel, type OtelHandle, PHOTON_OTEL_VERSION, type PhotonLogger, type SetupOtelOptions, createLogger, getLogLevel, instrumentFetch, isOtelActive, sanitizeEmail, sanitizeErrorMessage, sanitizePhone, setLogLevel, setupOtel, withSpan };
+//#endregion
+export { type FetchInstrumentation, type FetchSpanOptions, type InstrumentFetchOptions, type LogAttrs, type LogLevel, type OtelHandle, PHOTON_OTEL_VERSION, type PhotonLogger, type SetupOtelOptions, createInstrumentedFetch, createLogger, getLogLevel, instrumentFetch, isOtelActive, sanitizeEmail, sanitizeErrorMessage, sanitizePhone, setLogLevel, setupOtel, withSpan };
+//# sourceMappingURL=index.d.ts.map