Skip to content

Commit f7c6193

Browse files
committed
docs(genkit): name unmarked Genkit error paths and the enableTelemetry ordering
verify-r2 (t_f01a72b2) follow-ups: - validateSupport middleware (Request: <JSON>) and defineSimpleRetriever (Item: <JSON>) errors carry data without the Provided data: marker and are exported as thrown; parse-error key paths before the marker stay. - enableTelemetry({ spanProcessors }) must run before the first Genkit span, otherwise Genkit's own enableTelemetry({}) wins (@genkit-ai/core src/tracing.ts:32-40). N4-r2 is evidence only: coordinator reran jest on Node 20.20.2/22.23.3 (68 passed each) and the full contract with NODE_BINARY 22.23.3 (22 passed), backing the README Node row as written. approved: Nikhil 2026-10-03 blanket Refs: TH-8240
1 parent 20eea0a commit f7c6193

1 file changed

Lines changed: 2 additions & 1 deletion

File tree

‎typescript/packages/traceai_genkit/README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@ Three things the setup depends on, each checked in the installed 1.42.0 source:
6060
- `enableTelemetry` and `flushTracing` are exported from `genkit/tracing` (`genkit/src/tracing.ts:43-44`), not from `genkit`. They need Genkit's telemetry provider, which `genkit` / `genkit/beta` initialise at import (`genkit/src/common.ts:173-175`). Calling `enableTelemetry` before anything imported `genkit` throws `FAILED_PRECONDITION: TelemetryProvider is not initialized`.
6161
- `register()` must get `setGlobalTracerProvider: false`. Genkit takes its tracer from the global OpenTelemetry API (`@genkit-ai/core` `src/tracing/instrumentation.ts:96,197`) and its NodeSDK cannot register a global provider once fi-core has. Genkit spans would then skip both this processor and the Dev UI exporter, and reach Future AGI raw (content included, no kind). The processor warns (`TRACEAI_GENKIT_GLOBAL_PROVIDER`) when it detects this.
6262
- `enableTelemetry` keeps Genkit's own telemetry-server processor first and appends yours (`@genkit-ai/core` `src/tracing/node-telemetry-provider.ts:66-77`). The Genkit Dev UI keeps working. Passing `traceExporter` instead of `spanProcessors` throws in Genkit.
63+
- Call `enableTelemetry({ spanProcessors })` before the first flow, model or tool runs. When a Genkit span starts and no `enableTelemetry` call has happened yet, Genkit calls `enableTelemetry({})` itself (`@genkit-ai/core` `src/tracing.ts:32-40`), and a later call of yours starts a second NodeSDK that does not receive Genkit's spans (see the Firebase section below).
6364

6465
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.
6566

@@ -134,7 +135,7 @@ Content is off by default. That is stricter than Genkit, which records inputs an
134135

135136
Usage and finish reason are read from `genkit:output` before it is dropped, so tokens are present with content off.
136137

137-
Genkit's schema-validation error embeds the rejected data in its message: `Schema validation failed. Parse Errors: ... Provided data: <the JSON> Required JSON schema: ...` (`@genkit-ai/core` `src/schema.ts:78`). It is raised, for example, when `ai.generate({ output: { schema } })` gets model output that does not match the schema (the contract `schema` journey), and Genkit copies the message to the status and the exception event of every span the error passes through. With content off, the processor keeps the text before `Provided data:` (status, parse errors and paths), drops the rest (data, schema and, in the stack trace, the stack frames) and appends `[data redacted: captureContent is off]`. `exception.type` and the event itself are kept. Other error messages are exported as thrown: an error your own code throws with user input in its message is not redacted.
138+
Genkit's schema-validation error embeds the rejected data in its message: `Schema validation failed. Parse Errors: ... Provided data: <the JSON> Required JSON schema: ...` (`@genkit-ai/core` `src/schema.ts:78`). It is raised, for example, when `ai.generate({ output: { schema } })` gets model output that does not match the schema (the contract `schema` journey), and Genkit copies the message to the status and the exception event of every span the error passes through. With content off, the processor keeps the text before `Provided data:` (status, parse errors and paths), drops the rest (data, schema and, in the stack trace, the stack frames) and appends `[data redacted: captureContent is off]`. `exception.type` and the event itself are kept. Other error messages are exported as thrown: an error your own code throws with user input in its message is not redacted. Two Genkit errors also embed data without the `Provided data:` marker and are exported as thrown: the `validateSupport` model middleware, which a model plugin opts into, puts the whole request in its message (`Model '<name>' does not support ... Request: <JSON>`, `@genkit-ai/ai` `src/model/middleware.ts:107-115`), and a misconfigured `defineSimpleRetriever` puts the failing item in its message (`Item: <JSON>`, `src/retriever.ts:396-422`). The text kept before `Provided data:` can include object key paths from the parse errors.
138139

139140
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.
140141

0 commit comments

Comments
 (0)