@foam-ai/node 0.1.0-alpha.11 → 0.1.0-alpha.12

package/README.md

@@ -646,6 +646,85 @@ The official OpenTelemetry JavaScript SDK has no in-process Profiles provider, p
 - [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): Expanded data capture (http2, gRPC, DB results, messaging)
+
+Extension points Foam is not using yet, ordered by how much new data they
+unlock. All payload extraction flows through the same redaction and size
+caps as HTTP network capture.
+
+### Database results — biggest win, zero patching
+
+`responseHook` hands Foam the raw driver result (in memory, no extra query)
+before the span ends. Each package has its own payload shape — do not
+assume a shared contract: `pg` passes `{ data }`, `mysql2`
+`{ queryResults }`, `mongoose` `{ response }`, `mongodb` the command
+response, `cassandra-driver` only the first result page, and
+`ioredis`/`redis` (v4+) use positional `(cmdName, cmdArgs, response)`
+args. Also `requestHook` (pg, ioredis, oracledb) for full query/args, and
+`maskStatementHook` (mysql2) to wire SQL text into Foam redaction. No
+hooks: `mysql` v1, `tedious`, `memcached` — spans only. Ship as opt-in:
+results are the most PII-dense payload in the system.
+`enhancedDatabaseReporting` (adds bound parameter values) must likewise
+stay opt-in — redaction cannot key-match values inside SQL text.
+
+### http2 + gRPC — currently fully dark
+
+Node ships `http2.client.stream.*` / `http2.server.stream.*` lifecycle
+channels since 24.1 (backported to 22.x), and the request-body channels
+`bodyChunkSent` / `bodySent` since 24.12.0 / 22.22.1 — pin those floors in
+`support.ts`, gated on the Node version (core emits these, unlike undici's
+own channels). The adapter mirrors `src/network-capture/undici.ts` but the
+payloads differ: Node publishes `{ stream, writev, data, encoding }` for
+`bodyChunkSent` and `{ stream }` for `bodySent`, vs undici's
+`{ request, chunk }` — map fields explicitly. No OTel instrumentation
+exists for http2, so Foam creates the spans too. Response bodies have no
+channel and the exposed `ClientHttp2Stream` is live, not replayable:
+collect passively (wrap `push()` as `http.ts` does) without reading the
+stream or switching it into flowing mode, or leave response capture out.
+For gRPC, `instrumentation-grpc` gives spans but zero payload hooks
+(only `metadataToSpanAttributes` — enable it). The http2 body chunks carry
+gRPC framing, not bare protobuf: reassemble the 1-byte compression flag +
+4-byte big-endian length prefix per message, decompressing flagged
+messages, before any protobuf decode — or skip framing entirely with a
+custom patch of `@grpc/grpc-js` serialization.
+
+### Messaging and cloud payloads — hooks receive the actual message
+
+- `kafkajs` `producerHook`/`consumerHook` receive `{ topic, message }`
+  (value, key, headers); `amqplib` `publishHook`/`consumeHook`
+  (+confirm/end variants) receive the message `content` plus
+  routing/options metadata — shapes differ per hook.
+- `socket.io` `emitHook`/`onHook`: event payloads (covers the socket.io
+  slice of WebSocket traffic).
+- `aws-sdk` `preRequestHook`/`responseHook`/`exceptionHook` (the latter
+  gets `(span, requestInfo, err)`): normalized request/response for every
+  AWS call. SDK v3 only.
+
+### Crash and shutdown capture — data we currently lose
+
+Errors outside any span (timer callbacks, unhandled rejections, startup)
+are invisible, and `beforeExit` — Foam's only lifecycle hook — does not
+fire on crashes or signals, so the batch holding the spans that explain a
+crash dies with the process, and every SIGTERM (each deploy) drops the
+final batch window. Use `uncaughtExceptionMonitor` (never plain
+`uncaughtException`, which suppresses the default crash) — but note an
+async flush started there is abandoned when the process terminates, so
+crash delivery needs a synchronous durable handoff (sync write to disk, or
+a helper process that ships it) rather than relying on the async exporter.
+SIGTERM/SIGINT get flush-then-resignal handlers with a bounded flush
+timeout that never swallows the signal or changes the exit code. `warning`
+events ship as logs.
+
+### Smaller / later
+
+- `logHook` (bunyan/pino/winston), `graphql` `responseHook`,
+  `express`/`koa`/`restify` `requestHook`: enrichment, little new data.
+- Channels: `worker_threads` (detect uninstrumented workers), 24+ native
+  `console.*` (could replace patch-based console capture),
+  `tracing:module.*` (library-version detection), `child_process`.
+- No hook surface at all: raw `ws` frames (custom patch, frame data model)
+  and Prisma (Rust engine; needs app-enabled Prisma OTel tracing).
+
 ## 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:

package/dist/constants.d.ts

@@ -4,7 +4,7 @@ export declare const FOAM_INGEST_HOST: string;
 export declare const ATTR_FOAM_INGEST_HOST = "foam.ingest.host";
 export declare const FOAM_IDENTIFIER_NAME = "[foam-otel]";
 export declare const FOAM_DISTRO_NAME = "@foam-ai/node";
-export declare const FOAM_DISTRO_VERSION = "0.1.0-alpha.11";
+export declare const FOAM_DISTRO_VERSION = "0.1.0-alpha.12";
 export declare const FOAM_OTLP_TRACES_PATH = "/v1/traces";
 export declare const FOAM_OTLP_LOGS_PATH = "/v1/logs";
 export declare const FOAM_OTLP_METRICS_PATH = "/v1/metrics";

package/dist/constants.js

@@ -7,7 +7,7 @@ exports.FOAM_INGEST_HOST = new URL(exports.FOAM_ENDPOINT).hostname;
 exports.ATTR_FOAM_INGEST_HOST = "foam.ingest.host";
 exports.FOAM_IDENTIFIER_NAME = "[foam-otel]";
 exports.FOAM_DISTRO_NAME = "@foam-ai/node";
-exports.FOAM_DISTRO_VERSION = "0.1.0-alpha.11";
+exports.FOAM_DISTRO_VERSION = "0.1.0-alpha.12";
 exports.FOAM_OTLP_TRACES_PATH = "/v1/traces";
 exports.FOAM_OTLP_LOGS_PATH = "/v1/logs";
 exports.FOAM_OTLP_METRICS_PATH = "/v1/metrics";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foam-ai/node",
-  "version": "0.1.0-alpha.11",
+  "version": "0.1.0-alpha.12",
   "description": "Foam JavaScript Node.js SDK",
   "license": "Apache-2.0",
   "repository": {