@foam-ai/node 0.1.0-alpha.4 → 0.1.0-alpha.6

package/README.md

@@ -1,14 +1,12 @@
 # Foam OpenTelemetry SDK for Node.js
 
-`@foam-ai/node` is Foam's OpenTelemetry distribution for Node.js. It configures
-the official OpenTelemetry JavaScript SDK, node automatic instrumentations, and
-OTLP/HTTP exporters with one `init()` call.
+`@foam-ai/node` is Foam's OpenTelemetry distribution for Node.js.
 
 ## Requirements
 
 - Node.js `^18.19.0 || >=20.6.0`, matching the supported engine range of
-  `@opentelemetry/auto-instrumentations-node`
-- A Foam ingest token, stored as `FOAM_OTEL_TOKEN`
+    `@opentelemetry/auto-instrumentations-node`
+- Foam ingest token, stored as `FOAM_OTEL_TOKEN`
 
 ## Install
 
@@ -18,11 +16,14 @@ npm install @foam-ai/node
 
 ## Initialize
 
-Call `init()` before any application code loads so OpenTelemetry can patch
-libraries as they import. Don't import the app from the same file: ESM runs
-static imports before `init()`. Set `enabled: false` to disable Foam. Store
-the ingest token as `FOAM_OTEL_TOKEN` and pass `process.env.FOAM_OTEL_TOKEN`;
-do not hardcode it.
+Call `init()` before your app loads so OpenTelemetry can patch libraries as
+they import. Put `init()` in its own file and preload it with `--import` or
+`--require` (below).
+
+Set `enabled: false` to turn Foam off.
+
+Store the ingest token as `FOAM_OTEL_TOKEN` and pass
+`process.env.FOAM_OTEL_TOKEN` to `init()`.
 
 ### TypeScript
 
@@ -40,13 +41,14 @@ init({
 });
 ```
 
-Compile it with the app. If TypeScript emits ESM:
+Compile it with the app. If TypeScript emits ESM, preload with `--import`
+(same rule as ESM below):
 
 ```sh
 node --import ./dist/instrumentation.js ./dist/app.js
 ```
 
-If TypeScript emits CommonJS:
+If TypeScript emits CommonJS, preload with `--require`:
 
 ```sh
 node --require ./dist/instrumentation.js ./dist/app.js
@@ -60,7 +62,11 @@ node --import tsx --import ./instrumentation.ts ./src/app.ts
 
 ### ESM
 
-Create `instrumentation.mjs` with the same `init()` call, then:
+Create `instrumentation.mjs` with the same `init()` call.
+
+`import` lines always run first, even if you write `init()` above them.
+Don't import your app from that file. Use `--import`, or
+`await import("./app.js")` after `init()`:
 
 ```sh
 node --import ./instrumentation.mjs ./app.js
@@ -68,7 +74,9 @@ node --import ./instrumentation.mjs ./app.js
 
 ### CommonJS
 
-Create `instrumentation.cjs`:
+Create `instrumentation.cjs`. `require()` runs in order, so `init()` then
+`require("./app")` in this file is fine. `--require` is still the better
+preload:
 
 ```js
 const { init } = require("@foam-ai/node");
@@ -90,10 +98,10 @@ node --require ./instrumentation.cjs ./app.js
 
 ### `init(options)`
 
-Starts Foam: resource, sampler, OTLP exporters, automatic instrumentations,
-and the W3C propagator.
+Sets up tracing, metrics, logs, auto-instrumentation, OTLP export to Foam,
+and W3C context propagation.
 
-Call this once when Foam can own all of one of OTEL slots. 
+Call this once. Use it when Foam should run OpenTelemetry for the process.
 
 ```js
 import { init } from "@foam-ai/node";
@@ -113,6 +121,7 @@ init({
   environment,
   enabled,
   token,
+  endpoint?,
   version?,
   sampleRate?,
   additionalInstrumentations?,
@@ -123,51 +132,95 @@ init({
   disableLogSending?,
   networkCapture?,
   ignoredOutboundHosts?,
-  diagnostics?,
+  redact?,
+  beforeSend?,
 }): void
 ```
 
 `name`, `environment`, and `enabled` are required.
