feat(genkit): @traceai/genkit span processor (TH-8240) - #216

The Node OTLP exporter streams with Transfer-Encoding: chunked and sends
no Content-Length. The Receiver read Content-Length only, so every Node
export came back 400 with zero spans; two TH-8103 children had to put a
de-chunking relay in front of it. Receiver now accepts both framings.

It also records one entry per accepted export (path, lower-cased
headers, flattened resource attributes) via requests(), so a contract
test can assert X-Api-Key/X-Secret-Key and project_name through the
shared harness instead of a private recorder.

Verified: 6 harness tests pass, and the TanStack example's real Node
exporter delivered 4 chunked exports (4 spans, collector path, both
auth headers, project_name/project_type) with no relay.

Refs: TH-8339, TH-8103

New TypeScript package typescript/packages/traceai_genkit (@traceai/genkit,
JS only). FIGenkitSpanProcessor is passed to Genkit's
enableTelemetry({ spanProcessors }). Genkit's own telemetry-server processor
stays first (@genkit-ai/core src/tracing/node-telemetry-provider.ts:66-77), so
the Dev UI keeps working. For each ended Genkit span the processor builds a
mapped copy (Genkit's span is never modified) and hands it to the
@traceai/fi-core provider's span processor and OTLP exporter with the Future
AGI resource. Also: flushOnSignals(flush) for SIGTERM/SIGINT, README, root
README row, jest unit tests, shared-harness contract test, lockfile entries.

Tested: genkit 1.42.0 (@genkit-ai/core 1.42.0, @genkit-ai/ai 1.42.0, all
Apache-2.0 per node_modules LICENSE/package.json), Node 20.20.2, 22.23.3,
26.8.1. genkit is a peerDependency (^1.42.0) and a 1.42.0 devDependency only.

Inventory (contract/inventory.mjs, Genkit's mockModel from genkit/testing,
one flow with an ai.run() step and generateStream with a tool loop, called
and streamed: 14 spans, scope genkit-tracer, sdk-trace-base 1.25 shape):
- action/flow: genkit:type, genkit:metadata:subtype, genkit:key, genkit:name,
  genkit:isRoot (bool), genkit:path, genkit:input, genkit:output,
  genkit:state, genkit:metadata:context
- flowStep: genkit:type, genkit:name, genkit:path, genkit:output, genkit:state
- util (generate): genkit:type, genkit:name, genkit:path, genkit:input,
  genkit:output, genkit:state
- action/model and action/tool: genkit:type, genkit:metadata:subtype,
  genkit:key, genkit:name, genkit:path, genkit:input, genkit:output,
  genkit:state
- model genkit:output JSON: message, finishReason, usage {inputTokens,
  outputTokens, totalTokens}, latencyMs
- beta agent run adds promptTemplate (render, genkit:metadata:promptName),
  flowStep runTurn-1 (genkit:metadata:agent:snapshotId) and action/agent
  (genkit:metadata:agent:sessionId, genkit:init); errors add
  genkit:isFailureSource.
Kind map from genkit:type labels (core action.ts:538-543, flow.ts:219-221,
ai generate/action.ts:147-149, prompt.ts:273-275,490-492) and the ActionType
list (core registry.ts:40-62): model/background-model LLM, tool/tool.v2 TOOL,
retriever RETRIEVER, embedder EMBEDDING, reranker RERANKER, evaluator
EVALUATOR, agent AGENT, flow and other actions CHAIN, flowStep/util/
promptTemplate/dotprompt CHAIN, unknown type: no kind, span still exported.
Usage: only inputTokens/outputTokens/totalTokens (seen on the dumped model
spans) go to gen_ai.usage.input_tokens/output_tokens/total_tokens, on model
spans only. thoughtsTokens, cachedContentTokens and the character/media
counters exist in GenerationUsageSchema (ai model-types.ts:260-275) but no
inventoried span carried them: unavailable, not mapped. Promoted token/cost
keys on a non-model span move to genkit.usage.<key>; the contract test checks
the trace sum equals the two model calls (32/7/39). Model:
gen_ai.request.model = genkit:name of the model action span (not parsed);
provider and cost unavailable.

Deviations from the TH-8240 architecture/docs, with evidence:
1. enableTelemetry and flushTracing are exported from genkit/tracing
   (genkit/src/tracing.ts:43-44), not genkit. genkit/tracing does not
   initialise the telemetry provider; importing genkit does
   (genkit/src/common.ts:173-175 -> @genkit-ai/core src/node.ts:20-23).
   enableTelemetry before any genkit import throws FAILED_PRECONDITION:
   TelemetryProvider is not initialized (observed). README says import
   genkit first.
2. @genkit-ai/core 1.42.0 telemetryTypes.ts is 24 lines and has only
   TelemetryConfig = Partial<NodeSDKConfiguration> (line 24); there is no
   TelemetryOptions with forceDevExport / metricExportIntervalMillis /
   disableMetrics. Those are @genkit-ai/google-cloud options (src/types.ts:
   92,110). The example does not pass disableMetrics (types.test.ts asserts
   it is a type error). Metrics are not exported anyway: enableTelemetry adds
   no metricReader and @opentelemetry/sdk-node 0.52.1 builds a meter provider
   only with a reader or views (build/src/sdk.js:97-105,158). Dev UI export
   is not controlled by forceDevExport: Genkit always prepends its
   telemetry-server processor.
3. register() must be called with setGlobalTracerProvider: false (the docs
   example omits it). fi-core defaults it to true (otel.ts:486,604-605);
   Genkit takes its tracer from the global API (instrumentation.ts:96,197),
   so with fi-core global the NodeSDK cannot register and Genkit spans reach
   Future AGI raw (content, no kind). Contract control test covers this; the
   processor emits warning TRACEAI_GENKIT_GLOBAL_PROVIDER.
4. Session: a native key exists for beta agents only,
   genkit:metadata:agent:sessionId (ai/src/agent.ts:1061-1063), mapped to
   session.id on the agent span. Flows have none; the app sets it with
   fi-core setSession() around the call (read in onStart from the parent
   context). No session id is invented.
5. Tool name is genkit:name of the tool action span (spec: unverified).
6. AC-06 flush: flushTracing is confirmed (core src/tracing.ts:113). genkit
   registers SIGTERM/SIGINT listeners at import that call process.exit(0)
   without flushing (genkit/src/genkit.ts:786-793), so an app listener that
   awaits flushTracing() loses the race (contract control test). Added
   flushOnSignals(flushTracing), which runs the flush before the earlier
   listeners.
7. Genkit's NodeSDK uses sdk-trace-base 1.25 spans (parentSpanId,
   instrumentationLibrary); fi-core exports with 2.x (parentSpanContext,
   instrumentationScope). The processor converts the copy and reads the
   fi-core provider's _activeSpanProcessor/_resource (no public accessor).
