Skip to content

Commit 20eea0a

Browse files
committed
docs(genkit): Node claims, Firebase plugin, signals, masking, shutdown
Installed-review README findings. N4: the Node row claimed the contract suite and import check on 20.20.2, 22.23.3 and 26.8.1, but NODE_BINARY is one Node per run and TRACEAI_NODE_MATRIX parametrizes only the entry-point import check. The full contract suite was rerun once per Node (NODE_BINARY=20.20.2, 22.23.3, 26.8.1; TRACEAI_NODE_MATRIX = all three each time): 22 passed on each at 4973cae. jest also ran once per Node (that Node first on PATH): 68 passed each. The Node row and Tests section now say exactly that, name what TRACEAI_NODE_MATRIX parametrizes, and note the import check uses a symlink, not a clean npm install. N2: new subsection: using the Firebase / Google Cloud telemetry plugin (enableFirebaseTelemetry, enableGoogleCloudTelemetry, ENABLE_FIREBASE_MONITORING) with this package is not supported in this release. Reason: each enableTelemetry() starts another NodeSDK; only the first gets Genkit's spans and flushTracing() flushes only the last. Checked with a local probe (genkit 1.42.0, no plugin, two enableTelemetry calls with recording processors): first processor got the flow span and no flush, second got no span and the flush. Includes the PRD cost note (Future AGI export adds no GCP cost; the GCP copy may be billed by Google). N5: call flushOnSignals after every other SIGTERM/SIGINT listener; later listeners run in parallel with the flush; a second signal is ignored until the flush ends or times out. N6: fi-core TraceConfig / FI_HIDE_* masking is not applied; captureContent is the only content switch. N7: shutdown() also shuts down the register() provider passed in (Genkit's NodeSDK calls it on SIGTERM); use a dedicated provider for Genkit. Docs only; no code or test change. approved: Nikhil 2026-10-03 blanket Refs: TH-8240
1 parent 4973cae commit 20eea0a

1 file changed

Lines changed: 18 additions & 4 deletions

File tree

‎typescript/packages/traceai_genkit/README.md‎

