diff --git a/docs/architecture/decisions/VD-07-diagnostics-and-telemetry-exporter.md b/docs/architecture/decisions/VD-07-diagnostics-and-telemetry-exporter.md index b9c30ac6..b7c2e022 100644 --- a/docs/architecture/decisions/VD-07-diagnostics-and-telemetry-exporter.md +++ b/docs/architecture/decisions/VD-07-diagnostics-and-telemetry-exporter.md @@ -72,6 +72,11 @@ vendor 결정 전에는 안전한 기본값이 아니다. 아니거나 1 미만이거나 문서화된 ceiling(각각 `MAX_TELEMETRY_QUEUE`, `MAX_DIAGNOSTIC_ENTRIES` = 10,000)을 넘으면 `TypeError`로 거절한다. NaN/Infinity가 조용히 eviction을 비활성화하는 경로를 남기지 않는다. +7-5. (2026-09-25) 두 telemetry port는 collector 하나로 보낸다 + (`src/adapters/telemetry/telemetry-collector.ts`). collector는 본문을 60KiB 아래로 + 나누고, 진행 중인 keepalive 본문 합이 64KiB를 넘으면 그 부분은 keepalive 없이 + 보낸다(03-05). 조합 루트가 release manifest의 `buildId`·`releaseId`를 넘기면 모든 + 이벤트에 `build_id`·`release_id`를 붙인다(13-11, `src/bootstrap/runtime-adapters.ts`). 8. diagnostics와 telemetry failure는 제품 흐름, HTTP 결과, route transition, storage/cache fallback과 React error surface를 바꾸지 않는다. 9. mount 전 bootstrap failure는 안전한 build/config/error kind만 별도 evidence로 diff --git a/src/adapters/telemetry/telemetry-collector.ts b/src/adapters/telemetry/telemetry-collector.ts index 4d243463..d3bb2300 100644 --- a/src/adapters/telemetry/telemetry-collector.ts +++ b/src/adapters/telemetry/telemetry-collector.ts @@ -37,6 +37,11 @@ export type TelemetryCollectorOptions = Readonly<{ /** Monotonic clock for the send-rate window (default `performance.now`). */ now?: () => number; lifecycle?: Pick; + /** + * 13-11. Stamped on every event as `build_id` and `release_id`, so a + * failure rate can be split by release while old and new tabs coexist. + */ + release?: Readonly<{ buildId: string; releaseId: string }>; }>; export const DEFAULT_TELEMETRY_SENDS_PER_MINUTE = 20; @@ -81,8 +86,12 @@ function splitBodies(events: readonly unknown[]): string[] { export function createTelemetryCollector( options: TelemetryCollectorOptions, ): TelemetryCollector { - const { endpoint } = options; + const { endpoint, release } = options; const fetcher = options.fetcher ?? fetch; + const stamp = (event: unknown): unknown => + release && event !== null && typeof event === "object" && !Array.isArray(event) + ? { ...event, build_id: release.buildId, release_id: release.releaseId } + : event; const timeoutMs = assertBoundedCapacity( options.timeoutMs ?? DEFAULT_TELEMETRY_TIMEOUT_MS, MAX_TIMEOUT_MS, @@ -145,7 +154,9 @@ export function createTelemetryCollector( signal?: AbortSignal, ): Promise { // Sent together so a page-exit flush dispatches every part at once. - await Promise.all(splitBodies(events).map((body) => send(body, signal))); + await Promise.all( + splitBodies(events.map(stamp)).map((body) => send(body, signal)), + ); } return Object.freeze({ diff --git a/src/bootstrap/runtime-adapters.ts b/src/bootstrap/runtime-adapters.ts index 8e046691..22306b3d 100644 --- a/src/bootstrap/runtime-adapters.ts +++ b/src/bootstrap/runtime-adapters.ts @@ -319,6 +319,10 @@ export async function createRuntimeAdapters( ? createTelemetryCollector({ endpoint: config.TELEMETRY_ENDPOINT, ...(context.fetcher === undefined ? {} : { fetcher: context.fetcher }), + release: { + buildId: context.release.buildId, + releaseId: context.release.releaseId, + }, }) : undefined; const telemetry = createTelemetryAdapter({ diff --git a/tests/unit/runtime-adapters.test.ts b/tests/unit/runtime-adapters.test.ts index 2553a34c..c0fb88d2 100644 --- a/tests/unit/runtime-adapters.test.ts +++ b/tests/unit/runtime-adapters.test.ts @@ -174,6 +174,44 @@ describe("runtime adapter composition", () => { expect(fetcher).not.toHaveBeenCalled(); }); + it("sends telemetry stamped with the release identity (13-11)", async () => { + const bodies: { events: Record[] }[] = []; + const fetcher = vi.fn(async (_url: RequestInfo | URL, init?: RequestInit) => { + if (String(_url) === "https://telemetry.test/events") { + bodies.push(JSON.parse(String(init?.body))); + } + return new Response(null, { status: 204 }); + }); + const adapters = await createRuntimeAdapters({ + runtime: { + ...runtime, + config: { + ...runtime.config, + TELEMETRY_ENABLED: true, + TELEMETRY_ENDPOINT: "https://telemetry.test/events", + }, + } as Runtime, + release, + host: {}, + fetcher: fetcher as unknown as typeof fetch, + }); + + adapters.outputPorts.telemetry.emit("api.request.failed", { + error_kind: "SERVER_FAILURE", + http_status_group: "5xx", + attempt_count_bucket: "1", + route_id: "TEST_ROUTE", + }); + await adapters.outputPorts.telemetry.flush(); + + expect(bodies[0]?.events[0]).toMatchObject({ + eventName: "api.request.failed", + build_id: "build-a", + release_id: "release-a", + }); + adapters.infrastructure.dispose(); + }); + it("replaces the QueryClient and coordinator for each session generation", async () => { const adapters = await createRuntimeAdapters({ runtime, release, host: {} }); const previousClient = adapters.infrastructure.queryClient; diff --git a/tests/unit/telemetry.test.ts b/tests/unit/telemetry.test.ts index 04d3a062..c775767d 100644 --- a/tests/unit/telemetry.test.ts +++ b/tests/unit/telemetry.test.ts @@ -594,6 +594,55 @@ describe("one collector transport for both telemetry ports (Q-6.9-4)", () => { }); }); +/** + * 13-11. Failures must be attributable to a release while old and new tabs + * coexist, so every event the collector sends carries both identities. + */ +describe("collector release identity (13-11)", () => { + it("stamps build_id and release_id on every event of both ports", async () => { + const bodies: { events: Record[] }[] = []; + const fetcher = vi.fn(async (_url: RequestInfo | URL, init?: RequestInit) => { + bodies.push(JSON.parse(String(init?.body))); + return new Response(null, { status: 204 }); + }); + const collector = createTelemetryCollector({ + endpoint: "https://telemetry.test/events", + fetcher: fetcher as unknown as typeof fetch, + release: { buildId: "build-a", releaseId: "release-a" }, + }); + const adapter = createTelemetryAdapter({ + enabled: true, + endpoint: "https://telemetry.test/events", + schedule: () => {}, + collector, + }); + adapter.emit("api.request.failed", validAttributes); + await adapter.flush(); + await createFetchTelemetryTransport({ + endpoint: "https://telemetry.test/events", + collector, + }).send([ + { + event: { kind: "catalog.load.failed", severity: "error", featureId: "catalog" }, + fingerprint: "fp-1", + occurrences: 1, + }, + ]); + // A split batch keeps the identity on every part. + await collector.post( + Array.from({ length: 70 }, (_, index) => ({ index, padding: "x".repeat(1_000) })), + ); + + const events = bodies.flatMap((body) => body.events); + expect(bodies.length).toBeGreaterThan(3); + expect(events).toHaveLength(72); + for (const sent of events) { + expect(sent).toMatchObject({ build_id: "build-a", release_id: "release-a" }); + } + adapter.dispose(); + }); +}); + /** * 03-05. Fetch fails every keepalive request once the in-flight keepalive * bodies exceed 64KiB, so a large queue must be split and the collector must