8. Kinds beyond the spec's list (reranker, evaluator, agent,
   background-model, tool.v2, non-action types) come from the inventory.
9. Lockfile: @genkit-ai/core lists @genkit-ai/firebase as an
   optionalDependency, so the dev-only tree adds firebase-admin and
   @genkit-ai/google-cloud. Neither is a dependency of @traceai/genkit.
   pnpm-lock.yaml keeps 3eaadc8 byte for byte plus the new importer and the
   177 packages / 180 snapshots reachable from it that the base lacked
   (git diff --minimal: 2374 insertions, 0 deletions);
   pnpm install --frozen-lockfile (with and without --ignore-scripts)
   exits 0: "Lockfile is up to date, resolution step is skipped".

Tests (this tree): jest 5 suites, 62 tests passed (Node 26.8.1, 20.20.2,
22.23.3). Contract suite 20 passed with NODE_BINARY = node 26.8.1, 20.20.2
and 22.23.3. pnpm pack: 63 files, dist/ + README.md + package.json only.

approved: Nikhil 2026-10-03 blanket
Refs: TH-8240

Installed-review N1. Genkit's ValidationError embeds the rejected data in
its message after "Provided data:" (@genkit-ai/core 1.42.0 src/schema.ts:78)
and instrumentation.ts:156-162 copies e.message to the span status and an
exception event on every span the error passes through. The processor passed
status and events through unchanged, so with captureContent off (default) a
structured ai.generate whose model output fails the schema exported that
output to Future AGI.

