Repository navigation
Commit 24a2929
committed
feat(genkit): add @traceai/genkit
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-82401 parent 3eaadc8 commit 24a2929
22 files changed
Lines changed: 7920 additions & 2717 deletions
File tree
- typescript
- packages/traceai_genkit
- contract
- src
- __tests__
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
331 | 331 | | |
332 | 332 | | |
333 | 333 | | |
| 334 | + | |
334 | 335 | | |
335 | 336 | | |
336 | 337 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| 65 | + | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
| 93 | + | |
| 94 | + | |
| 95 | + | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
| 107 | + | |
| 108 | + | |
| 109 | + | |
| 110 | + | |
| 111 | + | |
| 112 | + | |
| 113 | + | |
| 114 | + | |
| 115 | + | |
| 116 | + | |
| 117 | + | |
| 118 | + | |
| 119 | + | |
| 120 | + | |
| 121 | + | |
| 122 | + | |
| 123 | + | |
| 124 | + | |
| 125 | + | |
| 126 | + | |
| 127 | + | |
| 128 | + | |
| 129 | + | |
| 130 | + | |
| 131 | + | |
| 132 | + | |
| 133 | + | |
| 134 | + | |
| 135 | + | |
| 136 | + | |
| 137 | + | |
| 138 | + | |
| 139 | + | |
| 140 | + | |
| 141 | + | |
| 142 | + | |
| 143 | + | |
| 144 | + | |
| 145 | + | |
| 146 | + | |
| 147 | + | |
| 148 | + | |
| 149 | + | |
| 150 | + | |
| 151 | + | |
| 152 | + | |
| 153 | + | |
| 154 | + | |
| 155 | + | |
| 156 | + | |
| 157 | + | |
| 158 | + | |
| 159 | + | |
| 160 | + | |
| 161 | + | |
| 162 | + | |
| 163 | + | |
| 164 | + | |
| 165 | + | |
| 166 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| 65 | + | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
0 commit comments