The Open Framework for Building Agents
feat(eve): record Vercel AI Gateway cost on local trace spans (#1388)
Chad Hietala33ea372d9528
diff --git a/.changeset/great-moles-tap.md b/.changeset/great-moles-tap.mdnew file mode 100644index 000000000..bc8642bee--- /dev/null+++ b/.changeset/great-moles-tap.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Records Vercel AI Gateway cost on local trace spans: `agent.step` spans now carry `gen_ai.usage.cost`, `gen_ai.usage.gateway_cost`, `gen_ai.usage.input_cost`/`output_cost`, and `gen_ai.generation.id` when the gateway reports them. The attributes only exist for gateway-served calls — other providers emit nothing.diff --git a/docs/guides/instrumentation.md b/docs/guides/instrumentation.mdindex b6ab7e1ab..6d8cf4956 100644--- a/docs/guides/instrumentation.md+++ b/docs/guides/instrumentation.md@@ -15,6 +15,8 @@ The directory is an immutable OTLP/JSON spool and remains available after `eve dUse `eve trace ls` to list captured traces and `eve trace <trace>` to inspect a session's span tree.+When a model call is served by Vercel AI Gateway, its `agent.step` span also carries the cost the gateway reported: `gen_ai.usage.cost` (raw inference, USD), `gen_ai.usage.gateway_cost` (with the gateway surcharge), `gen_ai.usage.input_cost` / `gen_ai.usage.output_cost` (the split), and `gen_ai.generation.id` for reconciliation with the gateway dashboard. These attributes only exist for gateway-served calls — other providers emit nothing. Cost per turn is the sum across the turn's step spans.+The local writer is an internal development default, not a second provider layered over authored instrumentation. When `instrumentation.ts` exists, its setup retains control and the zero-config writer is not installed.### Local trace retentiondiff --git a/packages/eve/src/harness/agent-otel-provider.test.ts b/packages/eve/src/harness/agent-otel-provider.test.tsindex b37786e9b..a77dfe1b1 100644--- a/packages/eve/src/harness/agent-otel-provider.test.ts+++ b/packages/eve/src/harness/agent-otel-provider.test.ts@@ -44,6 +44,7 @@ async function emitAttempt(input: {readonly attemptIndex?: number;readonly hooks: InstrumentationHooks;readonly runInContext: InstrumentationContextRunner;+ readonly providerMetadata?: Readonly<Record<string, unknown>>;readonly sessionId: string;readonly toolError?: Error;readonly turnAlreadyStarted?: boolean;@@ -112,6 +113,14 @@ async function emitAttempt(input: {},]);+ if (input.providerMetadata !== undefined) {+ await input.hooks.publish({+ providerMetadata: input.providerMetadata,+ scope,+ type: "attempt.metadata",+ });+ }+await input.hooks.publish({ scope, type: "attempt.completed" });await input.hooks.publish({sessionId: input.sessionId,@@ -203,6 +212,55 @@ describe("createAgentOtelInstrumentation", () => {expect(JSON.stringify(spans.map((span) => span.attributes))).not.toContain("private");});+ it("writes gateway cost attributes on the step span when the gateway reports them", async () => {+ const runtime = createRuntime();+ await emitAttempt({+ hooks: runtime.hooks,+ providerMetadata: {+ gateway: {+ cost: "0.000082",+ gatewayCost: "0.000182",+ generationId: "gen_01KYR80F7ZV4RM3PJ635KMXB5V",+ inputInferenceCost: "0.000042",+ outputInferenceCost: "0.00004",+ },+ },+ runInContext: runtime.runInContext,+ sessionId: "session-1",+ turnId: "turn-1",+ turnSequence: 0,+ });+ await runtime.provider.forceFlush();++ const step = byName(runtime.exporter.getFinishedSpans(), "agent.step")[0]!;+ expect(step.attributes).toMatchObject({+ "gen_ai.generation.id": "gen_01KYR80F7ZV4RM3PJ635KMXB5V",+ "gen_ai.usage.cost": 0.000082,+ "gen_ai.usage.gateway_cost": 0.000182,+ "gen_ai.usage.input_cost": 0.000042,+ "gen_ai.usage.output_cost": 0.00004,+ });+ });++ it("emits no cost attributes when the provider is not the gateway", async () => {+ const runtime = createRuntime();+ await emitAttempt({+ hooks: runtime.hooks,+ providerMetadata: { anthropic: { cacheCreationInputTokens: 0 } },+ runInContext: runtime.runInContext,+ sessionId: "session-1",+ turnId: "turn-1",+ turnSequence: 0,+ });+ await runtime.provider.forceFlush();++ const step = byName(runtime.exporter.getFinishedSpans(), "agent.step")[0]!;+ const keys = Object.keys(step.attributes);+ for (const key of keys) {+ expect(key).not.toContain("cost");+ }+ });+it("reuses one trace id across turns", async () => {const stateStore = new InMemoryAgentTraceStateStore();const firstRuntime = createRuntime(stateStore);diff --git a/packages/eve/src/harness/agent-otel-provider.ts b/packages/eve/src/harness/agent-otel-provider.tsindex 8df93fc67..c3770f7aa 100644--- a/packages/eve/src/harness/agent-otel-provider.ts+++ b/packages/eve/src/harness/agent-otel-provider.ts@@ -12,6 +12,7 @@ import {} from "#compiled/@opentelemetry/api/index.js";import type {+ InstrumentationAttemptMetadataEvent,InstrumentationAttemptScope,InstrumentationAttemptStartedEvent,InstrumentationAttemptTerminalEvent,@@ -387,11 +388,25 @@ export function createAgentOtelInstrumentation(return state;};+ const onAttemptMetadata = (event: InstrumentationAttemptMetadataEvent): void => {+ const attempt = steps.get(event.scope);+ if (attempt === undefined) return;+ // Vercel AI Gateway reports per-call cost in providerMetadata.gateway;+ // attributes exist only when it was actually the gateway serving the call.+ const costAttributes = readGatewayCost(event.providerMetadata);+ if (costAttributes === undefined) return;+ // The vendored OTel Span surface only has singular setAttribute.+ for (const [key, value] of Object.entries(costAttributes)) {+ attempt.step.span.setAttribute(key, value);+ }+ };+return {hook: {events: {"attempt.completed": onAttemptTerminal,"attempt.failed": onAttemptTerminal,+ "attempt.metadata": onAttemptMetadata,"attempt.started": onAttemptStarted,"model.call": { after: afterModelCall, before: beforeModelCall },"session.completed": onSessionTransition,@@ -448,6 +463,39 @@ function contextFromSpanContext(spanContext: SpanContext): Context {return trace.setSpan(ROOT_CONTEXT, trace.wrapSpanContext(spanContext));}+/**+ * Extracts cost data from a step result's provider metadata. Only Vercel AI+ * Gateway reports it (`providerMetadata.gateway`): raw inference cost, the+ * gateway's surcharged total, the input/output split, and the generation id+ * for dashboard reconciliation. Values arrive as USD strings; anything+ * missing or non-numeric is skipped, so non-gateway providers get nothing.+ */+function readGatewayCost(+ providerMetadata: Readonly<Record<string, unknown>>,+): Record<string, string | number> | undefined {+ const gateway = providerMetadata.gateway;+ if (!isRecord(gateway)) return undefined;+ const attributes: Record<string, string | number> = {};+ const cost = readUsd(gateway.cost);+ if (cost !== undefined) attributes["gen_ai.usage.cost"] = cost;+ const gatewayCost = readUsd(gateway.gatewayCost);+ if (gatewayCost !== undefined) attributes["gen_ai.usage.gateway_cost"] = gatewayCost;+ const inputCost = readUsd(gateway.inputInferenceCost);+ if (inputCost !== undefined) attributes["gen_ai.usage.input_cost"] = inputCost;+ const outputCost = readUsd(gateway.outputInferenceCost);+ if (outputCost !== undefined) attributes["gen_ai.usage.output_cost"] = outputCost;+ if (typeof gateway.generationId === "string" && gateway.generationId.length > 0) {+ attributes["gen_ai.generation.id"] = gateway.generationId;+ }+ return Object.keys(attributes).length === 0 ? undefined : attributes;+}++function readUsd(value: unknown): number | undefined {+ if (typeof value !== "string") return undefined;+ const parsed = Number(value);+ return Number.isFinite(parsed) ? parsed : undefined;+}+function isSpanState(value: unknown): value is SpanState {return typeof value === "object" && value !== null && "context" in value && "span" in value;}@@ -456,6 +504,10 @@ function isToolSpanState(value: unknown): value is ToolSpanState {return isSpanState(value) && "toolSpan" in value;}+function isRecord(value: unknown): value is Record<string, unknown> {+ return typeof value === "object" && value !== null && !Array.isArray(value);+}+function modelSpanName(operationName: string): string {return operationName === "ai.generateText"? "ai.generateText.doGenerate"diff --git a/packages/eve/src/harness/ai-sdk-hook-bridge.test.ts b/packages/eve/src/harness/ai-sdk-hook-bridge.test.tsindex ee6a98412..4093b51ca 100644--- a/packages/eve/src/harness/ai-sdk-hook-bridge.test.ts+++ b/packages/eve/src/harness/ai-sdk-hook-bridge.test.ts@@ -3,6 +3,7 @@ import { describe, expect, it, vi } from "vitest";import { createAiSdkHookBridge } from "#harness/ai-sdk-hook-bridge.js";import {createInstrumentationHooks,+ type InstrumentationAttemptMetadataEvent,type InstrumentationAttemptScope,type InstrumentationProviderDefinition,} from "#harness/instrumentation-lifecycle.js";@@ -119,6 +120,33 @@ describe("createAiSdkHookBridge", () => {expect(adapterCalls).toBe(0);});+ it("publishes step provider metadata as attempt.metadata, skipping steps without any", async () => {+ const events: InstrumentationAttemptMetadataEvent[] = [];+ const hooks = createInstrumentationHooks([+ {+ events: {+ "attempt.metadata": (event) => {+ events.push(event);+ },+ },+ },+ ]);+ const bridge = createAiSdkHookBridge(scope, hooks);++ await Reflect.apply(bridge.onStepEnd!, bridge, [+ { providerMetadata: { gateway: { cost: "0.000082" } } },+ ]);+ await Reflect.apply(bridge.onStepEnd!, bridge, [{ providerMetadata: undefined }]);++ expect(events).toEqual([+ {+ providerMetadata: { gateway: { cost: "0.000082" } },+ scope,+ type: "attempt.metadata",+ },+ ]);+ });+it("isolates a failing provider from the remaining providers", async () => {const after = vi.fn();const hooks = createInstrumentationHooks([diff --git a/packages/eve/src/harness/ai-sdk-hook-bridge.ts b/packages/eve/src/harness/ai-sdk-hook-bridge.tsindex e2779999e..80945ae65 100644--- a/packages/eve/src/harness/ai-sdk-hook-bridge.ts+++ b/packages/eve/src/harness/ai-sdk-hook-bridge.ts@@ -61,6 +61,17 @@ export function createAiSdkHookBridge(const completed = toModelCallCompleted(state, id, event);await hooks.after("model.call", completed);},+ async onStepEnd(event) {+ // Step results carry provider metadata (e.g. Vercel AI Gateway cost)+ // that the per-call telemetry events don't. Publish it for providers+ // that know what to do with it; skip when there is none.+ if (event.providerMetadata === undefined) return;+ await hooks.publish({+ providerMetadata: event.providerMetadata,+ scope: state.scope,+ type: "attempt.metadata",+ });+ },async onToolExecutionStart(event) {const id = createToolCallIdentity(state, event.toolCall.toolCallId);state.toolIds.set(event.toolCall.toolCallId, id);diff --git a/packages/eve/src/harness/instrumentation-lifecycle.ts b/packages/eve/src/harness/instrumentation-lifecycle.tsindex c0e71992b..828a30693 100644--- a/packages/eve/src/harness/instrumentation-lifecycle.ts+++ b/packages/eve/src/harness/instrumentation-lifecycle.ts@@ -58,6 +58,17 @@ export interface InstrumentationAttemptTerminalEvent {readonly scope: InstrumentationAttemptScope;}+/**+ * Provider metadata for one completed step, as reported by the AI SDK+ * (`StepResult.providerMetadata`). Carries Vercel AI Gateway cost data when+ * the request went through the gateway; absent for other providers.+ */+export interface InstrumentationAttemptMetadataEvent {+ readonly type: "attempt.metadata";+ readonly scope: InstrumentationAttemptScope;+ readonly providerMetadata: Readonly<Record<string, unknown>>;+}+export interface InstrumentationModelCallStartedEvent {readonly type: "model.call.started";readonly id: string;@@ -129,6 +140,9 @@ export interface InstrumentationProviderDefinition {readonly "attempt.failed"?: (event: InstrumentationAttemptTerminalEvent,) => void | PromiseLike<void>;+ readonly "attempt.metadata"?: (+ event: InstrumentationAttemptMetadataEvent,+ ) => void | PromiseLike<void>;readonly "session.completed"?: (event: InstrumentationSessionTransitionEvent,) => void | PromiseLike<void>;@@ -171,6 +185,7 @@ export type InstrumentationRelatedEventName = keyof InstrumentationRelatedEventMexport type InstrumentationPointEvent =| InstrumentationAttemptStartedEvent+ | InstrumentationAttemptMetadataEvent| InstrumentationAttemptTerminalEvent| InstrumentationSessionStartedEvent| InstrumentationSessionTransitionEvent