With captureContent off, toExportableSpan now cuts status.message and the
exception.message / exception.stacktrace attributes of exception events at
"Provided data:" and appends "[data redacted: captureContent is off]".
exception.type, the event and every other event are kept. New objects are
built; Genkit's span (read by the Dev UI exporter) is not modified. With
captureContent true both pass through unchanged.

Tests (written first):
- jest processor.test.ts: marker in status.message and an exception event,
  off redacts / on keeps / no-marker unchanged. RED on 24a2929: the off case
  failed (marker present), 16 others passed.
- contract: new `schema` journey (ai.generate with an output schema, the fake
  mockModel returns non-matching JSON). Asserts the model output text and
  its marker appear nowhere in the export, both error spans end with the
  note, exception.type kept ("400", GenkitError.code). RED on 24a2929 (marker
  found in the exported exception event); opt-in control passed.
- GREEN: jest 65 passed; contract 20 passed (Node 26.8.1, no matrix).

README: Content table row and paragraph for error-message redaction; the
Errors line no longer says status/events pass through unchanged.

approved: Nikhil 2026-10-03 blanket
Refs: TH-8240

…pans

Installed-review N3. isPromotedUsageKey matched only gen_ai.cost.total and
llm.cost.total exactly, so cost parts (gen_ai.cost.input/output,
llm.cost.prompt/completion) set through fi-core context attributes or Genkit
telemetryLabels stayed unprefixed on flow/step/generate/tool spans, where
fi-collector would sum them into the trace cost again. Match the cost
families by prefix (gen_ai.cost., llm.cost.), like the token families. Model
spans keep the keys unprefixed.

Tests (written first), mapping.test.ts:
- every gen_ai.cost.* / llm.cost.* key is promoted (parts and totals);
  look-alikes (gen_ai.costs, llm.costing, genkit.usage.*) are not.
- cost parts on a flow span, from span and from context attributes, move to
  genkit.usage.<key>.
- a model span keeps them unprefixed (control).
RED on b5cb204: the first two failed (2 failed, 37 passed in the file).
GREEN: jest 68 passed; contract 20 passed (Node 26.8.1). The contract
helper's promoted-key check now uses the same prefixes.

README: the promoted-key list names the cost prefixes.

approved: Nikhil 2026-10-03 blanket
Refs: TH-8240

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

…y 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

…I prices them

gen_ai.request.model carried the registered action name
("googleai/gemini-3.5-flash"). fi-collector prices a span by an exact
model-name lookup in its litellm table, which lists "gemini-3.5-flash",
so every Genkit model span showed cost 0 and no provider.

Model spans now get the vendor model id without the plugin namespace on
gen_ai.request.model and gen_ai.response.model, and gen_ai.provider.name
from the namespace for the model plugins whose namespaces were read from
their published packages (googleai -> google, vertexai -> vertexai,
openai, deepseek, xai, anthropic, ollama, mistral -> mistralai, groq,
aws-bedrock -> aws, azure-openai -> azure). Other namespaces leave the
provider unset. The full registered name stays on genkit:name.

Live check with gemini-3.5-flash: model gemini-3.5-flash, provider
google, cost 0.000234 / 0.000357 / 0.000147 in ClickHouse and the UI
(was 0). README: replace the retired gemini-2.5-flash example, document
the provider map and how cost is computed.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

The catalog rows for all TH-8103 integrations now live in one PR
(docs/th-8103-integration-catalog), so this PR no longer conflicts with
its siblings in README.md and can merge in any order.

Co-Authored-By: Claude Opus 5.5 <[email protected]>