feat(fetch): Add redactUrl option and sanitizeUrl helper

Allows callers to rewrite `url.full` before it is recorded as a span
attribute, stripping secrets from query strings or paths while keeping
the span. Unlike `ignore`, the request still goes through.

`sanitizeUrl()` follows OTel URL semconv: sensitive query-parameter
values and `user:pass@` credentials are replaced with `REDACTED`, with
parameter keys preserved. A built-in default list covers common AWS/GCP
signing parameters.

On Node, requesting `redactUrl` forces the `globalThis.fetch` wrap
instead of the native undici instrumentation, which has no hook to
rewrite `url.full`.

Author: underthestars-zhy

README.md

@@ -142,15 +142,18 @@ Options (`instrumentFetch`):
   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.
+- **`redactUrl`:** `instrumentFetch: { redactUrl: (url) => sanitizeUrl(url, { params: ["token"] }) }`
+  rewrites the URL stored as `url.full`, so you keep the span but drop secrets from the query string or
+  path. On Node it forces the `globalThis.fetch` wrap (undici can't rewrite `url.full`).
 
 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.
+- **`url.full` includes the query string** on both. If your URLs carry secrets there, strip them with
+  `redactUrl` (keeps the span) or drop the request with `ignore`.
 - **Native fetch tracing needs Node ≥ 20.6** (the undici instrumentation's floor); older 20.x falls
   back to the global wrap.
 
@@ -180,7 +183,8 @@ const client = new 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).
+  into every span (the practical way to tell different SDKs' spans apart); `redactUrl: (url) => string`
+  rewrites `url.full` to strip secrets (pair with `sanitizeUrl`).
 - Always uses the wrapper technique, so it behaves identically on Bun and Node (the native undici
   instrumentation can't target a single instance).
 

docs/configuration.mdx

@@ -204,6 +204,20 @@ setupOtel({
 });
 ```
 
+To keep the span but strip secrets from the URL, use `redactUrl` with the `sanitizeUrl()` helper:
+
+```ts
+import { sanitizeUrl, setupOtel } from "@photon-ai/otel";
+
+setupOtel({
+  serviceName: "orders-api",
+  endpoint: "http://localhost:4318",
+  instrumentFetch: {
+    redactUrl: (url) => sanitizeUrl(url, { params: ["token", "api_key"] }),
+  },
+});
+```
+
 On Node, `setupOtel()` uses the native `@opentelemetry/instrumentation-undici` by default; on Bun it wraps `globalThis.fetch`. Force the wrap on both runtimes with `mode: "global"`:
 
 ```ts
@@ -236,4 +250,4 @@ The package always excludes its own OTLP trace and log exporter endpoints from f
 - Set `serviceVersion` from your release artifact when possible.
 - Prefer stable resource attributes over high-cardinality request values.
 - Use `LOG_LEVEL=debug` temporarily when debugging production incidents, then return to `info` or higher.
-- Avoid putting secrets in URL query strings because fetch spans include `url.full`.
+- Avoid putting secrets in URL query strings (fetch spans include `url.full`); when unavoidable, strip them with the `redactUrl` option and the `sanitizeUrl()` helper.

docs/guides/fetch-instrumentation.mdx

@@ -107,7 +107,25 @@ When a URL is ignored:
 - no span is emitted
 - trace headers are not injected by this wrapper
 
-Use this for health checks, high-volume polling, or URLs with secrets in the query string.
+Use this for health checks or high-volume polling. To keep the span but hide a secret in the URL, reach for `redactUrl` instead (below).
+
+## Redacting URLs
+
+`ignore` drops the whole span. When you want to keep the span but strip a secret from the URL, use `redactUrl` — it rewrites the value stored as `url.full` while leaving `server.address` / `server.port` (derived from the original URL) and the rest of the span intact.
+
+```ts
+import { instrumentFetch, sanitizeUrl } from "@photon-ai/otel";
+
+instrumentFetch({
+  redactUrl: (url) => sanitizeUrl(url, { params: ["token", "api_key"] }),
+});
+```
+
+`sanitizeUrl()` follows the OpenTelemetry URL semantic conventions: it replaces sensitive query-parameter values and `user:pass@` credentials with the literal `REDACTED`, keeping the parameter key (`token=REDACTED`). It also redacts a built-in default list (`X-Amz-Signature`, `X-Amz-Credential`, `X-Amz-Security-Token`, `sig`, `X-Goog-Signature`). Pass your own names in `params`, or write any `(url) => string` function for full control — including stripping tokens from path segments.
+
+The redactor only changes what telemetry records; the real request still uses the original URL.
+
+On Node, setting `redactUrl` forces the `globalThis.fetch` wrap instead of the native undici instrumentation (which has no hook to rewrite `url.full`), trading undici's richer attributes for the redaction — the same tradeoff as static `attributes`.
 
 ## Automatic OTLP endpoint exclusion
 
@@ -172,14 +190,14 @@ Native fetch tracing requires Node 20.6 or newer (the undici instrumentation's f
 
 Fetch spans include `url.full`, which includes the query string.
 
-Do not put secrets, tokens, emails, or phone numbers in query strings. If you must call an endpoint with sensitive query parameters, use `ignore` to skip that URL or sanitize upstream.
+Prefer keeping secrets, tokens, emails, and phone numbers out of query strings. When you can't, use [`redactUrl`](#redacting-urls) to strip them while keeping the span, or `ignore` to skip the URL entirely.
 
-Thrown fetch error messages are sanitized before being used as span status messages by the `globalThis.fetch` wrap (Bun, or `mode: "global"`). The native undici instrumentation on Node does not scrub status messages — use `mode: "global"` if you need that scrubbing on Node. URL attributes are not sanitized on either path.
+Thrown fetch error messages are sanitized before being used as span status messages by the `globalThis.fetch` wrap (Bun, or `mode: "global"`). The native undici instrumentation on Node does not scrub status messages — use `mode: "global"` if you need that scrubbing on Node. Unless you set `redactUrl`, URL attributes are recorded as-is on both paths.
 
 ## Best practices
 
 - Prefer automatic setup-managed instrumentation for services.
-- Use `ignore` for health checks and sensitive URLs.
-- Keep secrets out of query strings.
+- Use `ignore` for health checks; use `redactUrl` to strip secrets from traced URLs.
+- Keep secrets out of query strings where you can.
 - Call `shutdown()` or `unpatch()` in tests to restore global fetch.
 - Install setup before code starts making outbound requests.

docs/guides/pii-scrubbing.mdx

@@ -3,11 +3,12 @@ title: "PII scrubbing"
 description: "Use the sanitize helpers and understand where automatic scrubbing does and does not happen."
 ---
 
-The package exports three helpers for masking common personally identifiable information:
+The package exports helpers for masking common personally identifiable information and URL secrets:
 
 - `sanitizeEmail(input)`
 - `sanitizePhone(input)`
 - `sanitizeErrorMessage(input)`
+- `sanitizeUrl(input, options?)`
 
 They are intentionally small and predictable. They are not a full data-loss-prevention system.
 
@@ -79,7 +80,7 @@ The package does not sanitize:
 - log attributes
 - logger exception attributes
 - span attributes
-- fetch `url.full`
+- fetch `url.full` (opt in with the `redactUrl` option — see [URL safety](#url-safety))
 - response bodies
 - request bodies
 - headers
@@ -123,21 +124,33 @@ Prefer stable internal identifiers over emails or phone numbers.
 
 ## URL safety
 
-Fetch spans include `url.full`, including query parameters.
+Fetch spans include `url.full`, including query parameters. When a URL carries a token, API key, or other secret, redact it with the `redactUrl` fetch option so the span keeps everything except the secret. The `sanitizeUrl()` helper implements semantic-convention redaction — sensitive query-parameter values and `user:pass@` credentials are replaced with the literal `REDACTED`, with the key preserved:
 
-Avoid URLs like:
+```ts
+import { sanitizeUrl, setupOtel } from "@photon-ai/otel";
 
-```txt
-https://api.example.com/search?email=foo.bar@example.com
+setupOtel({
+  serviceName: "orders-api",
+  endpoint: "http://localhost:4318",
+  instrumentFetch: {
+    redactUrl: (url) => sanitizeUrl(url, { params: ["token", "api_key"] }),
+  },
+});
 ```
 
-Prefer:
+Or per SDK, without touching the global fetch:
 
-```txt
-https://api.example.com/search
+```ts
+import { createInstrumentedFetch, sanitizeUrl } from "@photon-ai/otel";
+
+const fetch = createInstrumentedFetch(undefined, {
+  redactUrl: (url) => sanitizeUrl(url),
+});
 ```
 
-with the sensitive value in a request body or header that your telemetry pipeline does not record. If you cannot avoid sensitive query strings, configure fetch instrumentation to ignore those URLs.
+`redactUrl` keeps the span — unlike `ignore`, which drops it entirely. On Node it forces the `globalThis.fetch` wrap, because the native undici instrumentation has no hook to rewrite `url.full`.
+
+Even with redaction available, prefer keeping secrets out of URLs in the first place — put the sensitive value in a request body or header your telemetry pipeline does not record. Reserve `ignore` for URLs you do not want traced at all.
 
 ## Best practices
 

docs/reference/api.mdx

@@ -15,6 +15,7 @@ import {
   sanitizeEmail,
   sanitizeErrorMessage,
   sanitizePhone,
+  sanitizeUrl,
   setLogLevel,
   setupOtel,
   withSpan,
@@ -185,11 +186,14 @@ function instrumentFetch(options?: InstrumentFetchOptions): FetchInstrumentation
 interface FetchSpanOptions {
   ignore?: (url: string) => boolean;
   attributes?: Attributes;
+  redactUrl?: (url: string) => string;
 }
 ```
 
 `ignore` skips spans for matching URLs. `attributes` (the OpenTelemetry `Attributes` type) merges static attributes into every span this instrumentation produces — useful for tagging an SDK's traffic, such as `{ "peer.service": "openai" }`.
 
+`redactUrl` rewrites the URL before it is stored as `url.full`, so you can strip secrets from the query string or path while keeping the span (unlike `ignore`, which drops the span entirely). `server.address` / `server.port` are still derived from the original URL. Pair it with [`sanitizeUrl`](#sanitizeurl-url-options). On Node, setting `redactUrl` forces the `globalThis.fetch` wrap, because the native undici instrumentation has no hook to rewrite `url.full`.
+
 ### `InstrumentFetchOptions`
 
 ```ts
@@ -237,6 +241,7 @@ function createInstrumentedFetch(
 
 - Wraps the given fetch so each non-ignored request creates a client span with HTTP attributes and W3C trace-context injection.
 - Merges `options.attributes` into every span.
+- Applies `options.redactUrl` to the stored `url.full`, if provided.
 - Returns the fetch function directly — there is no global lifecycle and no `unpatch()`.
 - Is idempotent: passing an already-instrumented fetch returns it unchanged.
 - Always uses the wrapper technique, so it works identically on Bun and Node.
@@ -288,6 +293,43 @@ sanitizeErrorMessage("contact foo.bar@example.com or +13315553374");
 // "contact fo***@e***.com or +133xxxx3374"
 ```
 
+## `sanitizeUrl(url, options)`
+
+Redacts secrets from a URL before it is recorded as a span attribute, following the OpenTelemetry URL semantic conventions: sensitive query-parameter values and `user:pass@` credentials are replaced with the literal `REDACTED`, with the key preserved (`sig=REDACTED`). Non-sensitive parameters and the path are left intact.
+
+```ts
+function sanitizeUrl(url: string, options?: SanitizeUrlOptions): string;
+
+interface SanitizeUrlOptions {
+  params?: string[];
+  redactDefaults?: boolean;
+}
+```
+
+- `params` — additional query-parameter names to redact, on top of the built-in list. Case-sensitive, matching the semantic conventions.
+- `redactDefaults` — redact the built-in semconv list (`X-Amz-Signature`, `X-Amz-Credential`, `X-Amz-Security-Token`, `sig`, `X-Goog-Signature`) and `user:pass@` credentials. Defaults to `true`.
+
+Unparseable input — and input with nothing to redact — is returned unchanged.
+
+It is designed to pair with the `redactUrl` fetch option:
+
+```ts
+import { createInstrumentedFetch, sanitizeUrl } from "@photon-ai/otel";
+
+const fetch = createInstrumentedFetch(undefined, {
+  redactUrl: (url) => sanitizeUrl(url, { params: ["token", "api_key"] }),
+});
+```
+
+Example:
+
+```ts
+sanitizeUrl("https://api.example.com/v1?token=secret&page=2", {
+  params: ["token"],
+});
+// "https://api.example.com/v1?token=REDACTED&page=2"
+```
+
 ## `PHOTON_OTEL_VERSION`
 
 Package version constant.

docs/reference/testing.mdx

@@ -153,4 +153,4 @@ Then verify:
 | Fetch spans missing | no traces endpoint or `instrumentFetch: false` | configure trace endpoint or force `instrumentFetch: true` |
 | Logs not correlated with traces | setup ran too late or context was replaced | call `setupOtel()` before work begins |
 | Process exits before telemetry appears | batch processors did not flush | await `shutdown()` |
-| Sensitive query values visible | fetch spans record `url.full` | remove sensitive query strings or ignore those URLs |
+| Sensitive query values visible | fetch spans record `url.full` | strip them with the `redactUrl` option (`sanitizeUrl()` helper), or `ignore` the URL |

src/index.ts

@@ -15,9 +15,11 @@ export {
   setLogLevel,
 } from "./logger";
 export {
+  type SanitizeUrlOptions,
   sanitizeEmail,
   sanitizeErrorMessage,
   sanitizePhone,
+  sanitizeUrl,
 } from "./sanitize";
 export {
   isOtelActive,

src/instrument-fetch-native.ts

@@ -81,11 +81,14 @@ export function instrumentFetchNative(
   options: InstrumentFetchOptions | undefined,
   requireFn: RequireFn
 ): FetchInstrumentation | undefined {
-  // The undici instrumentation has no hook to stamp caller-supplied static
-  // attributes onto every span, so when they're requested, decline the native
-  // path and let the caller fall back to the globalThis.fetch wrap (which does
-  // apply them).
-  if (options?.attributes && Object.keys(options.attributes).length > 0) {
+  // The undici instrumentation exposes no hook to stamp caller-supplied static
+  // attributes on every span, nor to rewrite `url.full` for redaction. When
+  // either is requested, decline the native path and let the caller fall back
+  // to the globalThis.fetch wrap (which applies both).
+  const hasStaticAttributes =
+    options?.attributes !== undefined &&
+    Object.keys(options.attributes).length > 0;
+  if (hasStaticAttributes || options?.redactUrl !== undefined) {
     return;
   }
 

src/instrument-fetch.ts

@@ -31,6 +31,20 @@ export interface FetchSpanOptions {
    * query string. The request is still performed — only the span is skipped.
    */
   ignore?: (url: string) => boolean;
+  /**
+   * Rewrite the request URL before it is stored as `url.full`. Use this to
+   * strip tokens/secrets from the query string or path while still keeping the
+   * span (unlike `ignore`, which drops the span entirely). Receives the
+   * absolute URL and returns the value to record; `server.address` /
+   * `server.port` are still derived from the ORIGINAL URL, so an aggressive
+   * redactor can't break host resolution. Pair with the `sanitizeUrl()` helper
+   * for semconv-style query-parameter redaction.
+   *
+   * On Node, requesting `redactUrl` forces the `globalThis.fetch` wrap instead
+   * of the native undici instrumentation (which has no hook to rewrite
+   * `url.full`), trading undici's richer attributes for the redaction.
+   */
+  redactUrl?: (url: string) => string;
 }
 
 export interface InstrumentFetchOptions extends FetchSpanOptions {
@@ -126,10 +140,16 @@ function toAttributes(attrs: Attributes): Attributes {
   return out;
 }
 
-function fetchAttributes(method: string, url: string): Attributes {
+function fetchAttributes(
+  method: string,
+  url: string,
+  redactUrl?: (url: string) => string
+): Attributes {
   const attrs: Attributes = {
     [ATTR_HTTP_REQUEST_METHOD]: method,
-    [ATTR_URL_FULL]: url,
+    // server.* below come from the original URL; only the stored full URL is
+    // redacted, so host/port resolution is unaffected by the redactor.
+    [ATTR_URL_FULL]: redactUrl ? redactUrl(url) : url,
   };
   try {
     const parsed = new URL(url);
@@ -198,7 +218,7 @@ function buildWrappedFetch(
       if (staticAttributes) {
         span.setAttributes(staticAttributes);
       }
-      span.setAttributes(fetchAttributes(name, url));
+      span.setAttributes(fetchAttributes(name, url, options?.redactUrl));
       try {
         const headers = buildPropagatedHeaders(input, init);
         const response = await callOriginal(original, input, init, headers);