-`token` is required only when enabled; store it as `FOAM_OTEL_TOKEN`.
-`sampleRate` accepts values from `0` through `1` and defaults to
-`1`.
-
-Foam always installs this sampler rather than reading `OTEL_TRACES_SAMPLER`.
-Diagnostics default to enabled.
-
-`additionalResourceAttributes` adds custom resource attributes (for example
-`team` or `cloud.region`) to all telemetry. The Basic API's `name`,
-`environment`, and `version` options take precedence over matching keys.
-Foam also sets `telemetry.sdk.*` from the OpenTelemetry SDK and
-`telemetry.distro.name` / `telemetry.distro.version` for this distribution.
-
-Foam detects process, host, and OS attributes from this machine. It does not
-run cloud or container resource detectors (AWS, GCP, Azure, Alibaba, or cgroup
-`container.id`), which call metadata APIs at startup. Set cloud or container
-identity with `additionalResourceAttributes`.
-
-`additionalInstrumentations` registers extra OpenTelemetry instrumentations
-alongside Foam's Node auto bundle and `ConsoleInstrumentation`. Foam already
-enables [`@opentelemetry/instrumentation-openai`](https://www.npmjs.com/package/@opentelemetry/instrumentation-openai)
-from that bundle (`openai` `>=4.19 <7`); message content is captured only when
-`networkCapture` is `"advanced"`. Use this option for libraries Foam does not
-ship, such as community Anthropic instrumentations
-([`@traceloop/instrumentation-anthropic`](https://www.npmjs.com/package/@traceloop/instrumentation-anthropic)
-or
-[`@arizeai/openinference-instrumentation-anthropic`](https://www.npmjs.com/package/@arizeai/openinference-instrumentation-anthropic)),
-or to replace a bundled instrumentation by name: last entry wins, and Foam
-disables its own copy. Replacing HTTP or Undici this way also replaces Foam's
-network capture hooks.
-
-### `createFoamIngestSpanProcessor(name, environment, token)`
-
-Returns a span processor that exports traces to Foam without taking over the
-global TracerProvider.
-
-Use this when another OpenTelemetry SDK already owns traces and you only need
-Foam as an extra export destination.
+`token` is required only when Foam is enabled; store it as `FOAM_OTEL_TOKEN`.
+
+`endpoint` defaults to Foam's OTLP endpoint and is where all telemetry is
+delivered. Override it only to route through a Foam-compatible OTLP
+gateway, such as an egress proxy or a local collector. It must be an
+`http(s)` URL; its host is always excluded from outbound tracing so
+export calls do not become client spans.
+
+`version` sets `service.version`. 
+
+`sampleRate` is a number from `0` to `1` and defaults to `1`. Rarely if ever updated. Only change it if you are sending telemetry in the petabytes range.
+
+`additionalInstrumentations` adds extra OpenTelemetry instrumentations next
+to Foam's Node auto bundle and `ConsoleInstrumentation`.
+
+`additionalSpanProcessors`, `additionalLogRecordProcessors`, and
+`additionalMetricReaders` add extra processors/readers from other vendors next to Foam's
+exporters. Note: Never add Foam's own processors/readers helpers.
+
+`additionalResourceAttributes` adds extra resource attributes (for example
+`team` or `cloud.region`) to all telemetry.
+
+`disableLogSending` defaults to `false`. Set `true` to stop Foam from
+adding its own sending path to supported loggers; trace correlation in
+log records is unaffected (see Loggers).
+
+`networkCapture` defaults to `"basic"`. Upgrade to `"advanced"` unless you
+cannot; it gives much more powerful HTTP and Undici capture. See Network capture.
+
+`redact` adds keys to Foam's built-in redaction. `secrets` preserves the last
+four characters of longer values; `pii` fully masks values.
 
 ```js
+init({
+  // ...
+  redact: {
+    secrets: ["internalId", "internalReference"],
+    pii: ["customerEmail", "homeAddress"],
+  },
+});
+```
+
+`beforeSend` can edit or drop spans and logs before Foam exports them. Return
+the event to send it or `null` to drop it.
+
+```js
+init({
+  // ...
+  beforeSend: (event) => {
+    if (event.type === "span" && event.attributes["url.path"] === "/health") {
+      return null; // drop health checks
+    }
+    delete event.attributes["user.email"];
+    return event;
+  },
+});
+```
+
+Metrics are not passed through `beforeSend`. See Redaction for coverage.
+
+`ignoredOutboundHosts` skips outbound HTTP tracing for those hostnames.
+The configured `endpoint` host is always skipped so export calls do not
+become client spans. Add extra hosts for high-volume clients that would drown traces,
+for example a sidecar health-check host (`localhost`) or another vendor's
+OTLP ingest host you already export to.
+
+TODO(pcga11): Add other common Gen AI providers.
+
+If another SDK already registered traces, metrics, logs, or the propagator,
+`init()` leaves the signal's slot untouched and only takes what is available. When a slot is taken, use its ingest helper instead.
+
+### `createFoamIngestSpanProcessor(name, environment, token, options?)`
+
+The helper returns a span processor but does not attach it to the
+application's provider. Include it in the `spanProcessors` option when
+constructing `BasicTracerProvider`. It cannot be added after provider
+construction in `@opentelemetry/sdk-trace-base` 2.10; the old
+`addSpanProcessor()` API is obsolete. If another SDK creates the provider,
+configure the processor through that SDK's startup options.
+
+```js
+import { trace } from "@opentelemetry/api";
+import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base";
 import { createFoamIngestSpanProcessor } from "@foam-ai/node";
 
 const spanProcessor = createFoamIngestSpanProcessor(
@@ -175,17 +228,24 @@ const spanProcessor = createFoamIngestSpanProcessor(
   "production",
   process.env.FOAM_OTEL_TOKEN,
 );
-tracerProvider.addSpanProcessor(spanProcessor);
+const tracerProvider = new BasicTracerProvider({
+  spanProcessors: [spanProcessor],
+});
+trace.setGlobalTracerProvider(tracerProvider);
 ```
 
-### `createFoamIngestLogRecordProcessor(name, environment, token)`
-
-Returns a log-record processor that exports logs to Foam without taking over
-the global LoggerProvider.
+### `createFoamIngestLogRecordProcessor(name, environment, token, options?)`
 
-Use this when another SDK already owns logs and you want those records in Foam.
+The helper returns a log-record processor but does not attach it to the
+application's provider. Include it in the `processors` option when constructing
+`LoggerProvider`. It cannot be added after provider construction in
+`@opentelemetry/sdk-logs` 0.221; the old `addLogRecordProcessor()` API is
+obsolete. If another SDK creates the provider, configure the processor through
+that SDK's startup options.
 
 ```js
+import { logs } from "@opentelemetry/api-logs";
+import { LoggerProvider } from "@opentelemetry/sdk-logs";
 import { createFoamIngestLogRecordProcessor } from "@foam-ai/node";
 
 const logRecordProcessor = createFoamIngestLogRecordProcessor(
@@ -193,18 +253,27 @@ const logRecordProcessor = createFoamIngestLogRecordProcessor(
   "production",
   process.env.FOAM_OTEL_TOKEN,
 );
-loggerProvider.addLogRecordProcessor(logRecordProcessor);
+const loggerProvider = new LoggerProvider({
+  processors: [logRecordProcessor],
+});
+logs.setGlobalLoggerProvider(loggerProvider);
 ```
 
-### `createFoamIngestMetricReader(name, environment, token)`
+Both ingest helpers accept the same `redact` and `beforeSend` options as
+`init()`.
 
-Returns a metric reader that exports metrics to Foam without taking over the
-global MeterProvider.
+### `createFoamIngestMetricReader(name, environment, token)`
 
-Use this when another SDK already owns metrics and you want those meters in
-Foam.
+The helper returns a metric reader but does not attach it to the application's
+provider. Include it in the `readers` option when constructing `MeterProvider`.
+It cannot be added after provider construction in
+`@opentelemetry/sdk-metrics` 2.10; the old `addMetricReader()` API is obsolete.
+If another SDK creates the provider, configure the reader through that SDK's
+startup options.
 
 ```js
+import { metrics } from "@opentelemetry/api";
+import { MeterProvider } from "@opentelemetry/sdk-metrics";
 import { createFoamIngestMetricReader } from "@foam-ai/node";
 
 const metricReader = createFoamIngestMetricReader(
@@ -212,42 +281,65 @@ const metricReader = createFoamIngestMetricReader(
   "production",
   process.env.FOAM_OTEL_TOKEN,
 );
-meterProvider.addMetricReader(metricReader);
+const meterProvider = new MeterProvider({
+  readers: [metricReader],
+});
+metrics.setGlobalMeterProvider(meterProvider);
+```
+
+If a vendor SDK does not expose a processor or reader startup option, add Foam
+at the collector instead.
+
+If the other SDK already set `service.name` or environment,
+Foam's values overwrite them on that copy only. The original spans, logs,
+and metrics are left unchanged. For the Foam SDK, ensure all of the signals (spans, logs and metrics)
+carry identical `service.name`.
+
+Don't use `init()` and an ingest helper for the same signal. If another
+SDK already owns traces (or another signal), call `init()` for the rest
+and attach ingest only to the provider you don't own. Don't pass ingest
+helpers as `additionalSpanProcessors` or extra readers: `init()` already
+installs Foam exporters.
+
+Ingest helpers do not register instrumentations. If you cannot call
+`init()`, register them with the official OpenTelemetry API
+before the app imports those libraries:
+
+```js
+import { registerInstrumentations } from "@opentelemetry/instrumentation";
+import { RedisInstrumentation } from "@opentelemetry/instrumentation-redis";
+import { createFoamIngestSpanProcessor } from "@foam-ai/node";
+
+registerInstrumentations({
+  instrumentations: [new RedisInstrumentation()],
+});
 ```
 
-The factories do not claim global OTel providers. `name`, `environment`, and
-`token` are required; Foam stamps `service.name`,
-`deployment.environment.name`, and `foam.ingest.tier=external` onto the
-exported resource. If the other SDK already set `service.name` or environment,
-Foam's values overwrite them on the copy sent to Foam only. The original
-spans, logs, and metrics are not mutated.
-
-Use `init()` or ingest, not both on the same signal. If another SDK already
-owns traces (or another slot), call `init()` for the free signals and attach
-ingest only to the provider you do not own. Do not pass ingest factories as
-`additionalSpanProcessors` / readers: `init()` already installs Foam exporters.
-
-The global propagator is also first-wins. OpenTelemetry allows only one, and
-HTTP, Express, Undici, and Fetch all call it to copy trace headers onto
-requests. Foam registers W3C Trace Context and W3C Baggage
-(`traceparent`, `tracestate`, `baggage`) and nothing else: not B3, Jaeger, or
-AWS X-Ray. If Foam wins the slot, auto-instrumented HTTP is W3C-only. If
-another SDK already registered a propagator, Foam keeps it,
-`getState().signals.baggage` is `false`, and HTTP speaks that winner's format.
-A B3-only (or Jaeger/X-Ray-only) winner will not send or honor `traceparent`,
-so a Foam peer that only understands W3C starts a new trace. Foam does not
-wrap inject/extract to dual-read those formats or add W3C headers on top.
-Initialize Foam first, or have the other SDK register a composite that
-includes W3C, if those headers must be on HTTP.
+Attach the ingest helper to the other SDK's provider as in the examples
+above. If that SDK already instruments the same library, don't register a
+second copy.
+
+OpenTelemetry allows only one global propagator per signal. Foam registers W3C Trace
+Context and W3C Baggage (`traceparent`, `tracestate`, `baggage`), not B3,
+Jaeger, or AWS X-Ray. Auto-instrumented HTTP uses whichever propagator
+won. If another SDK already registered a propagator, Foam keeps it and
+`getState().signals.baggage` is `"none"`. A non-W3C propagator will not
+send `traceparent`, so a Foam peer starts a new trace. Foam does not add
+W3C headers on top.
+
+A work around is to initialize Foam first, or include W3C in the other
+SDK's composite, if those headers must be on HTTP.
+
+TODO(pcga11): Handle traceparent conflict^
 
 ### `injectTraceContext(headers)`
 
 Writes W3C `traceparent`, `tracestate`, and `baggage` onto a header map.
 
-Use this when you send a message yourself (Kafka, a queue, a custom socket).
-Auto-instrumented HTTP, Express, Undici, and Fetch already inject these
-headers; do not call this on ordinary HTTP. This path uses Foam's local W3C
-propagator even if Foam lost the global slot.
+Use this when you send a message yourself (Kafka, a queue, a custom
+socket). Auto-instrumented HTTP, Express, Undici, and Fetch already inject
+these headers; don't call this on ordinary HTTP. This uses Foam's local
+W3C propagator so it works even if Foam did not get the global one.
 
 ```js
 const headers = {};
@@ -257,10 +349,11 @@ await kafka.send({ value: payload, headers });
 
 ### `extractTraceContext(headers)`
 
-Reads W3C trace and baggage headers and returns a parent OpenTelemetry context.
+Reads W3C trace and baggage headers and returns a parent OpenTelemetry
+context.
 
-Use this when you receive a message on a custom transport so the work continues
-the same trace. Ignoring those headers starts a new one.
+Use this when receiving a message on a custom transport. Without extraction,
+the handler loses the propagated parent context.
 
 ```js
 import { context } from "@opentelemetry/api";
@@ -269,25 +362,22 @@ const parent = extractTraceContext(message.headers);
 await context.with(parent, () => handle(message));
 ```
 
-### `setBaggage(key, value)`
-
-Stores a small string on the current request context.
+### `setBaggage(key, value, callback)`
 
-Use this for request-scoped identity (tenant, user id) that should follow the
-request across `await`s without being passed through every function. Values do
-not leak to other concurrent requests. Auto-instrumented HTTP does not send
-these keys until you call `injectTraceContext`.
+Runs a callback with a request-scoped string such as a tenant or user ID.
+The value follows work started by the callback across `await`s without leaking
+to later handlers. Call `injectTraceContext` to send it on custom transports.
 
 ```js
-setBaggage("tenant.id", "acme");
+await setBaggage("tenant.id", "acme", () => handleRequest());
 ```
 
 ### `getBaggage(key)`
 
 Returns a baggage value from the current request, or `undefined`.
 
-Use this later in the same request to read a value set with `setBaggage`, or a
-key that arrived on an inbound `baggage` header.
+Use this later in the same request to read a value set with `setBaggage`,
+or a key that arrived on an inbound `baggage` header.
 
 ```js
 const tenant = getBaggage("tenant.id"); // "acme"
@@ -295,9 +385,9 @@ const tenant = getBaggage("tenant.id"); // "acme"
 
 ### `incrementCounter(name, value?, attributes?, options?)`
 
-Adds to a counter that only increases.
+Creates the counter if it does not exist, then increments it.
 
-Use this for event counts: orders created, jobs finished, errors.
+This counter can only increases. Use this for event counts.
 
 ```js
 incrementCounter("orders.created", 1, { "cloud.region": "us-west-1" });
@@ -305,10 +395,9 @@ incrementCounter("orders.created", 1, { "cloud.region": "us-west-1" });
 
 ### `recordHistogram(name, value, attributes?, options?)`
 
-Records a measurement in a distribution.
+Creates the histogram if it does not exist, then records a measurement.
 
-Use this for values you want percentiles or averages of: latency, duration,
-payload size.
+Use this for values you want percentiles or averages of: latency, duration, payload size.
 
 ```js
 recordHistogram("checkout.duration", 0.142, undefined, { unit: "s" });
@@ -316,17 +405,20 @@ recordHistogram("checkout.duration", 0.142, undefined, { unit: "s" });
 
 ### `addUpDownCounter(name, value, attributes?, options?)`
 
-Adds a signed delta to a counter that can go up or down.
+Creates the up-down counter if it does not exist, then adds a signed
+delta. The value can go up or down.
 
 Use this for occupancy: active jobs, open connections, items in a pool.
 
+In other terms, pass +value when something starts occupying a slot, -value when it leaves. The metric is the current state of occupancy.
+
 ```js
 addUpDownCounter("jobs.active", -1);
 ```
 
 ### `setMetric(name, value, attributes?, options?)`
 
-Sets the current value of a gauge.
+Creates the gauge if it does not exist, then sets its current value.
 
 Use this for a point-in-time level: queue depth, heap used, cache size.
 
@@ -334,17 +426,51 @@ Use this for a point-in-time level: queue depth, heap used, cache size.
 setMetric("queue.depth", 27);
 ```
 
-Each metric helper caches instruments by kind and name. `unit` and
-`description` therefore apply on first use. Observable (pull) instruments are
-not part of this API; use `@opentelemetry/api` or automatic instrumentation
-when a value should be sampled on export rather than recorded on an event.
+TODO(pcga11): Investigate if it's worth support observable (pull) instruments API.
+
+### `log(body, severity?, attributes?)`
+
+Sends a log record to Foam on Foam's own export path. It does not write to the app's logger, and it does not emit on a LoggerProvider Foam does
+not own.
+
+Use this to send logs directly. Typically used for Pino 5–6, Winston 1–2 as they do not support sending logs.
+
+```js
+import { log, SeverityNumber } from "@foam-ai/node";
+
+log("checkout failed");
+log("checkout failed", SeverityNumber.ERROR);
+```
+
+### `recordException(error)`
+
+Records an exception on the current active span and sets the span status
+to `ERROR`. Accepts an `Error` or any value (stringified). Never throws;
+does nothing when no span is active or the span is not recording.
+
+Use this in `catch` blocks inside auto-instrumented handlers (HTTP
+routes, message consumers) where you did not create the span yourself.
+The exception lands on whichever SDK owns the active span, so it works
+even when another SDK owns tracing.
+
+```js
+import { recordException } from "@foam-ai/node";
+
+try {
+  await chargeCard(order);
+} catch (err) {
+  recordException(err);
+  throw err;
+}
+```
 
 ### `getState()`
 
-Returns whether Foam initialized, which instrumentations registered, and which
-signals have an export path.
+Returns whether Foam initialized, which instrumentations registered, and
+which signals have an export path. 
 
-Use this in health checks, tests, or diagnostics to confirm Foam is running.
+Use this in health checks, tests, or diagnostics to confirm Foam is
+running.
 
 ```js
 import { getState } from "@foam-ai/node";
@@ -354,117 +480,170 @@ getState();
 //   initialized: true,
 //   instrumentations: ["http", "express", "pg", ...],
 //   signals: {
-//     traces: true,
-//     metrics: true,
-//     logs: true,
-//     baggage: true,
-//     profile: false,
+//     traces: "global",
+//     metrics: "global",
+//     logs: "global",
+//     baggage: "global",
+//     profile: "none",
 //   },
 // }
 ```
 
-`instrumentations` contains only the instrumentations registered with a
+`instrumentations` lists only the instrumentations registered with a
 successfully started Foam SDK, after upstream defaults and
 `OTEL_NODE_ENABLED_INSTRUMENTATIONS` /
-`OTEL_NODE_DISABLED_INSTRUMENTATIONS` filtering. Registration means an
-instrumentation is ready to patch a supported module when that module loads; it
-does not prove that the module has loaded or emitted spans.
+`OTEL_NODE_DISABLED_INSTRUMENTATIONS` filtering. Registered means the
+instrumentation is ready to patch a supported module when that module
+loads.
+
+Each `signals` value names the source of the Foam export path for that
+signal:
+
+- `"global"` — `init()` registered Foam's provider in the global
+  OpenTelemetry slot.
+- `"ingest"` — a `createFoamIngest*` processor/reader was constructed for
+  another SDK's pipeline. Foam cannot tell whether you actually registered
+  the returned object.
+- `"local"` — logs only: another SDK owns the global LoggerProvider, but
+  Foam keeps its own local provider so `log()` still delivers to Foam.
+- `"none"` — no Foam export path.
+
+A value other than `"none"` means telemetry is expected, not that the app
+has already produced or exported it.
+
+## Custom spans and other OpenTelemetry APIs
+
+Foam does not wrap span creation. To start your own spans, read the
+current span, or work with context, import `@opentelemetry/api` directly.
+`init()` registers Foam's providers in the global OpenTelemetry slots, so
+the official API routes to Foam automatically.
 
-Each `signals` boolean means Foam successfully constructed an export path for
-that signal. This can be a Foam-owned provider from `init()` or a
-processor/reader returned by an ingest factory. For ingest factories, Foam
-cannot prove that the caller subsequently registered the returned object. The
-boolean therefore means telemetry is expected, not that the application has
-already produced or successfully exported it.
+Install the API in your app so it resolves one compatible `1.x` copy:
+
+```sh
+npm install @opentelemetry/api
+```
+
+```js
+import { trace, SpanStatusCode } from "@opentelemetry/api";
+
+const tracer = trace.getTracer("checkout");
+
+await tracer.startActiveSpan("charge-card", async (span) => {
+  try {
+    await chargeCard(order);
+  } catch (err) {
+    span.recordException(err);
+    span.setStatus({ code: SpanStatusCode.ERROR });
+    throw err;
+  } finally {
+    span.end();
+  }
+});
+```
+
+Prefer `startActiveSpan` over `startSpan`: it makes the span current, so
+auto-instrumented HTTP/database spans and nested custom spans parent under
+it. Always call `span.end()` (the `finally` above), or the span never
+exports. When you did not create the span yourself, Foam's
+`recordException(err)` does the exception-plus-ERROR-status pair on the
+current active span for you.
+
+The same applies to the rest of the API: `trace.getActiveSpan()` to tag
+the current request (`span.setAttribute(...)`), and `context.with(...)`
+to run code under a specific context.
+
+This is safe in every state: if another SDK owns the global tracer slot,
+these spans go to that SDK; before `init()` (or when Foam is disabled)
+the API returns a no-op tracer and nothing is recorded. Custom spans
+export wherever `getState().signals.traces` points.
 
 ## Network capture
 
-`networkCapture` defaults to `"basic"` and controls HTTP enrichment: `"off"`
-keeps standard OpenTelemetry HTTP/Undici telemetry with no extra capture,
-`"basic"` adds allowlisted `content-type`, `content-length`, and
-`content-encoding` headers, and `"advanced"` adds those headers plus complete
-Node `http`/`https` (and Fetch/Undici, when diagnostics exist) request and
-response bodies as raw wire bytes up to 1 MiB. Bodies are emitted as
-correlated `foam.http.body.chunk` log events; the HTTP span records semantic
-`http.*.body.size` and, for textual bodies, `http.*.body.content`, while
-`authorization`, `cookie`, HTTP/2, and gRPC are never captured. Advanced
-capture requires Foam to own the logger provider, closes incomplete bodies
-after 60 seconds of inactivity, and is replaced if you override the bundled
-HTTP instrumentation through `additionalInstrumentations`. Foam partitions
-serialized trace and log export batches below 19 MiB to stay under the
-ClickStack collector's 20 MiB OTLP/HTTP limit.
-
-## Logger support and ownership
-
-Foam follows the compatibility ranges of its OpenTelemetry logger
-instrumentations:
-
-- Bunyan `>=1 <2`
-- Pino `>=5.14 <11`
-- Winston `>=1 <4`
-
-The init log line that lists registered instrumentations also names each
-detected logger with its installed version. Initialize Foam before importing or
-constructing the logger; registration alone does not prove that a logger was
-loaded, patched, or produced records.
-
-Logger trace correlation remains enabled by default. With
-`disableLogSending: false` (the default), OpenTelemetry automatically sends:
-
-- Bunyan records through its added OTel stream
-- Pino 7 and newer records through an added main-thread multistream
-- Winston 3 records through the bundled `OpenTelemetryTransportV3`
-
-Pino 5 and 6 and Winston 1 and 2 support correlation only. Set
-`disableLogSending: true` when the application manually installs a Bunyan OTel
-stream, configures `pino-opentelemetry-transport`, installs a Winston OTel
-transport, or otherwise gives another pipeline ownership of logger records.
-This disables automatic sending for Bunyan, Pino, and Winston while preserving
-trace correlation.
-
-OpenTelemetry cannot reliably deduplicate manually configured streams and
-transports; explicit `disableLogSending` ownership is the correctness
-mechanism.
-
-`ConsoleInstrumentation` separately turns calls to `console.*` into OTel log
-records. It does not make arbitrary stdout/stderr writes observable.
+`networkCapture` defaults to `"basic"` and controls extra HTTP detail.
 
-## OpenTelemetry configuration and compliance
+- `"off"` keeps standard OpenTelemetry HTTP/Undici telemetry, with no extra
+  capture.
+- `"basic"` adds allowlisted `content-type`, `content-length`, and
+  `content-encoding` headers.
+- `"advanced"` adds those headers plus full Node `http`/`https` and
+  Fetch/Undici request and response bodies as raw wire bytes, up to 1 MiB. Always set to `"advanced"` when security and compliance allows.
 
-Foam composes the official OpenTelemetry JavaScript API, SDK, resource,
-propagation, instrumentation, and OTLP exporter packages. It does not fork
-their data model or redefine spans, metrics, logs, resources, or context.
+## Redaction
 
-Foam does not use any of environment configuration. So they remain available, including:
+Foam always masks common credentials in captured request and response data,
+URLs, and exported span and log fields. Add application-specific keys with the
+`redact` option shown under `init(options)`.
 
-- `OTEL_RESOURCE_ATTRIBUTES` (the Basic API's required service name and
-  environment take precedence for those resource attributes)
-- `OTEL_NODE_ENABLED_INSTRUMENTATIONS` and
-  `OTEL_NODE_DISABLED_INSTRUMENTATIONS`
-- `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`
-- `OTEL_TRACES_SAMPLER`
+Redaction applies to Foam's exports, including ingest helpers. It does not
+modify telemetry sent through other exporters.
 
-The [OpenTelemetry JavaScript compliance matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix/js.yaml)
-describes `opentelemetry-js`, not this distro. It uses `+` (implemented),
-`-` (not implemented), `?` (unknown), and `N/A`. Foam does not reimplement
-those SDK features and does not inherit every `+` row: `init()` only
-constructs the packages and options this distro actually wires (W3C
-propagation, OTLP/HTTP to Foam, a parent-based ratio sampler). Rows the
-matrix marks `+` for JavaScript but Foam never installs stay unavailable
-here, including OTLP/gRPC, Zipkin, Prometheus, Jaeger remote sampling,
-B3/Jaeger propagators, metric views, and `OTEL_TRACES_SAMPLER`. Foam also
-does not implement rows marked `-` or `?`.
+## Loggers
 
-## TODO(pcga11): OpenTelemetry profiling
+Initialize Foam before you import or construct the logger.
+
+What Foam does depends on the logger version:
+
+- Bunyan 1, Pino 7–10, and Winston 3: Foam adds trace IDs to every
+  record and automatically sends a copy to Foam.
+- Pino 5.14–6 and Winston 1–2: Foam adds trace IDs, but these versions
+  have no way to attach a sender, so no copy reaches Foam. Upgrade the
+  logger, or call `log()` yourself.
+- Everything else: Foam does nothing. Use `console.*` (captured
+  below), call `log()`, or upgrade the logger.
+
+### If the app already ships logs somewhere
+
+- To a non-OTel destination (files, another vendor's transport): no
+  conflict. Keep the defaults; Foam sends its own copy alongside.
+- Through its own OTel stream/transport (a Bunyan OTel stream,
+  Winston `OpenTelemetryTransportV3`): those already deliver to Foam
+  via the global LoggerProvider. Set `disableLogSending: true` so
+  records don't arrive twice.
+- Through another OTel SDK's LoggerProvider: set
+  `disableLogSending: true` and attach
+  `createFoamIngestLogRecordProcessor` to that provider (see Public
+  API) so Foam gets a copy.
+- Through `pino-opentelemetry-transport`: it runs in a worker
+  thread and never touches the in-process LoggerProvider, so nothing
+  conflicts. Keep `disableLogSending: false`, or Foam gets no Pino
+  records at all.
+- Through a collector or agent reading stdout/files: no app changes;
+  add a Foam OTLP exporter to the collector config.
+
+`log()` sends a single record straight to Foam in any setup. It is a
+manual per-record call, not a mirror of the logger. Use it for
+targeted, high-value records.
 
-Profiling is not supported: the official OpenTelemetry JavaScript SDK has no
-in-process Profiles provider, processor, or exporter yet.
+`ConsoleInstrumentation` turns calls to `console.*` into OTel log records.
+It does not capture arbitrary stdout/stderr writes.
 
-Add profiling and report `getState().signals.profile: true` after that ships.
+```js
+console.log("hi");              // captured
+process.stdout.write("hi\n");   // not captured
+```
+
+## OpenTelemetry configuration and compliance
+
+Foam uses the official OpenTelemetry JavaScript API, SDK, resource,
+propagation, instrumentation, and OTLP exporter packages.
+
+The [OpenTelemetry JavaScript compliance matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix/js.yaml)
+
+## TODO(pcga11): OpenTelemetry profiling
 
-Track upstream progress:
+The official OpenTelemetry JavaScript SDK has no in-process Profiles provider, processor, or exporter yet. Track upstream progress:
 
 - [OpenTelemetry JS profiling implementation issue](https://github.com/open-telemetry/opentelemetry-js/issues/6500)
 - [Profiling SIG language SDK support tracker](https://github.com/open-telemetry/sig-profiling/issues/106)
 - [OpenTelemetry Profiles public alpha announcement](https://opentelemetry.io/blog/2026/profiles-alpha/)
 - [OpenTelemetry eBPF profiler](https://github.com/open-telemetry/opentelemetry-ebpf-profiler)
+
+## TODO(pcga11): Anthropic instrumentation
+
+There is no released official OpenTelemetry JavaScript instrumentation for the Anthropic SDK yet, but one is actively in progress in js-contrib, based on the OpenInference donation from Arize. Once `@opentelemetry/instrumentation-anthropic` is released (and picked up by `auto-instrumentations-node`), bundle it here like the OpenAI and aws-sdk ones. Until then, Anthropic coverage is handled case by case with the FDE (see FDE.md). Track upstream progress:
+
+- [feat(instrumentation-anthropic): add basic messages instrumentation](https://github.com/open-telemetry/opentelemetry-js-contrib/pull/3664)
+- [refactor(instrumentation-anthropic): use genai-util library](https://github.com/open-telemetry/opentelemetry-js-contrib/pull/3698)
+- [Tracking: Migrate OpenInference JS instrumentations into opentelemetry-js-contrib](https://github.com/open-telemetry/opentelemetry-js-contrib/issues/3668)
+- [feat: Add @opentelemetry/genai-util package for GenAI instrumentations](https://github.com/open-telemetry/opentelemetry-js-contrib/issues/3681)