diff --git a/.changeset/eager-meteors-wear.md b/.changeset/eager-meteors-wear.md new file mode 100644 index 00000000000..22a8680647d --- /dev/null +++ b/.changeset/eager-meteors-wear.md @@ -0,0 +1,5 @@ +--- +'@mastra/client-js': minor +--- + +Add getTracePage() for Platform. diff --git a/.changeset/four-foxes-pick.md b/.changeset/four-foxes-pick.md new file mode 100644 index 00000000000..9f168506c8d --- /dev/null +++ b/.changeset/four-foxes-pick.md @@ -0,0 +1,5 @@ +--- +'@mastra/core': minor +--- + +Add shared contracts for bounded trace reads. diff --git a/client-sdks/client-js/src/client.ts b/client-sdks/client-js/src/client.ts index 85ee7de066f..d7498e0563d 100644 --- a/client-sdks/client-js/src/client.ts +++ b/client-sdks/client-js/src/client.ts @@ -45,6 +45,8 @@ import type { } from './resources/observability'; import type { TraceRecord, + GetTracePageArgs, + TracePageResponse, GetTraceLightResponse, GetSpanResponse, ListTracesArgs, @@ -1283,6 +1285,14 @@ export class MastraClient extends BaseResource { return this.observability.getTrace(traceId); } + /** + * Retrieves a bounded trace page from Platform. OSS servers do not serve this endpoint. + * Check `capabilities.tracePage` before calling. + */ + getTracePage(request: GetTracePageArgs): Promise { + return this.observability.getTracePage(request); + } + /** Retrieves a lightweight trace by ID (timeline fields only, excludes heavy fields). */ getTraceLight(traceId: string): Promise { return this.observability.getTraceLight(traceId); diff --git a/client-sdks/client-js/src/resources/observability-route-types.ts b/client-sdks/client-js/src/resources/observability-route-types.ts index 5aea5e9f357..244999c97e7 100644 --- a/client-sdks/client-js/src/resources/observability-route-types.ts +++ b/client-sdks/client-js/src/resources/observability-route-types.ts @@ -13,6 +13,8 @@ type ListArgs = Simplify< } >; +export type { TracePageRequest, GetTracePageArgs, TracePageResponse, TracePageNode } from './trace-page-types'; + export type TraceRecord = Response<'GET /observability/traces/:traceId'>; export type GetTraceLightResponse = Response<'GET /observability/traces/:traceId/light'>; export type GetSpanResponse = Response<'GET /observability/traces/:traceId/spans/:spanId'>; diff --git a/client-sdks/client-js/src/resources/observability.trace-page.test.ts b/client-sdks/client-js/src/resources/observability.trace-page.test.ts new file mode 100644 index 00000000000..c13819e2617 --- /dev/null +++ b/client-sdks/client-js/src/resources/observability.trace-page.test.ts @@ -0,0 +1,125 @@ +import { createServer } from 'node:http'; +import type { AddressInfo } from 'node:net'; +import { SpanType } from '@mastra/core/observability'; +import { InMemoryStore, readTracePage } from '@mastra/core/storage'; +import { afterAll, beforeAll, beforeEach, describe, expect, it } from 'vitest'; +import { MastraClient } from '../client'; + +// Real HTTP transport and real storage: proves the paged API does not serialize IDs or cursors as GET parameters. +describe('legacy and paged trace reads over HTTP', () => { + const storage = new InMemoryStore(); + let client: MastraClient; + let failures: (number | 'disconnect')[] = []; + let requests: unknown[] = []; + const makeClient = (retries?: number) => + new MastraClient({ + baseUrl: `http://127.0.0.1:${(server.address() as AddressInfo).port}`, + retries, + backoffMs: 1, + }); + const server = createServer(async (req, res) => { + try { + expect(req.url).toBe( + req.method === 'GET' ? '/api/observability/traces/trace' : '/api/observability/traces/trace/page', + ); + const store = (await storage.getStore('observability'))!; + const chunks: Buffer[] = []; + for await (const chunk of req) chunks.push(Buffer.from(chunk)); + const body = chunks.length ? JSON.parse(Buffer.concat(chunks).toString()) : undefined; + requests.push(body); + const failure = failures.shift(); + if (failure === 'disconnect') { + req.socket.destroy(); + return; + } + if (failure) { + res.writeHead(failure).end(JSON.stringify({ error: 'Request failed' })); + return; + } + const result = + req.method === 'GET' + ? await store.getTrace({ traceId: 'trace' }) + : await readTracePage( + { + scopeKey: 'test-backend', + structure: async () => (await store.getStructure({ traceId: 'trace' }))?.spans ?? null, + spans: async (_, spanIds) => (await store.getSpans({ traceId: 'trace', spanIds })).spans, + }, + 'trace', + body, + ); + res.setHeader('content-type', 'application/json'); + res.end(JSON.stringify(result)); + } catch (error) { + res.writeHead(500).end(JSON.stringify({ error: String(error) })); + } + }); + beforeAll(async () => { + const store = (await storage.getStore('observability'))!; + await store.batchCreateSpans({ + records: ['a', 'b'].map(spanId => ({ + traceId: 'trace', + spanId, + name: spanId, + spanType: SpanType.AGENT_RUN, + isEvent: false, + startedAt: new Date('2026-11-01'), + input: { value: spanId }, + })), + }); + await new Promise(resolve => server.listen(0, '127.0.0.1', resolve)); + client = makeClient(0); + }); + beforeEach(() => { + failures = []; + requests = []; + }); + afterAll(async () => { + server.closeAllConnections(); + await new Promise((resolve, reject) => server.close(error => (error ? reject(error) : resolve()))); + }); + it('keeps legacy GET responses and reads bounded pages through POST', async () => { + expect((await client.getTrace('trace')).spans.map(span => span.spanId)).toEqual(['a', 'b']); + const first = await client.getTracePage({ traceId: 'trace', limit: 1 }); + expect(first.nodes.map(node => node.spanId)).toEqual(['a']); + const next = await client.getTracePage({ traceId: 'trace', cursor: first.nextCursor! }); + expect(next.nodes.map(node => node.spanId)).toEqual(['b']); + expect(next.nextCursor).toBeUndefined(); + }); + it('hydrates exactly the IDs absent from the caller cache', async () => { + const page = await client.getTracePage({ traceId: 'trace', spanIds: ['b'], include: 'full' }); + expect(page.nodes).toHaveLength(1); + expect(page.nodes[0]!.details?.input).toEqual({ value: 'b' }); + }); + it.each([503, 'disconnect'] as const)( + 'retries a trace page after %s without changing its selection', + async failure => { + failures = [failure]; + const page = await makeClient().getTracePage({ traceId: 'trace', spanIds: ['b'], include: 'full' }); + expect(page.nodes.map(node => node.spanId)).toEqual(['b']); + expect(requests).toEqual([ + { spanIds: ['b'], include: 'full' }, + { spanIds: ['b'], include: 'full' }, + ]); + }, + ); + it('retries a continuation without losing or repeating a span', async () => { + const first = await client.getTracePage({ traceId: 'trace', limit: 1 }); + requests = []; + failures = [503]; + const next = await makeClient().getTracePage({ traceId: 'trace', cursor: first.nextCursor! }); + expect([...first.nodes, ...next.nodes].map(node => node.spanId)).toEqual(['a', 'b']); + expect(next.nextCursor).toBeUndefined(); + expect(requests).toEqual([{ cursor: first.nextCursor }, { cursor: first.nextCursor }]); + }); + it.each([400, 409, 413, 422, 501])('does not retry terminal HTTP %s', async status => { + failures = [status]; + await expect(makeClient().getTracePage({ traceId: 'trace' })).rejects.toMatchObject({ status }); + expect(requests).toEqual([{}]); + }); + it('honors explicitly disabled retries', async () => { + failures = [503]; + await expect(client.getTracePage({ traceId: 'trace' })).rejects.toMatchObject({ status: 503 }); + expect(requests).toEqual([{}]); + }); +}); diff --git a/client-sdks/client-js/src/resources/observability.ts b/client-sdks/client-js/src/resources/observability.ts index ccd33e983b8..d8b1c1868f4 100644 --- a/client-sdks/client-js/src/resources/observability.ts +++ b/client-sdks/client-js/src/resources/observability.ts @@ -20,6 +20,8 @@ import { toQueryParams } from '../utils'; import { BaseResource } from './base'; import type { TraceRecord, + GetTracePageArgs, + TracePageResponse, GetTraceLightResponse, GetSpanResponse, ListTracesArgs, @@ -233,6 +235,19 @@ export class Observability extends BaseResource { return this.request(`/observability/traces/${traceId}`); } + /** + * Retrieves a bounded trace page from Platform. OSS servers do not serve this endpoint. + * Check `capabilities.tracePage` before calling. + */ + getTracePage(request: GetTracePageArgs): Promise { + const { traceId, ...body } = request; + return this.request(`/observability/traces/${encodeURIComponent(traceId)}/page`, { + method: 'POST', + body, + retries: this.readRetries(), + }); + } + /** * Retrieves a lightweight trace by ID (timeline fields only). * Excludes heavy fields (input, output, attributes, metadata, tags, links) diff --git a/client-sdks/client-js/src/resources/trace-page-types.ts b/client-sdks/client-js/src/resources/trace-page-types.ts new file mode 100644 index 00000000000..f5aec0927d5 --- /dev/null +++ b/client-sdks/client-js/src/resources/trace-page-types.ts @@ -0,0 +1,72 @@ +import type { SpanRecord } from '@mastra/core/storage'; +import type { Serialized } from '../types'; + +// Platform serves this contract; it is not part of the @mastra/server route registry. +// Keep declarations independent of new core exports so older supported core packages can resolve them. +// type-tests/trace-page.test-d.ts verifies parity with the shared core schemas. +export type TracePageRequest = + | { + anchorSpanId?: string; + depth?: number; + spanIds?: string[]; + search?: string; + ancestors?: boolean; + include?: 'structure' | 'full'; + limit?: number; + maxBytes?: number; + } + | { cursor: string }; +export type GetTracePageArgs = TracePageRequest & { traceId: string }; +export type TracePageNode = Pick< + Serialized, + | 'traceId' + | 'spanId' + | 'parentSpanId' + | 'name' + | 'spanType' + | 'isEvent' + | 'startedAt' + | 'endedAt' + | 'entityType' + | 'entityId' + | 'entityName' + | 'model' + | 'provider' + | 'outcome' + | 'stopReason' + | 'stopReasonContext' + | 'errorCount' + | 'externalParentSpanId' + | 'resumedFromSpanId' + | 'timeToFirstChunkMs' + | 'inputPreview' + | 'outputPreview' + | 'errorPreview' + | 'timeToFirstTokenMs' + | 'experimentId' + | 'userId' + | 'organizationId' + | 'resourceId' + | 'runId' + | 'sessionId' + | 'threadId' + | 'requestId' + | 'environment' + | 'source' + | 'serviceName' + | 'tags' +> & { + projectId?: string | null; + status: 'success' | 'error' | 'running'; + childCount: number | null; + match: boolean; + parentState: 'root' | 'available' | 'unavailable' | 'not-requested'; + details?: Omit, 'scope' | 'links'>; +}; +export interface TracePageResponse { + traceId: string; + nodes: TracePageNode[]; + missingSpanIds: string[]; + nextCursor?: string; + ancestorPaths: 'not-requested' | 'continued' | 'complete' | 'unavailable'; +} diff --git a/client-sdks/client-js/src/types.ts b/client-sdks/client-js/src/types.ts index 7d8eb251aeb..db0f6c9073c 100644 --- a/client-sdks/client-js/src/types.ts +++ b/client-sdks/client-js/src/types.ts @@ -1492,7 +1492,14 @@ export interface MastraPackage { export type GetSystemPackagesResponse = GeneratedResponse<'GET /system/packages'>; -export type GetObservabilityCapabilitiesResponse = GeneratedResponse<'GET /observability/capabilities'>; +type BaseObservabilityCapabilitiesResponse = GeneratedResponse<'GET /observability/capabilities'>; +export type GetObservabilityCapabilitiesResponse = Omit & { + capabilities: BaseObservabilityCapabilitiesResponse['capabilities'] & { + /** Optional capabilities advertised by Platform's trace page endpoint. */ + tracePage?: boolean; + tracePageSearch?: boolean; + }; +}; // ============================================================================ // Workspace Types @@ -2607,3 +2614,10 @@ export type { SavedViewSort, SavedViewState, } from '@mastra/core/storage'; + +export type { + GetTracePageArgs, + TracePageRequest, + TracePageResponse, + TracePageNode, +} from './resources/observability-route-types'; diff --git a/client-sdks/client-js/type-tests/trace-page.test-d.ts b/client-sdks/client-js/type-tests/trace-page.test-d.ts new file mode 100644 index 00000000000..1ab14d40086 --- /dev/null +++ b/client-sdks/client-js/type-tests/trace-page.test-d.ts @@ -0,0 +1,29 @@ +import type { TracePageRequest as CoreRequest, TracePageResponse as CoreResponse } from '@mastra/core/storage'; +import { expectTypeOf, test } from 'vitest'; +import type { MastraClient } from '../src/client'; +import type { TracePageRequest, TracePageResponse } from '../src/resources/trace-page-types'; +import type { RouteKey } from '../src/route-types.generated'; +import type { GetObservabilityCapabilitiesResponse, Serialized } from '../src/types'; + +type CoreWireResponse = Serialized; +type CoreWireNode = CoreWireResponse['nodes'][number]; +// HTTP serializes the internal status enum as its string values. +type ExpectedResponse = Omit & { + nodes: (Omit & { status: `${CoreWireNode['status']}` })[]; +}; + +test('keeps Platform trace page types aligned without exposing an OSS server route', () => { + expectTypeOf().toEqualTypeOf(); + expectTypeOf().toMatchTypeOf(); + expectTypeOf().toMatchTypeOf(); + expectTypeOf().toEqualTypeOf(); + expectTypeOf().toEqualTypeOf(); + expectTypeOf>().toEqualTypeOf< + keyof NonNullable + >(); + expectTypeOf>().toEqualTypeOf>(); + expectTypeOf>().toEqualTypeOf(); + expectTypeOf().toEqualTypeOf< + boolean | undefined + >(); +}); diff --git a/client-sdks/client-js/type-tests/tsconfig.thread-query.json b/client-sdks/client-js/type-tests/tsconfig.thread-query.json index a342b992e44..0381852df4f 100644 --- a/client-sdks/client-js/type-tests/tsconfig.thread-query.json +++ b/client-sdks/client-js/type-tests/tsconfig.thread-query.json @@ -4,6 +4,7 @@ "include": [ "../src/**/*.ts", "./thread-query.test-d.ts", + "./trace-page.test-d.ts", "./deletion.test-d.ts", "./request-context.test-d.ts", "./generate-legacy.test-d.ts" diff --git a/client-sdks/client-js/vitest.config.js b/client-sdks/client-js/vitest.config.ts similarity index 92% rename from client-sdks/client-js/vitest.config.js rename to client-sdks/client-js/vitest.config.ts index 02c2c0c12d6..055a8c337ea 100644 --- a/client-sdks/client-js/vitest.config.js +++ b/client-sdks/client-js/vitest.config.ts @@ -9,6 +9,7 @@ export default defineConfig({ enabled: true, include: [ 'type-tests/thread-query.test-d.ts', + 'type-tests/trace-page.test-d.ts', 'type-tests/deletion.test-d.ts', 'type-tests/request-context.test-d.ts', 'type-tests/generate-legacy.test-d.ts', diff --git a/packages/core/src/storage/domains/observability/index.ts b/packages/core/src/storage/domains/observability/index.ts index b091416bcf5..df70b5e521e 100644 --- a/packages/core/src/storage/domains/observability/index.ts +++ b/packages/core/src/storage/domains/observability/index.ts @@ -165,3 +165,5 @@ export * from './tracing'; export * from './types'; export * from './span-query'; export * from './thread-query'; + +export * from './trace-page'; diff --git a/packages/core/src/storage/domains/observability/trace-page.test.ts b/packages/core/src/storage/domains/observability/trace-page.test.ts new file mode 100644 index 00000000000..5fa3a592aff --- /dev/null +++ b/packages/core/src/storage/domains/observability/trace-page.test.ts @@ -0,0 +1,413 @@ +import { createHash } from 'node:crypto'; +import { describe, expect, it } from 'vitest'; +import { SpanType } from '../../../observability/types'; +import { readTracePage, tracePageRequestSchema, tracePageResponseSchema } from './trace-page'; +import type { TracePageSource, TracePageResponse } from './trace-page'; +import type { SpanRecord } from './tracing'; + +const span = (spanId: string, parentSpanId: string | null = null, input?: unknown): SpanRecord => ({ + traceId: 'trace', + spanId, + parentSpanId, + name: spanId, + spanType: SpanType.AGENT_RUN, + isEvent: false, + startedAt: new Date('2026-11-01'), + input, +}); +function source(rows: SpanRecord[], matches: string[] = []): TracePageSource { + return { + scopeKey: 'org/project/user', + structure: async () => rows, + spans: async (_, ids) => rows.filter(row => ids.includes(row.spanId)), + search: async () => matches, + }; +} +async function drain(src: TracePageSource, first: TracePageResponse): Promise { + const pages = [first]; + while (pages.at(-1)!.nextCursor) { + if (pages.length > 100) throw new Error('Continuation failed to progress'); + pages.push((await readTracePage(src, 'trace', { cursor: pages.at(-1)!.nextCursor! }))!); + } + return pages; +} + +describe('bounded trace exploration', () => { + it('keeps context on each actual root across pages, without treating orphan or anchored children as roots', async () => { + const context = { + experimentId: 'experiment', + userId: 'user', + organizationId: 'org', + projectId: 'project', + resourceId: 'resource', + runId: 'run', + sessionId: 'session', + threadId: 'thread', + requestId: 'request', + environment: 'test', + source: 'service', + serviceName: 'worker', + tags: ['test'], + }; + const src = source([ + { ...span('root-a'), ...context }, + { ...span('root-b'), ...context, userId: 'other' }, + { ...span('child', 'root-a'), ...context }, + { ...span('orphan', 'absent'), ...context }, + ]); + const pages = await drain(src, (await readTracePage(src, 'trace', { limit: 1 }))!); + const nodes = pages.flatMap(page => tracePageResponseSchema.parse(page).nodes); + expect(nodes.find(node => node.spanId === 'root-a')).toMatchObject(context); + expect(nodes.find(node => node.spanId === 'root-b')).toMatchObject({ ...context, userId: 'other' }); + for (const node of nodes.filter(node => node.parentSpanId)) { + for (const key of Object.keys(context)) expect(node).not.toHaveProperty(key); + } + for (const request of [{ anchorSpanId: 'child' }, { spanIds: ['child'] }]) { + const page = (await readTracePage(src, 'trace', request))!; + expect(page.nodes.map(node => node.spanId)).toEqual(['child']); + for (const key of Object.keys(context)) expect(page.nodes[0]).not.toHaveProperty(key); + } + const rootPage = await readTracePage(src, 'trace', { spanIds: ['root-b'] }); + expect(rootPage!.nodes[0]).toMatchObject({ ...context, userId: 'other' }); + }); + + it('counts root context toward the page byte budget', async () => { + const src = source([ + { ...span('a'), tags: ['x'.repeat(40000)] }, + { ...span('b'), tags: ['y'.repeat(40000)] }, + ]); + const pages = await drain(src, (await readTracePage(src, 'trace', { maxBytes: 65536 }))!); + expect(pages.map(page => page.nodes.map(node => node.spanId))).toEqual([['a'], ['b']]); + for (const page of pages) expect(Buffer.byteLength(JSON.stringify(page))).toBeLessThanOrEqual(65536); + }); + + it('omits scope and links from full details without charging their bytes to the page', async () => { + const record = { ...span('root'), scope: { hidden: 'x'.repeat(70000) }, links: [{ hidden: 'y'.repeat(70000) }] }; + const page = await readTracePage(source([record]), 'trace', { include: 'full', maxBytes: 65536 }); + expect(page!.nodes[0]!.details).not.toHaveProperty('scope'); + expect(page!.nodes[0]!.details).not.toHaveProperty('links'); + expect(record).toHaveProperty('scope'); + expect(record).toHaveProperty('links'); + }); + + it.each(['structure', 'full'] as const)( + 'preserves execution diagnostics in %s pages without requiring payload hydration', + async include => { + const diagnostics = { + model: 'gpt-6.1-sol', + provider: 'openai', + outcome: 'failed', + stopReason: 'max_steps', + stopReasonContext: { maxSteps: 10 }, + errorCount: 0, + externalParentSpanId: 'external', + resumedFromSpanId: 'previous', + timeToFirstChunkMs: 0, + timeToFirstTokenMs: 12, + inputPreview: 'question', + outputPreview: '', + errorPreview: 'limit reached', + }; + const record = { + ...span('root', null, { large: 'payload' }), + createdAt: new Date('2026-11-01'), + updatedAt: null, + ...diagnostics, + }; + const page = await readTracePage(source([record]), 'trace', { include }); + expect(tracePageResponseSchema.parse(page).nodes[0]).toMatchObject(diagnostics); + if (include === 'full') expect(page!.nodes[0]!.details).toEqual(record); + else expect(page!.nodes[0]).not.toHaveProperty('details'); + expect(page!.nodes[0]).not.toHaveProperty('input'); + }, + ); + + it.each(['inputPreview', 'stopReasonContext'] as const)( + 'counts %s toward the structure page byte budget', + async field => { + const value = 'x'.repeat(40000); + const diagnostics = { [field]: field === 'stopReasonContext' ? { reason: value } : value }; + const src = source([ + { ...span('a'), ...diagnostics }, + { ...span('b'), ...diagnostics }, + ]); + const pages = await drain(src, (await readTracePage(src, 'trace', { maxBytes: 65536 }))!); + expect(pages.map(page => page.nodes.map(node => node.spanId))).toEqual([['a'], ['b']]); + for (const page of pages) expect(Buffer.byteLength(JSON.stringify(page))).toBeLessThanOrEqual(65536); + }, + ); + + it('loads a shallow breadth-first tree with deterministic sibling ordering and discoverable children', async () => { + const src = source([span('z', 'root'), span('root'), span('deep', 'a'), span('a', 'root')]); + const pages = await drain(src, (await readTracePage(src, 'trace', { depth: 1, limit: 2 }))!); + expect(pages.flatMap(page => page.nodes.map(node => node.spanId))).toEqual(['root', 'a', 'z']); + expect(pages[0]!.nodes[1]).toMatchObject({ childCount: 1 }); + expect(pages.at(-1)!.nextCursor).toBeUndefined(); + expect(pages[0]).not.toHaveProperty('version'); + }); + + it('finds an unloaded deep match and continues its ancestor path across strict total node limits', async () => { + const src = source( + [span('root'), span('a', 'root'), span('b', 'a'), span('match', 'b'), span('other', 'root')], + ['match'], + ); + const pages = await drain(src, (await readTracePage(src, 'trace', { search: 'timeout', limit: 1 }))!); + expect(pages.flatMap(page => page.nodes.map(node => [node.spanId, node.match]))).toEqual([ + ['root', false], + ['a', false], + ['b', false], + ['match', true], + ]); + expect(pages.map(page => page.ancestorPaths)).toEqual(['continued', 'continued', 'continued', 'complete']); + }); + + it('deduplicates shared ancestors and distinguishes an unavailable parent from a root', async () => { + const src = source([span('root', 'missing'), span('a', 'root'), span('b', 'root')], ['a', 'b']); + const pages = await drain(src, (await readTracePage(src, 'trace', { search: 'error', limit: 2 }))!); + expect(pages.flatMap(page => page.nodes.map(node => node.spanId))).toEqual(['root', 'a', 'b']); + expect(pages[0]!.nodes[0]!.parentState).toBe('unavailable'); + expect(pages.at(-1)!.ancestorPaths).toBe('unavailable'); + }); + + it('hydrates only explicit IDs, reports missing IDs, and preserves requested order across pages', async () => { + const src = source([span('root'), span('a', 'root', { answer: 42 }), span('b', 'a')]); + src.structure = async () => { + throw new Error('Explicit IDs must not load topology'); + }; + + const pages = await drain( + src, + (await readTracePage(src, 'trace', { + spanIds: ['b', 'absent', 'a', 'b'], + include: 'full', + limit: 1, + }))!, + ); + expect(pages.flatMap(page => page.nodes.map(node => node.spanId))).toEqual(['b', 'a']); + expect(pages[0]!.missingSpanIds).toEqual([]); + expect(pages[1]!.missingSpanIds).toEqual(['absent']); + expect(pages[1]!.nodes).toEqual([]); + expect(pages[2]!.nodes[0]!.details?.input).toEqual({ answer: 42 }); + expect(pages[0]!.nodes[0]!.details?.spanId).toBe('b'); + }); + + it('continues at the first unreturned payload when the byte budget fills', async () => { + const src = source([span('a', null, 'x'.repeat(40000)), span('b', null, 'y'.repeat(40000))]); + const pages = await drain(src, (await readTracePage(src, 'trace', { include: 'full', maxBytes: 65536 }))!); + expect(pages.map(page => page.nodes.map(node => node.spanId))).toEqual([['a'], ['b']]); + for (const page of pages) expect(Buffer.byteLength(JSON.stringify(page))).toBeLessThanOrEqual(65536); + }); + + it('gives an actionable error for one oversized payload rather than a cursor that never advances', async () => { + const src = source([span('a', null, 'x'.repeat(70000))]); + await expect(readTracePage(src, 'trace', { include: 'full', maxBytes: 65536 })).rejects.toMatchObject({ + code: 'PAYLOAD_TOO_LARGE', + }); + const structure = await readTracePage(src, 'trace', { maxBytes: 65536 }); + expect(structure!.nodes[0]!.details).toBeUndefined(); + expect(JSON.stringify(structure)).not.toContain('xxxxx'); + }); + + it('rejects scope changes and late arrivals even when root activity is unchanged', async () => { + const rows = [span('a'), span('b')]; + const src = source(rows); + const first = (await readTracePage(src, 'trace', { limit: 1 }))!; + const request = { cursor: first.nextCursor! }; + await expect(readTracePage({ ...src, scopeKey: 'another/org' }, 'trace', request)).rejects.toMatchObject({ + code: 'TRACE_CHANGED', + }); + rows.push(span('aa')); + await expect(readTracePage(src, 'trace', request)).rejects.toMatchObject({ code: 'TRACE_CHANGED' }); + }); + + it('rejects cyclic topology and malformed or conflicting continuation requests', async () => { + await expect(readTracePage(source([span('a', 'b'), span('b', 'a')]), 'trace', {})).rejects.toMatchObject({ + code: 'INVALID_TOPOLOGY', + }); + await expect(readTracePage(source([]), 'trace', { cursor: 'bad' })).rejects.toMatchObject({ + code: 'INVALID_CURSOR', + }); + expect(tracePageRequestSchema.safeParse({ cursor: 'cursor', include: 'full' }).success).toBe(false); + expect(tracePageRequestSchema.safeParse({ spanIds: ['a'], depth: 2 }).success).toBe(false); + expect(tracePageRequestSchema.safeParse({ search: 'foo', depth: 2 }).success).toBe(false); + }); + it('can continue a maximum-size batch of multibyte identifiers', async () => { + const ids = Array.from({ length: 100 }, (_, i) => '界'.repeat(125) + String(i)); + const src = source(ids.map(id => span(id))); + const first = (await readTracePage(src, 'trace', { spanIds: ids, limit: 1 }))!; + expect(first.nextCursor!.length).toBeLessThanOrEqual(60000); + expect(Buffer.byteLength(JSON.stringify({ cursor: first.nextCursor }))).toBeLessThan(65536); + const second = await readTracePage(src, 'trace', { cursor: first.nextCursor! }); + expect(second!.nodes[0]!.spanId).toBe(ids[1]); + }); +}); + +describe('trace page request boundaries', () => { + it('accepts exactly 50000 topology rows and rejects the overflow sentinel', async () => { + const rows = Array.from({ length: 50000 }, (_, i) => span(String(i).padStart(5, '0'))); + const page = (await readTracePage(source(rows), 'trace', { limit: 1 }))!; + expect(page.nodes.map(node => node.spanId)).toEqual(['00000']); + expect(page.nextCursor).toBeTruthy(); + rows.push(span('50000')); + await expect(readTracePage(source(rows), 'trace', { limit: 1 })).rejects.toMatchObject({ + code: 'LIMIT_EXCEEDED', + }); + }); + + it.each([{ limit: 201 }, { maxBytes: 4194305 }])('rejects request budgets above the cap: %j', request => { + expect(tracePageRequestSchema.safeParse(request).success).toBe(false); + }); + it('accepts the maximum request budgets', () => { + expect(tracePageRequestSchema.safeParse({ limit: 200, maxBytes: 4194304 }).success).toBe(true); + }); + + it.each([true, false])('requires search when ancestors is %s, including in cursors', async ancestors => { + const src = source([span('a'), span('b', 'a')], ['b']); + expect(tracePageRequestSchema.safeParse({ ancestors }).success).toBe(false); + const page = (await readTracePage(src, 'trace', { limit: 1 }))!; + const cursor = JSON.parse(Buffer.from(page.nextCursor!, 'base64url').toString()); + cursor.selection.ancestors = ancestors; + await expect( + readTracePage(src, 'trace', { cursor: Buffer.from(JSON.stringify(cursor)).toString('base64url') }), + ).rejects.toMatchObject({ code: 'INVALID_CURSOR' }); + const search = (await readTracePage(src, 'trace', { search: 'error', ancestors }))!; + expect(search.nodes.map(node => node.spanId)).toEqual(ancestors ? ['a', 'b'] : ['b']); + expect(search.ancestorPaths).toBe(ancestors ? 'complete' : 'not-requested'); + }); + + it.each([{ limit: 1000 }, { maxBytes: 4194305 }, { spanIds: ['a', 'b'], search: 'error' }])( + 'revalidates selection in a forged cursor: %j', + async changes => { + const src = source([span('a'), span('b')]); + const page = (await readTracePage(src, 'trace', { spanIds: ['a', 'b'], limit: 1 }))!; + const cursor = JSON.parse(Buffer.from(page.nextCursor!, 'base64url').toString()); + Object.assign(cursor.selection, changes); + // Even a recomputed fingerprint cannot authorize invalid selection or budgets. + cursor.fingerprint = createHash('sha256') + .update(JSON.stringify([src.scopeKey, 'trace', cursor.selection])) + .digest('hex'); + await expect( + readTracePage(src, 'trace', { cursor: Buffer.from(JSON.stringify(cursor)).toString('base64url') }), + ).rejects.toMatchObject({ code: 'INVALID_CURSOR' }); + }, + ); + + it.each([0, -1, 1.5, 2, 3, 50001])('rejects a cursor offset outside the selection: %s', async offset => { + const src = source([span('a'), span('b')]); + const page = (await readTracePage(src, 'trace', { spanIds: ['a', 'b'], limit: 1 }))!; + const cursor = JSON.parse(Buffer.from(page.nextCursor!, 'base64url').toString()); + cursor.offset = offset; + await expect( + readTracePage(src, 'trace', { cursor: Buffer.from(JSON.stringify(cursor)).toString('base64url') }), + ).rejects.toMatchObject({ code: 'INVALID_CURSOR' }); + }); + + it('rejects non-base64url characters even when the decoder would ignore them', async () => { + const src = source([span('a'), span('b')]); + const page = (await readTracePage(src, 'trace', { limit: 1 }))!; + await expect(readTracePage(src, 'trace', { cursor: `${page.nextCursor!}\n` })).rejects.toMatchObject({ + code: 'INVALID_CURSOR', + }); + }); + + it('limits cursor text before decoding an otherwise valid JSON continuation', async () => { + const src = source([span('a'), span('b')]); + const page = (await readTracePage(src, 'trace', { limit: 1 }))!; + const json = Buffer.from(page.nextCursor!, 'base64url').toString(); + const cursor = Buffer.from(json + ' '.repeat(45001)).toString('base64url'); + expect(cursor.length).toBeGreaterThan(60000); + await expect(readTracePage(src, 'trace', { cursor })).rejects.toThrow(); + expect(tracePageRequestSchema.safeParse({ cursor: 'a'.repeat(60000) }).success).toBe(true); + expect(tracePageRequestSchema.safeParse({ cursor: 'a'.repeat(60001) }).success).toBe(false); + }); + + it('requires a restart if a selected span disappears during hydration', async () => { + const src = source([span('a'), span('b')]); + const readSpans = src.spans; + src.spans = async (...args) => (await readSpans(...args)).filter(row => row.spanId !== 'b'); + await expect(readTracePage(src, 'trace', {})).rejects.toMatchObject({ code: 'TRACE_CHANGED' }); + }); +}); + +it.each(['browse', 'hydrate', 'search'] as const)( + 'accounts for exact UTF-8 and JSON byte boundaries in %s pages', + async mode => { + const rows = [span('a', null, '界"\n'.repeat(4000)), span('b', 'a', '界"\n'.repeat(4000))]; + const src = source(rows, ['b']); + const selection = + mode === 'hydrate' ? { spanIds: ['missing"界', 'a', 'b'] } : mode === 'search' ? { search: 'error' } : {}; + const request = { ...selection, include: 'full' as const, maxBytes: 65536 }; + const sample = (await readTracePage(src, 'trace', request))!; + rows[0]!.input += 'x'.repeat(65536 - Buffer.byteLength(JSON.stringify(sample))); + const exact = (await readTracePage(src, 'trace', request))!; + expect(Buffer.byteLength(JSON.stringify(exact))).toBe(65536); + expect(exact.nodes.map(node => node.spanId)).toEqual(['a', 'b']); + expect(exact.nextCursor).toBeUndefined(); + + rows[0]!.input += 'x'; + const pages = await drain(src, (await readTracePage(src, 'trace', request))!); + expect(pages).toHaveLength(2); + expect(pages.flatMap(page => page.nodes.map(node => node.spanId))).toEqual(['a', 'b']); + expect(pages.flatMap(page => page.missingSpanIds)).toEqual(mode === 'hydrate' ? ['missing"界'] : []); + for (const page of pages) expect(Buffer.byteLength(JSON.stringify(page))).toBeLessThanOrEqual(65536); + if (mode === 'search') expect(pages.map(page => page.ancestorPaths)).toEqual(['continued', 'complete']); + }, +); + +it('reads each explicit ID only on its own page and survives unrelated arrivals', async () => { + const rows = Array.from({ length: 100 }, (_, i) => span(String(i), null, 'large payload')); + let reads = 0; + const src = source(rows); + src.spans = async (_, ids, projection) => { + expect(ids).toHaveLength(1); + expect(projection).toBe('full'); + reads += ids.length; + return rows.filter(row => ids.includes(row.spanId)); + }; + const first = (await readTracePage(src, 'trace', { + spanIds: rows.map(row => row.spanId), + limit: 1, + include: 'full', + }))!; + rows.push(span('unrelated')); + const pages = await drain(src, first); + expect(reads).toBe(100); + expect(pages.flatMap(page => page.nodes)).toHaveLength(100); +}); + +it('continues an anchored subtree through unrelated arrivals but rejects relevant changes', async () => { + const rows = [span('root'), span('a', 'root'), span('b', 'a'), span('other', 'root')]; + const src = source(rows); + const first = (await readTracePage(src, 'trace', { anchorSpanId: 'a', limit: 1 }))!; + rows.push(span('unrelated', 'other')); + expect((await readTracePage(src, 'trace', { cursor: first.nextCursor! }))!.nodes[0]!.spanId).toBe('b'); + rows.push(span('new-child', 'a')); + await expect(readTracePage(src, 'trace', { cursor: first.nextCursor! })).rejects.toMatchObject({ + code: 'TRACE_CHANGED', + }); +}); + +it('requests only topology columns then page summaries for structure browsing', async () => { + const rows = [span('a'), span('b')]; + const src = source(rows); + src.structure = async (_, limit) => { + expect(limit).toBe(50001); + return rows.map(({ traceId, spanId, parentSpanId, startedAt }) => ({ traceId, spanId, parentSpanId, startedAt })); + }; + src.spans = async (_, ids, include) => { + expect(ids).toEqual(['a']); + expect(include).toBe('structure'); + return rows.filter(row => ids.includes(row.spanId)); + }; + expect((await readTracePage(src, 'trace', { limit: 1 }))!.nodes[0]!.name).toBe('a'); +}); + +it('continues explicit IDs across a response byte boundary without skipping unread payloads', async () => { + const src = source([span('a', null, 'x'.repeat(40000)), span('b', null, 'y'.repeat(40000))]); + const pages = await drain( + src, + (await readTracePage(src, 'trace', { spanIds: ['absent', 'a', 'b'], include: 'full', maxBytes: 65536 }))!, + ); + expect(pages.flatMap(page => page.nodes.map(node => node.spanId))).toEqual(['a', 'b']); + expect(pages.flatMap(page => page.missingSpanIds)).toEqual(['absent']); +}); diff --git a/packages/core/src/storage/domains/observability/trace-page.ts b/packages/core/src/storage/domains/observability/trace-page.ts new file mode 100644 index 00000000000..ae79d2dcb31 --- /dev/null +++ b/packages/core/src/storage/domains/observability/trace-page.ts @@ -0,0 +1,467 @@ +import { createHash } from 'node:crypto'; +import { z } from 'zod/v4'; +import { spanRecordSchema, computeTraceStatus, TraceStatus } from './tracing'; +import type { SpanRecord } from './tracing'; + +// Bound serialized identities so every accepted ID batch fits in a continuation request. +export const tracePageIdSchema = z + .string() + .min(1) + .max(128) + .refine(value => Buffer.byteLength(JSON.stringify(value)) <= 384, 'Identifier exceeds the serialized byte limit'); +const id = tracePageIdSchema; +const selectionSchema = z + .object({ + anchorSpanId: id.optional(), + depth: z.number().int().min(0).max(32).optional().describe('Browse depth from the anchor or roots; defaults to 2.'), + spanIds: z.array(id).min(1).max(100).optional(), + search: z.string().trim().min(1).max(256).optional(), + ancestors: z.boolean().optional(), + include: z.enum(['structure', 'full']).default('structure'), + limit: z.number().int().min(1).max(200).default(100), + maxBytes: z.number().int().min(65536).max(4194304).default(1048576), + }) + .strict(); + +/** POST body for the getTracePage endpoint. Continuations cannot change selection. */ +export const tracePageRequestSchema = z.union([ + selectionSchema.superRefine((value, ctx) => { + if ( + value.spanIds && + (value.anchorSpanId || value.search || value.depth !== undefined || value.ancestors !== undefined) + ) { + ctx.addIssue({ code: 'custom', message: 'spanIds cannot be combined with browse or search selection' }); + } + if (value.search && (value.anchorSpanId || value.depth !== undefined)) { + ctx.addIssue({ code: 'custom', message: 'Search covers the entire trace; anchorSpanId is browse-only' }); + } + if (value.ancestors !== undefined && !value.search) { + ctx.addIssue({ code: 'custom', message: 'ancestors requires search' }); + } + }), + z.object({ cursor: z.string().min(1).max(60000) }).strict(), +]); +export type TracePageRequest = z.input; + +// Trace context belongs to actual roots, not the anchor of an arbitrary subtree. +const tracePageRootContextSchema = spanRecordSchema + .pick({ + experimentId: true, + userId: true, + organizationId: true, + resourceId: true, + runId: true, + sessionId: true, + threadId: true, + requestId: true, + environment: true, + source: true, + serviceName: true, + tags: true, + }) + .extend({ projectId: z.string().nullish() }); + +/** Execution diagnostics and previews; full payloads and metadata remain in details. */ +export const tracePageNodeSchema = spanRecordSchema + .pick({ + traceId: true, + spanId: true, + parentSpanId: true, + name: true, + spanType: true, + isEvent: true, + startedAt: true, + endedAt: true, + entityType: true, + entityId: true, + entityName: true, + model: true, + provider: true, + outcome: true, + stopReason: true, + stopReasonContext: true, + errorCount: true, + externalParentSpanId: true, + resumedFromSpanId: true, + timeToFirstChunkMs: true, + inputPreview: true, + outputPreview: true, + errorPreview: true, + timeToFirstTokenMs: true, + }) + .extend({ + ...tracePageRootContextSchema.shape, + status: z.nativeEnum(TraceStatus), + childCount: z.number().int().nonnegative().nullable(), + match: z.boolean(), + parentState: z.enum(['root', 'available', 'unavailable', 'not-requested']), + details: spanRecordSchema.omit({ scope: true, links: true }).optional(), + }); +export const tracePageResponseSchema = z.object({ + traceId: z.string(), + nodes: z.array(tracePageNodeSchema), + missingSpanIds: z.array(z.string()), + nextCursor: z.string().optional(), + ancestorPaths: z.enum(['not-requested', 'continued', 'complete', 'unavailable']), +}); +export type TracePageResponse = z.infer; +export type TracePageNode = z.infer; +export type TracePageStructure = Pick; +export type TracePageSummary = Pick< + SpanRecord, + | 'traceId' + | 'spanId' + | 'parentSpanId' + | 'startedAt' + | 'name' + | 'spanType' + | 'isEvent' + | 'endedAt' + | 'entityType' + | 'entityId' + | 'entityName' + | 'model' + | 'provider' + | 'outcome' + | 'stopReason' + | 'stopReasonContext' + | 'errorCount' + | 'externalParentSpanId' + | 'resumedFromSpanId' + | 'timeToFirstChunkMs' + | 'inputPreview' + | 'outputPreview' + | 'errorPreview' + | 'timeToFirstTokenMs' +> & + z.infer & { error?: unknown }; + +export class TracePageError extends Error { + constructor( + public readonly code: + | 'INVALID_REQUEST' + | 'INVALID_CURSOR' + | 'TRACE_CHANGED' + | 'UNSUPPORTED' + | 'LIMIT_EXCEEDED' + | 'INVALID_TOPOLOGY' + | 'PAYLOAD_TOO_LARGE', + message: string, + ) { + super(message); + this.name = 'TracePageError'; + } +} + +/** + * @internal Experimental Platform integration; not a supported OSS storage-adapter contract. + * All reads must independently enforce trusted scope. A cursor is never authorization. + * Cursors are unsigned base64url JSON, not integrity-protected tokens. Their fingerprint + * detects selection changes, not forgery; decoded requests must still be validated. + */ +export interface TracePageSource { + scopeKey: string; + /** Return at most limit topology rows; the extra row detects overflow. */ + structure(traceId: string, limit: number): Promise; + /** + * Read only the selected IDs, excluding payload fields for structure projection. + * Include a non-null `error` indicator for failed spans so status is computed correctly. + * Full projection returns span details including the actual error payload; scope and links are omitted. + */ + spans(traceId: string, spanIds: string[], include: 'structure' | 'full'): Promise; + /** Complete matching identities within this trace; fail rather than truncate. */ + search?(traceId: string, text: string): Promise; +} + +const hash = (value: unknown) => createHash('sha256').update(JSON.stringify(value)).digest('hex'); +const cursorSchema = z + .object({ + version: z.literal(2), + selection: selectionSchema, + fingerprint: z.string().regex(/^[a-f0-9]{64}$/), + offset: z.number().int().min(1).max(50000), + }) + .strict(); + +/** + * @internal Experimental Platform reader; not a supported OSS storage-adapter contract. + * Bounded wire pages over a capped topology read; this is not O(page size) database work. + */ +export async function readTracePage( + source: TracePageSource, + traceId: string, + request: TracePageRequest, +): Promise { + if (!id.safeParse(traceId).success) throw new TracePageError('INVALID_REQUEST', 'Invalid trace identifier'); + const parsed = tracePageRequestSchema.parse(request); + let continuation: z.infer | undefined; + if ('cursor' in parsed) { + try { + if (!/^[A-Za-z0-9_-]+$/.test(parsed.cursor)) throw new Error(); + continuation = cursorSchema.parse(JSON.parse(Buffer.from(parsed.cursor, 'base64url').toString('utf8'))); + tracePageRequestSchema.parse(continuation.selection); + } catch { + throw new TracePageError('INVALID_CURSOR', 'Invalid trace continuation'); + } + } + const selection = continuation?.selection ?? ('cursor' in parsed ? undefined : parsed); + if (!selection) throw new TracePageError('INVALID_CURSOR', 'Invalid trace continuation'); + if (selection.search && !source.search) + throw new TracePageError('UNSUPPORTED', 'Indexed in-trace search is unavailable'); + const offset = continuation?.offset ?? 0; + const renderPage = async ( + ids: string[], + fingerprint: string, + topology?: { + nodes: Map; + children: Map; + matches: Set; + missingSpanIds: string[]; + unavailableAncestors: boolean; + }, + ): Promise => { + // Explicit-ID cursors depend on the requested positions, never on fetched membership. + if (continuation && continuation.fingerprint !== fingerprint) + throw new TracePageError('TRACE_CHANGED', 'Selection or request scope changed; restart this selection'); + if (continuation && offset >= ids.length) + throw new TracePageError('INVALID_CURSOR', 'Continuation is outside the selection'); + const pageIds = ids.slice(offset, offset + selection.limit); + const records = pageIds.length ? await source.spans(traceId, pageIds, selection.include) : []; + const recordsById = new Map(); + for (const record of records) { + if ( + record.traceId !== traceId || + !pageIds.includes(record.spanId) || + recordsById.has(record.spanId) || + !Number.isFinite(record.startedAt.getTime()) + ) + throw new TracePageError('INVALID_TOPOLOGY', 'Page read returned conflicting identities or timestamps'); + const node = topology?.nodes.get(record.spanId); + if ( + node && + ((node.parentSpanId ?? null) !== (record.parentSpanId ?? null) || + node.startedAt.getTime() !== record.startedAt.getTime()) + ) + throw new TracePageError('TRACE_CHANGED', 'Selected structure changed during the read'); + recordsById.set(record.spanId, record); + } + const result: TracePageResponse = { + traceId, + nodes: [], + missingSpanIds: [...(topology?.missingSpanIds ?? [])], + ancestorPaths: 'not-requested', + }; + let nodeBytes = 0; + let missingIdBytes = result.missingSpanIds.reduce( + (bytes, spanId) => bytes + Buffer.byteLength(JSON.stringify(spanId)), + 0, + ); + // Serialize each selected payload once. The small envelope changes as the cursor + // advances; empty arrays already account for brackets, with commas added below. + const responseBytes = () => + Buffer.byteLength(JSON.stringify({ ...result, nodes: [], missingSpanIds: [] })) + + nodeBytes + + Math.max(0, result.nodes.length - 1) + + missingIdBytes + + Math.max(0, result.missingSpanIds.length - 1); + let processed = 0; + const updateContinuation = () => { + const nextOffset = offset + processed; + if (nextOffset < ids.length) + result.nextCursor = Buffer.from( + JSON.stringify({ + version: 2, + selection, + fingerprint, + offset: nextOffset, + }), + ).toString('base64url'); + else delete result.nextCursor; + if (selection.search && selection.ancestors !== false) + result.ancestorPaths = result.nextCursor + ? 'continued' + : topology?.unavailableAncestors + ? 'unavailable' + : 'complete'; + }; + for (const spanId of pageIds) { + const record = recordsById.get(spanId); + let addedBytes: number; + if (!record) { + if (topology) throw new TracePageError('TRACE_CHANGED', 'Selected spans disappeared; restart this selection'); + result.missingSpanIds.push(spanId); + addedBytes = Buffer.byteLength(JSON.stringify(spanId)); + missingIdBytes += addedBytes; + } else { + const { traceId, parentSpanId, name, spanType, isEvent, startedAt, endedAt, entityType, entityId, entityName } = + record; + const details = selection.include === 'full' ? { ...(record as SpanRecord) } : undefined; + if (details) { + delete details.scope; + delete details.links; + } + const node: TracePageNode = { + traceId, + spanId, + parentSpanId, + name, + spanType, + isEvent, + startedAt, + endedAt, + entityType, + entityId, + entityName, + model: record.model, + provider: record.provider, + outcome: record.outcome, + stopReason: record.stopReason, + stopReasonContext: record.stopReasonContext, + errorCount: record.errorCount, + externalParentSpanId: record.externalParentSpanId, + resumedFromSpanId: record.resumedFromSpanId, + timeToFirstChunkMs: record.timeToFirstChunkMs, + inputPreview: record.inputPreview, + outputPreview: record.outputPreview, + errorPreview: record.errorPreview, + timeToFirstTokenMs: record.timeToFirstTokenMs, + ...(!parentSpanId ? tracePageRootContextSchema.parse(record) : {}), + status: computeTraceStatus(record), + childCount: topology ? (topology.children.get(spanId)?.length ?? 0) : null, + match: topology?.matches.has(spanId) ?? false, + parentState: !parentSpanId + ? 'root' + : !topology + ? 'not-requested' + : topology.nodes.has(parentSpanId) + ? 'available' + : 'unavailable', + ...(details ? { details } : {}), + }; + result.nodes.push(node); + addedBytes = Buffer.byteLength(JSON.stringify(node)); + nodeBytes += addedBytes; + } + processed++; + updateContinuation(); + if (responseBytes() > selection.maxBytes) { + if (record) { + result.nodes.pop(); + nodeBytes -= addedBytes; + } else { + result.missingSpanIds.pop(); + missingIdBytes -= addedBytes; + } + processed--; + updateContinuation(); + if (!processed) + throw new TracePageError( + 'PAYLOAD_TOO_LARGE', + `Span '${spanId}' exceeds maxBytes; request structure or use the single-span endpoint`, + ); + break; + } + } + updateContinuation(); + if (responseBytes() > selection.maxBytes) + throw new TracePageError('LIMIT_EXCEEDED', 'Trace response metadata exceeds maxBytes'); + return result; + }; + + if (selection.spanIds) { + const ids = [...new Set(selection.spanIds)]; + const fingerprint = hash([source.scopeKey, traceId, selection]); + return renderPage(ids, fingerprint); + } + const structure = await source.structure(traceId, 50001); + if (!structure) return null; + if (structure.length > 50000) throw new TracePageError('LIMIT_EXCEEDED', 'Trace topology exceeds 50000 spans'); + const nodes = new Map(); + for (const node of structure) { + if (node.traceId !== traceId || nodes.has(node.spanId) || !Number.isFinite(node.startedAt.getTime())) { + throw new TracePageError('INVALID_TOPOLOGY', 'Trace contains conflicting identities or invalid timestamps'); + } + nodes.set(node.spanId, node); + } + const visited = new Set(); + for (const node of structure) { + const path = new Set(); + let current: TracePageStructure | undefined = node; + while (current && !visited.has(current.spanId)) { + if (path.has(current.spanId)) throw new TracePageError('INVALID_TOPOLOGY', 'Trace contains a parent cycle'); + path.add(current.spanId); + current = current.parentSpanId ? nodes.get(current.parentSpanId) : undefined; + } + for (const spanId of path) visited.add(spanId); + } + const sorted = [...nodes.values()].sort( + (a, b) => a.startedAt.getTime() - b.startedAt.getTime() || (a.spanId < b.spanId ? -1 : a.spanId > b.spanId ? 1 : 0), + ); + const children = new Map(); + const roots: TracePageStructure[] = []; + for (const node of sorted) { + if (node.parentSpanId && nodes.has(node.parentSpanId)) { + const siblings = children.get(node.parentSpanId) ?? []; + siblings.push(node); + children.set(node.parentSpanId, siblings); + } else roots.push(node); + } + const matches = new Set(selection.search ? await source.search!(traceId, selection.search) : []); + if ([...matches].some(spanId => !nodes.has(spanId))) + throw new TracePageError('TRACE_CHANGED', 'Search membership changed during the read; restart this selection'); + const selected: TracePageStructure[] = []; + const missingSpanIds: string[] = []; + if (selection.search) { + const emitted = new Set(); + for (const match of sorted.filter(node => matches.has(node.spanId))) { + const path: TracePageStructure[] = []; + let current: TracePageStructure | undefined = match; + while (current && !emitted.has(current.spanId)) { + path.push(current); + current = selection.ancestors !== false && current.parentSpanId ? nodes.get(current.parentSpanId) : undefined; + } + for (const node of path.reverse()) { + emitted.add(node.spanId); + selected.push(node); + } + } + } else { + const anchors = selection.anchorSpanId + ? [nodes.get(selection.anchorSpanId)].filter((node): node is TracePageStructure => !!node) + : roots; + if (selection.anchorSpanId && !anchors.length) missingSpanIds.push(selection.anchorSpanId); + const queue = anchors.map(node => ({ node, depth: 0 })); + for (let i = 0; i < queue.length; i++) { + const entry = queue[i]!; + selected.push(entry.node); + if (entry.depth < (selection.depth ?? 2)) { + for (const child of children.get(entry.node.spanId) ?? []) queue.push({ node: child, depth: entry.depth + 1 }); + } + } + } + // Only changes affecting this selection invalidate continuation, not unrelated branches. + const fingerprint = hash([ + source.scopeKey, + traceId, + selection, + selected.map(node => [ + node.spanId, + node.parentSpanId ?? null, + node.startedAt.toISOString(), + children.get(node.spanId)?.length ?? 0, + !!node.parentSpanId && nodes.has(node.parentSpanId), + matches.has(node.spanId), + ]), + ]); + return renderPage( + selected.map(node => node.spanId), + fingerprint, + { + nodes, + children, + matches, + missingSpanIds, + unavailableAncestors: selected.some(node => node.parentSpanId && !nodes.has(node.parentSpanId)), + }, + ); +}