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

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,49 +132,66 @@ 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.
+`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 copying logger
+records into Foam (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` and `beforeSend` are accepted but **not implemented yet**; passing
+them logs a warning and they are ignored. `redact` will add extra
+sensitive keys (strings or RegExps) to the built-in body redaction list.
+`beforeSend` will run on every captured body before it leaves the
+process, returning the (possibly edited) text or `null` to drop the
+capture. Until they ship, rely on the built-in redaction (see Network
+capture).
+
+`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)`
 
-Returns a span processor that exports traces to Foam without taking over the
-global TracerProvider.
+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.
+Use this when another OpenTelemetry SDK already owns traces and you only
+need Foam as an extra export destination.
 
 ```js
 import { createFoamIngestSpanProcessor } from "@foam-ai/node";
@@ -183,7 +209,8 @@ tracerProvider.addSpanProcessor(spanProcessor);
 Returns a log-record processor that exports logs to Foam without taking over
 the global LoggerProvider.
 
-Use this when another SDK already owns logs and you want those records in Foam.
+Use this when another SDK already owns logs and you want those records in
+Foam.
 
 ```js
 import { createFoamIngestLogRecordProcessor } from "@foam-ai/node";
@@ -198,8 +225,8 @@ loggerProvider.addLogRecordProcessor(logRecordProcessor);
 
 ### `createFoamIngestMetricReader(name, environment, token)`
 
-Returns a metric reader that exports metrics to Foam without taking over the
-global MeterProvider.
+Returns a metric reader that exports metrics to Foam without taking over
+the global MeterProvider.
 
 Use this when another SDK already owns metrics and you want those meters in
 Foam.
@@ -215,39 +242,56 @@ const metricReader = createFoamIngestMetricReader(
 meterProvider.addMetricReader(metricReader);
 ```
 
-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.
+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()],
+});
+```
+
+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 `false`. 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 +301,10 @@ 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 you receive a message on a custom transport so the tracing carries over. Missing to extact resets the context on these headers effectively losing the context previously injected.
 
 ```js
 import { context } from "@opentelemetry/api";
@@ -273,10 +317,11 @@ await context.with(parent, () => handle(message));
 
 Stores a small string on the current request context.
 
-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`.
+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. Caveat: auto-instrumented HTTP
+does not send these keys until you call `injectTraceContext`.
 
 ```js
 setBaggage("tenant.id", "acme");
@@ -286,8 +331,8 @@ setBaggage("tenant.id", "acme");
 
 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 +340,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 +350,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 +360,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 +381,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,47 +435,107 @@ 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.
+
+Install the API in your app so it resolves one compatible `1.x` copy:
+
+```sh
+npm install @opentelemetry/api
+```
 
-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.
+```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
+`networkCapture` defaults to `"basic"` and controls extra HTTP detail.
+
+- `"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.
+
+
+Headers are captured from an allowlist only, so sensitive headers such as
+`authorization` and `cookie` never leave the process. Captured JSON and
+form-urlencoded bodies are redacted before emission: values of sensitive
+keys (`password`, `token`, `api_key`, `client_secret`, `ssn`, and similar,
+matched case-insensitively across `-`, `_`, and `.` separators) are
+replaced with `[REDACTED]` on both the span body content and the emitted
+body chunks. When redaction changes a compressed body, the chunks carry
+the redacted text instead of the raw wire bytes. Other text and binary
+media types are captured unmodified.
+
+## Loggers
 
 Foam follows the compatibility ranges of its OpenTelemetry logger
 instrumentations:
@@ -403,66 +544,41 @@ instrumentations:
 - 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.
+Initialize Foam before you import or construct the logger. Registration alone does not mean a logger
+was loaded, patched, or produced records.
 
-Logger trace correlation remains enabled by default. With
-`disableLogSending: false` (the default), OpenTelemetry automatically sends:
+With `disableLogSending: false` (the default), Foam SDK sends:
 
-- Bunyan records through its added OTel stream
-- Pino 7 and newer records through an added main-thread multistream
+- Bunyan 1 records through an added OTel stream
+- Pino 7–10 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.
+Pino 5–6 and Winston 1–2 still get correlation. But they have no sending
+path (`pino.multistream` starts at 7; Winston transports start at 3), so Foam never receives a copy. Call `log()` to send a record yourself.
 
-`ConsoleInstrumentation` separately turns calls to `console.*` into OTel log
-records. It does not make arbitrary stdout/stderr writes observable.
+Set `disableLogSending: true` when the app already exports logger records
+itself (a Bunyan OTel stream, `pino-opentelemetry-transport`, a Winston
+OTel transport, or another pipeline). That turns off sending for Bunyan
+1, Pino 7–10, and Winston 3.
 
-## OpenTelemetry configuration and compliance
+`ConsoleInstrumentation` turns calls to `console.*` into OTel log records.
+It does not capture arbitrary stdout/stderr writes.
 
-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.
+```js
+console.log("hi");              // captured
+process.stdout.write("hi\n");   // not captured
+```
 
-Foam does not use any of environment configuration. So they remain available, including:
+## OpenTelemetry configuration and compliance
 
-- `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`
+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)
-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 `?`.
 
 ## TODO(pcga11): OpenTelemetry profiling
 
-Profiling is not supported: the official OpenTelemetry JavaScript SDK has no
-in-process Profiles provider, processor, or exporter yet.
-
-Add profiling and report `getState().signals.profile: true` after that ships.
-
-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)