Lines changed: 18 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,15 @@ Send [Firebase Genkit](https://genkit.dev) (JavaScript) spans to Future AGI. Gen
44

55
Alpha. Validated with real `genkit` 1.42.0 flows on Genkit's own test model (`mockModel` from `genkit/testing`), exported to a loopback OTLP receiver. No model vendor and no GCP were called.
66

7-
JavaScript only. Genkit Python and Genkit Go are not covered. This package does not use the Firebase / Google Cloud plugin and does not wrap `ai.generate()`.
7+
JavaScript only. Genkit Python and Genkit Go are not covered. This package does not use the Firebase / Google Cloud plugin, cannot run next to it in one process in this release (see [Firebase / Google Cloud telemetry plugin](#firebase--google-cloud-telemetry-plugin)), and does not wrap `ai.generate()`.
88

99
## Versions and licence
1010

1111
| Item | Value |
1212
|---|---|
1313
| Tested pin | `genkit` 1.42.0 (`@genkit-ai/core` 1.42.0, `@genkit-ai/ai` 1.42.0) |
1414
| Peer range | `genkit` `^1.42.0` |
15-
| Node | 20.20.2, 22.23.3 and 26.8.1 (contract suite and CJS/ESM import check) |
15+
| Node | 20.20.2, 22.23.3 and 26.8.1: the full contract suite (every journey) ran once per version with `NODE_BINARY` set to it, and jest ran once per version with that Node first on `PATH`. `TRACEAI_NODE_MATRIX` parametrizes only the CJS/ESM entry-point import check; each of the three runs set it to all three Nodes. See [Tests](#tests). |
1616
| Genkit licence | Apache-2.0 (`node_modules/genkit/LICENSE`, `package.json` `license`) |
1717

1818
`genkit` is a **peer dependency**. Install it yourself. This package never bundles or re-exports Genkit; the pack test hashes every file of the installed `genkit`, `@genkit-ai/core` and `@genkit-ai/ai` and checks that none ships in the tarball.
@@ -63,6 +63,14 @@ Three things the setup depends on, each checked in the installed 1.42.0 source:
6363

6464
Metrics: `enableTelemetry({ spanProcessors })` passes no metric reader, and the NodeSDK Genkit uses (`@opentelemetry/sdk-node` 0.52.1) builds a meter provider only when one is configured, so no Genkit metrics go anywhere. `disableMetrics` and `forceDevExport` are options of the `@genkit-ai/google-cloud` plugin (`src/types.ts:92,110`), not of `enableTelemetry`'s `TelemetryConfig`; TypeScript rejects them there.
6565

66+
### Firebase / Google Cloud telemetry plugin
67+
68+
Using this package together with the Firebase / Google Cloud telemetry plugin (`enableFirebaseTelemetry()` from `@genkit-ai/firebase`, `enableGoogleCloudTelemetry()` from `@genkit-ai/google-cloud`, or `ENABLE_FIREBASE_MONITORING=true`) is **not supported in this release**. Use one or the other per process.
69+
70+
Why: both plugins call the same `enableTelemetry()` (`@genkit-ai/firebase` `src/index.ts:40-44` -> `@genkit-ai/google-cloud` `src/index.ts:38-41`), and every `enableTelemetry()` call replaces Genkit's stored config and starts a second NodeSDK (`@genkit-ai/core` `src/tracing/node-telemetry-provider.ts:64,97-98`). Only the first NodeSDK becomes the global tracer provider, so only the first call's processors get Genkit's spans, while `flushTracing()` flushes only the last call's processors (`node-telemetry-provider.ts:143-151`). Whichever runs second gets no spans, and the first is no longer flushed by `flushTracing()`. Checked locally with genkit 1.42.0 and no plugin: two `enableTelemetry()` calls with recording processors, one flow; the first processor received the flow span and no flush, the second received no span and the flush. `ENABLE_FIREBASE_MONITORING=true` makes Genkit call `enableFirebaseTelemetry()` itself when a span starts before any `enableTelemetry()` call (`@genkit-ai/core` `src/tracing.ts:33,50-62`); the Firebase plugin itself was not run (it needs GCP).
71+
72+
Cost: the Future AGI export adds no Google Cloud cost. The Firebase / Google Cloud plugin exports to Cloud Trace, Logging and Monitoring, which Google bills (Blaze plan), so exporting to both, for example from separate deployments, may cost on GCP for that copy only.
73+
6674
## What you get
6775

6876
### Span kinds
@@ -130,11 +138,15 @@ Genkit's schema-validation error embeds the rejected data in its message: `Schem
130138

131139
The processor never changes Genkit's span. Genkit's Dev UI and any other exporter see the original attributes; Future AGI gets a mapped copy.
132140

141+
fi-core's `TraceConfig` masking (`FI_HIDE_INPUTS`, `FI_HIDE_OUTPUTS` and the other `FI_HIDE_*` settings) is not applied to Genkit spans: `captureContent` is the only content switch in this package.
142+
133143
## Flush and shutdown
134144

135145
- `flushTracing()` from `genkit/tracing` (`core/src/tracing.ts:113`) flushes every processor, this one included. Call it before a short script exits.
136146
- `FIGenkitSpanProcessor.forceFlush()` and `shutdown()` never reject. Each is bounded by `flushTimeoutMillis` (default 30000 ms). A collector that is down is logged through the OTel diag logger; the flow still returns.
147+
- `shutdown()` also shuts down the `register()` provider you passed, and Genkit's NodeSDK calls it on SIGTERM (`@genkit-ai/core` `src/tracing/node-telemetry-provider.ts:99,111`), so give Genkit its own `register()` provider instead of sharing one with other traceAI instrumentations.
137148
- SIGTERM: `genkit` installs a SIGTERM / SIGINT listener at import that stops its reflection servers and calls `process.exit(0)` without flushing (`genkit/src/genkit.ts:786-793`). An app listener that awaits `flushTracing()` loses that race. `flushOnSignals(flush)` moves the listeners registered so far behind a bounded `flush` (default 10000 ms) and then runs them in order. Call it after `import "genkit"` and after `await enableTelemetry(...)`. It returns a function that restores the original listeners.
149+
- Call `flushOnSignals` after every other SIGTERM / SIGINT listener is installed: a listener added later is not moved behind the flush and runs at once, in parallel with it, and a second signal (a second Ctrl-C) during the flush is ignored until the flush finishes or its timeout ends.
138150
- Export goes through the fi-core provider's own span processor and exporter. This package adds no queue of its own.
139151

140152
## Span inventory at 1.42.0
@@ -159,11 +171,13 @@ From `typescript/packages/traceai_genkit`:
159171
pnpm exec jest
160172
```
161173

162-
From the repository root (shared harness in `python/tests/harness`):
174+
From the repository root (shared harness in `python/tests/harness`), once per Node version:
163175

164176
```bash
177+
NODE_BINARY=/path/to/node-v20.20.2/bin/node \
178+
TRACEAI_NODE_MATRIX=/path/to/node-v20.20.2/bin/node:/path/to/node-v22.23.3/bin/node:/path/to/node-v26.8.1/bin/node \
165179
PYTHONPATH=python/tests uv run --no-project --python 3.11 --with pytest --with protobuf --with opentelemetry-proto \
166180
pytest typescript/packages/traceai_genkit/contract -q -p no:cacheprovider --noconftest -o addopts=''
167181
```
168182

169-
The contract suite builds the package, runs `contract/run_fixture.mjs` against the real fi-core exporter and the shared receiver, and checks the collector path and headers, the resource, span names, kinds and parenting, model and tokens, the trace token sum, content off by default with an opt-in control run, one closed model span for a streamed flow, error status and exception events, schema-validation data cut from status and exception events with content off (and kept after opt-in), SIGTERM flushing (with a control that shows a plain listener loses the race), a collector that is down, Genkit's Dev UI reflection server and telemetry export in `GENKIT_ENV=dev`, the inventory drift check, the packed tarball, and the CJS / ESM entry points. `NODE_BINARY` selects the node binary; `TRACEAI_NODE_MATRIX` (path-separated) widens the entry-point check.
183+
The contract suite builds the package, runs `contract/run_fixture.mjs` against the real fi-core exporter and the shared receiver, and checks the collector path and headers, the resource, span names, kinds and parenting, model and tokens, the trace token sum, content off by default with an opt-in control run, one closed model span for a streamed flow, error status and exception events, schema-validation data cut from status and exception events with content off (and kept after opt-in), SIGTERM flushing (with a control that shows a plain listener loses the race), a collector that is down, Genkit's Dev UI reflection server and telemetry export in `GENKIT_ENV=dev`, the inventory drift check, the packed tarball, and the CJS / ESM entry points. `NODE_BINARY` is the node every fixture journey and the inventory check run on (the build and `pnpm pack` steps use the `node` on `PATH`). `TRACEAI_NODE_MATRIX` (path-separated) parametrizes only the CJS / ESM entry-point import check, which loads the built package through a symlink in a temporary `node_modules` (not a clean `npm install`); unset, it is `NODE_BINARY` alone. The suite ran on 20.20.2, 22.23.3 and 26.8.1, one run each with the matrix above: 22 passed per run (19 tests plus the import check on three Nodes). jest ran on the same three Nodes (that Node first on `PATH`): 68 passed each.

0 commit comments

Comments
 (0)