The Open Framework for Building Agents
feat(eve): measure live stream event read age (#1918)
Alex Langenfeld24f6c062bc16
diff --git a/.changeset/measure-stream-event-read-age.md b/.changeset/measure-stream-event-read-age.mdnew file mode 100644index 000000000..4a03e1bdc--- /dev/null+++ b/.changeset/measure-stream-event-read-age.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Eve now emits `workflow.stream.follow.read` spans while following newly created runs, measuring each event from its durable write timestamp to the reader without counting replayed events.diff --git a/packages/eve/src/execution/workflow-runtime.test.ts b/packages/eve/src/execution/workflow-runtime.test.tsindex cd2151048..9411fbda4 100644--- a/packages/eve/src/execution/workflow-runtime.test.ts+++ b/packages/eve/src/execution/workflow-runtime.test.ts@@ -1,5 +1,7 @@import { afterEach, describe, expect, it, vi } from "vitest";+import { SpanKind } from "#compiled/@opentelemetry/api/index.js";+import type { ChannelAdapter } from "#channel/adapter.js";import { ChannelRequestIdKey } from "#context/keys.js";import { resolveInstalledPackageInfo } from "#internal/application/package.js";@@ -20,6 +22,27 @@ const getWorldMock = vi.fn();const resumeHookMock = vi.fn();const cancelRunMock = vi.fn();const startMock = vi.fn();+const startSpanMock = vi.fn();+const endSpanMock = vi.fn();++vi.mock("#compiled/@opentelemetry/api/index.js", async (importOriginal) => {+ const actual = await importOriginal<typeof import("#compiled/@opentelemetry/api/index.js")>();+ return {+ ...actual,+ trace: {+ ...actual.trace,+ getTracer: (name: string) => {+ expect(name).toBe("workflow");+ return {+ startSpan: (...args: unknown[]) => {+ startSpanMock(...args);+ return { end: endSpanMock };+ },+ };+ },+ },+ };+});vi.mock("#compiled/@workflow/core/runtime.js", () => ({cancelRun: (...args: unknown[]) => cancelRunMock(...args),@@ -41,6 +64,8 @@ afterEach(() => {resumeHookMock.mockReset();cancelRunMock.mockReset();startMock.mockReset();+ startSpanMock.mockReset();+ endSpanMock.mockReset();vi.mocked(getCompiledRuntimeAgentBundle).mockReset();vi.unstubAllEnvs();});@@ -608,4 +633,71 @@ describe("createWorkflowRuntime#createSession", () => {expect(getRunMock).toHaveBeenCalledWith("driver-run");expect(getReadable).toHaveBeenCalledTimes(1);});++ it("records live-follow read spans and preserves events", async () => {+ const compiledArtifactsSource = {} as RuntimeCompiledArtifactsSource;+ vi.mocked(getCompiledRuntimeAgentBundle).mockResolvedValue({+ compiledArtifactsSource,+ resolvedAgent: { config: {} },+ turnAgent: createTestTurnAgent(),+ } as never);+ const events = [+ { meta: { at: "invalid", id: "invalid" }, type: "test.event" },+ { meta: { at: "2026-01-01T00:00:00.000Z", id: "valid" }, type: "test.event" },+ ];+ getRunMock.mockReturnValue({ getReadable: vi.fn(() => ndjsonReadable(...events)) });+ startMock.mockResolvedValue({ runId: "driver-run" });+ getHookByTokenMock.mockResolvedValue({ runId: "driver-run" });+ vi.spyOn(Date, "now").mockReturnValue(Date.parse("2026-01-01T00:00:00.123Z"));++ const handle = await buildRuntime(compiledArtifactsSource).createSession({+ adapter,+ auth: null,+ input: { message: "hello" },+ mode: "task",+ });++ await expect(readAll(handle.events)).resolves.toEqual(events);+ expect(startSpanMock).toHaveBeenCalledExactlyOnceWith("workflow.stream.follow.read", {+ attributes: {+ "workflow.run.id": "driver-run",+ "workflow.stream.sequence": 1,+ },+ kind: SpanKind.CLIENT,+ startTime: Date.parse("2026-01-01T00:00:00.000Z"),+ });+ expect(endSpanMock).toHaveBeenCalledExactlyOnceWith(Date.parse("2026-01-01T00:00:00.123Z"));+ });++ it("does not record replayable event streams", async () => {+ const compiledArtifactsSource = {} as RuntimeCompiledArtifactsSource;+ const event = {+ meta: { at: "2026-01-01T00:00:00.000Z", id: "event-1" },+ type: "test.event",+ };+ getRunMock.mockReturnValue({ getReadable: vi.fn(() => ndjsonReadable(event)) });++ await expect(+ readAll(await buildRuntime(compiledArtifactsSource).getEventStream("driver-run")),+ ).resolves.toEqual([event]);+ expect(startSpanMock).not.toHaveBeenCalled();+ });});++function ndjsonReadable(...events: unknown[]): ReadableStream<Uint8Array> {+ const bytes = new TextEncoder().encode(+ events.map((event) => `${JSON.stringify(event)}\n`).join(""),+ );+ return new ReadableStream({+ start(controller) {+ controller.enqueue(bytes);+ controller.close();+ },+ });+}++async function readAll<T>(stream: ReadableStream<T>): Promise<T[]> {+ const values: T[] = [];+ for await (const value of stream) values.push(value);+ return values;+}diff --git a/packages/eve/src/execution/workflow-runtime.ts b/packages/eve/src/execution/workflow-runtime.tsindex a08ee48e9..1fd26ba32 100644--- a/packages/eve/src/execution/workflow-runtime.ts+++ b/packages/eve/src/execution/workflow-runtime.ts@@ -27,6 +27,7 @@ import {import { resolveInstalledPackageInfo } from "#internal/application/package.js";import { isEveDevEnvironment } from "#internal/application/dev-environment.js";import { createLogger, logError } from "#internal/logging.js";+import { SpanKind, trace } from "#compiled/@opentelemetry/api/index.js";import {getHookByToken,getRun,@@ -83,6 +84,7 @@ export const STABLE_WORKFLOW_NAMES: ReadonlySet<string> = new Set([const STABLE_ID_BASE = EVE_PACKAGE_INFO.name;const log = createLogger("execution.workflow-runtime");+const workflowTracer = trace.getTracer("workflow");interface WorkflowHookRecord {readonly runId: string;@@ -201,7 +203,7 @@ export function createWorkflowRuntime(config: {let events: ReadableStream<MessageStreamEvent> | undefined;const getEvents = () => {- events ??= parseNdjsonStream<MessageStreamEvent>(() => getRun(run.runId).getReadable());+ events ??= createLiveEventStream(run.runId);return events;};@@ -421,6 +423,46 @@ function shouldRouteToLatestDeployment(): boolean {return process.env.VERCEL_ENV === "production" || isEveDevEnvironment();}+function createLiveEventStream(sessionId: string): ReadableStream<MessageStreamEvent> {+ let sequence = 0;+ return parseNdjsonStream<MessageStreamEvent>(() => getRun(sessionId).getReadable()).pipeThrough(+ new TransformStream({+ transform(event, controller) {+ const eventSequence = sequence;+ sequence += 1;+ const readAtMs = Date.now();+ controller.enqueue(event);+ recordLiveStreamEventRead({ event, readAtMs, sequence: eventSequence, sessionId });+ },+ }),+ );+}++function recordLiveStreamEventRead(input: {+ readonly event: MessageStreamEvent;+ readonly readAtMs: number;+ readonly sequence: number;+ readonly sessionId: string;+}): void {+ const writtenAtMs = Date.parse(input.event.meta?.at ?? "");+ if (!Number.isFinite(writtenAtMs)) return;++ try {+ workflowTracer+ .startSpan("workflow.stream.follow.read", {+ attributes: {+ "workflow.run.id": input.sessionId,+ "workflow.stream.sequence": input.sequence,+ },+ kind: SpanKind.CLIENT,+ startTime: writtenAtMs,+ })+ .end(input.readAtMs);+ } catch {+ // Telemetry must not interrupt event delivery.+ }+}+function isLatestDeploymentUnsupportedError(error: unknown): boolean {return error instanceof Error && error.message.includes(LATEST_DEPLOYMENT_UNSUPPORTED_MESSAGE);}