From a328776bf2d9e974c4635c5d0e8a3c4fa8febcae Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 24 Sep 2026 13:15:40 +0900 Subject: [PATCH] fix(telemetry): send both telemetry ports through one collector transport (Q-6.9-4) The application port (best-effort-telemetry) and the feature port (feature-telemetry pipeline) each posted to TELEMETRY_ENDPOINT on their own: 20+20 sends per minute, cookies on the application side, no pagehide flush or dispose abort on the feature side, and no deadline on any fetch, so a hung collector held activeFlush forever (6.3-10). New src/adapters/telemetry/telemetry-collector.ts is the one transport: shared send-rate window (createTelemetrySendRate, now in the platform pipeline and injectable via `sendRate`), credentials "omit", cache "no-store", a per-request deadline through the kernel createAbortableOperation, and one pagehide fan-out. runtime-adapters builds one collector and passes it to both ports. Body projections are unchanged and pinned by characterization tests first. Verified: new tests in tests/unit/telemetry.test.ts (5 RED before wiring: credentials/cache, hung collector timeout, shared rate, feature pagehide flush, feature dispose abort); all gates pass except the known tests/unit/removal-fixture.test.ts (artifacts/ absent); check:adapter-inventory 137/137; FE-RB-004 drill PASS. Co-Authored-By: Claude Opus 5.5 --- docs/reviews/adapters/01-network-and-state.md | 1 + docs/reviews/adapters/INVENTORY.md | 27 +- .../telemetry/best-effort-telemetry.ts | 79 +++--- src/adapters/telemetry/feature-telemetry.ts | 79 ++++-- src/adapters/telemetry/index.ts | 6 + src/adapters/telemetry/telemetry-collector.ts | 123 +++++++++ src/bootstrap/runtime-adapters.ts | 12 + src/platform/telemetry/telemetry-pipeline.ts | 62 +++-- tests/unit/telemetry.test.ts | 237 ++++++++++++++++++ 9 files changed, 528 insertions(+), 98 deletions(-) create mode 100644 src/adapters/telemetry/telemetry-collector.ts diff --git a/docs/reviews/adapters/01-network-and-state.md b/docs/reviews/adapters/01-network-and-state.md index 0dea760b..1938c688 100644 --- a/docs/reviews/adapters/01-network-and-state.md +++ b/docs/reviews/adapters/01-network-and-state.md @@ -81,6 +81,7 @@ All 24 files below were read in full. | src/adapters/query-cache/tanstack-query-cache.ts | Creates QueryClient defaults and QueryCachePort read/write/invalidate adapter with diagnostics | TanStack Query, QueryCachePort, errors/diagnostics | Keep retry disabled and clone-on-write. Clone-on-read is an optional port-semantics decision, not a confirmed production defect. | | src/adapters/telemetry/best-effort-telemetry.ts | Allowlisted bounded oldest-drop telemetry queue, scheduled/pagehide flush, sink isolation and evidence | TelemetryPort, telemetry/diagnostic contracts, bootstrap | Add terminal lifecycle state, joined flush promise and in-flight abort; ensure runtime composition disposes it. | | src/adapters/telemetry/feature-telemetry.ts | Feature TelemetryPort adapter over the platform telemetry pipeline; fetch transport to the collector endpoint | platform/telemetry pipeline; TelemetryPort; bootstrap | Keep. Registered 2026-09-24 (added in 6f6c48e without a ledger row); shares the collector with best-effort-telemetry (review 6.9-4). | +| src/adapters/telemetry/telemetry-collector.ts | The one collector transport behind both telemetry ports: shared send-rate window, `credentials: "omit"`, `cache: "no-store"`, per-request deadline through the kernel abort primitive, one `pagehide` fan-out | platform/telemetry send rate; adapters/platform abort and capacity kernel; bootstrap | Keep. Added 2026-09-24 for review 6.9-4 / 6.3-10: a hung collector no longer stalls later flushes, and the two ports no longer send 20+20 per minute. | ## 4. Traced boundary inventory diff --git a/docs/reviews/adapters/INVENTORY.md b/docs/reviews/adapters/INVENTORY.md index f574a5d3..d4829486 100644 --- a/docs/reviews/adapters/INVENTORY.md +++ b/docs/reviews/adapters/INVENTORY.md @@ -141,18 +141,19 @@ | 131 | `src/adapters/telemetry/best-effort-telemetry.ts` | [Network/state](./01-network-and-state.md) | | 132 | `src/adapters/telemetry/feature-telemetry.ts` | [Network/state](./01-network-and-state.md) | | 133 | `src/adapters/telemetry/index.ts` | [Network/state](./01-network-and-state.md) | -| 134 | `src/adapters/web-push/codec-primitives.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 135 | `src/adapters/web-push/inbound/notification-click-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 136 | `src/adapters/web-push/inbound/push-event-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 137 | `src/adapters/web-push/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 138 | `src/adapters/web-push/notification-registry.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 139 | `src/adapters/web-push/push-association-fence-store.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 140 | `src/adapters/web-push/push-codec.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 141 | `src/adapters/web-push/push-registration-gateway.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 142 | `src/adapters/web-push/push-subscription-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 143 | `src/adapters/web-push/runtime-support.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 144 | `src/adapters/web-push/service-worker-runtime.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 145 | `src/adapters/web-push/service-worker-scope-host.ts` | [Worker/push](./05-service-worker-and-web-push.md) | +| 134 | `src/adapters/telemetry/telemetry-collector.ts` | [Network/state](./01-network-and-state.md) | +| 135 | `src/adapters/web-push/codec-primitives.ts` | [Worker/push](./05-service-worker-and-web-push.md) | +| 136 | `src/adapters/web-push/inbound/notification-click-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) | +| 137 | `src/adapters/web-push/inbound/push-event-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) | +| 138 | `src/adapters/web-push/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) | +| 139 | `src/adapters/web-push/notification-registry.ts` | [Worker/push](./05-service-worker-and-web-push.md) | +| 140 | `src/adapters/web-push/push-association-fence-store.ts` | [Worker/push](./05-service-worker-and-web-push.md) | +| 141 | `src/adapters/web-push/push-codec.ts` | [Worker/push](./05-service-worker-and-web-push.md) | +| 142 | `src/adapters/web-push/push-registration-gateway.ts` | [Worker/push](./05-service-worker-and-web-push.md) | +| 143 | `src/adapters/web-push/push-subscription-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) | +| 144 | `src/adapters/web-push/runtime-support.ts` | [Worker/push](./05-service-worker-and-web-push.md) | +| 145 | `src/adapters/web-push/service-worker-runtime.ts` | [Worker/push](./05-service-worker-and-web-push.md) | +| 146 | `src/adapters/web-push/service-worker-scope-host.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -합계: **145/145**. 새 adapter 파일이 추가되면 이 ledger와 해당 상세 리뷰 inventory를 같은 변경에서 갱신한다. +합계: **146/146**. 새 adapter 파일이 추가되면 이 ledger와 해당 상세 리뷰 inventory를 같은 변경에서 갱신한다. diff --git a/src/adapters/telemetry/best-effort-telemetry.ts b/src/adapters/telemetry/best-effort-telemetry.ts index 63027b44..0e6d66de 100644 --- a/src/adapters/telemetry/best-effort-telemetry.ts +++ b/src/adapters/telemetry/best-effort-telemetry.ts @@ -6,6 +6,10 @@ import type { } from "../../contracts/telemetry.ts"; import type { TelemetryPort } from "../../application/ports/telemetry-port.ts"; import { assertBoundedCapacity } from "../platform/bounded-capacity.ts"; +import { + createTelemetryCollector, + type TelemetryCollector, +} from "./telemetry-collector.ts"; export type TelemetryAdapter = TelemetryPort & Readonly<{ @@ -36,10 +40,14 @@ export type TelemetryAdapterOptions = Readonly<{ monotonicNow?: () => number; setTimer?: (callback: () => void, ms: number) => unknown; clearTimer?: (handle: unknown) => void; + /** + * Q-6.9-4. The collector transport shared with feature telemetry. When set, + * it owns `fetcher`, `lifecycle`, `maxSendsPerMinute` and `monotonicNow`. + */ + collector?: TelemetryCollector; }>; -export const DEFAULT_TELEMETRY_SENDS_PER_MINUTE = 20; -const SEND_WINDOW_MS = 60_000; +export { DEFAULT_TELEMETRY_SENDS_PER_MINUTE } from "./telemetry-collector.ts"; export const noOpTelemetry: TelemetryAdapter = Object.freeze({ emit: () => {}, @@ -67,27 +75,28 @@ export function createTelemetryAdapter( return noOpTelemetry; } - const endpoint = options.endpoint; - const fetcher = options.fetcher ?? fetch; const maxQueue = assertBoundedCapacity( options.maxQueue ?? 100, MAX_TELEMETRY_QUEUE, "telemetry maxQueue", ); const schedule = options.schedule ?? queueMicrotask; - const maxSendsPerMinute = assertBoundedCapacity( - options.maxSendsPerMinute ?? DEFAULT_TELEMETRY_SENDS_PER_MINUTE, - MAX_TELEMETRY_QUEUE, - "telemetry maxSendsPerMinute", - ); - const monotonicNow = options.monotonicNow ?? (() => performance.now()); + const collector = + options.collector ?? + createTelemetryCollector({ + endpoint: options.endpoint, + ...(options.fetcher === undefined ? {} : { fetcher: options.fetcher }), + ...(options.maxSendsPerMinute === undefined + ? {} + : { maxSendsPerMinute: options.maxSendsPerMinute }), + ...(options.monotonicNow === undefined ? {} : { now: options.monotonicNow }), + ...(options.lifecycle === undefined ? {} : { lifecycle: options.lifecycle }), + }); const setTimer = options.setTimer ?? ((callback: () => void, ms: number) => setTimeout(callback, ms)); const clearTimer = options.clearTimer ?? ((handle: unknown) => clearTimeout(handle as ReturnType)); - /** Send instants inside the current window; never longer than the limit. */ - const sendTimes: number[] = []; let rateTimer: unknown = null; const queue: TelemetryEvent[] = []; let lifecycleState: TelemetryLifecycle = "ACTIVE"; @@ -99,12 +108,6 @@ export function createTelemetryAdapter( let dropped = 0; const dropReasons = new Map(); let lastDeliveryEvidence: TelemetryEvent | null = null; - const lifecycle = - options.lifecycle ?? - (typeof globalThis.addEventListener === "function" && - typeof globalThis.removeEventListener === "function" - ? globalThis - : undefined); function recordDrop(reason: string, count = 1): void { const safeReason = @@ -173,16 +176,8 @@ export function createTelemetryAdapter( scheduleFlush(); } - function rateAllows(at: number): boolean { - while (sendTimes.length > 0 && at - (sendTimes[0] as number) >= SEND_WINDOW_MS) { - sendTimes.shift(); - } - return sendTimes.length < maxSendsPerMinute; - } - - function armRateTimer(at: number): void { + function armRateTimer(reopenIn: number): void { if (rateTimer !== null || lifecycleState === "DISPOSED") return; - const reopenIn = Math.max(1, (sendTimes[0] ?? at) + SEND_WINDOW_MS - at); rateTimer = setTimer(() => { rateTimer = null; void flush(); @@ -198,31 +193,18 @@ export function createTelemetryAdapter( if (lifecycleState === "DISPOSED" || queue.length === 0) { return Promise.resolve(); } - const at = monotonicNow(); - if (!rateAllows(at)) { - if (!bypassRate) { - armRateTimer(at); - return Promise.resolve(); - } + const reopenIn = collector.sendRate.take(bypassRate); + if (reopenIn > 0) { + armRateTimer(reopenIn); + return Promise.resolve(); } - sendTimes.push(at); - if (sendTimes.length > maxSendsPerMinute) sendTimes.shift(); const generation = scheduleGeneration; const run = async () => { const batch = queue.splice(0, queue.length); const controller = new AbortController(); activeSink = controller; try { - const response = await fetcher(endpoint, { - method: "POST", - headers: { "Content-Type": "application/json" }, - body: JSON.stringify({ events: batch }), - keepalive: true, - signal: controller.signal, - }); - // A sink that ignored the abort must not update post-dispose state. - if (generation !== scheduleGeneration) return; - if (!response.ok) recordDrop("sink-failure", batch.length); + await collector.post(batch, controller.signal); } catch { if (generation !== scheduleGeneration) return; recordDrop("sink-failure", batch.length); @@ -239,10 +221,9 @@ export function createTelemetryAdapter( } // Page exit is the last chance to deliver: it may exceed the window once. - const flushBeforePageExit = () => { + const stopPageExitFlush = collector.onPageExit(() => { void flush(true); - }; - lifecycle?.addEventListener("pagehide", flushBeforePageExit); + }); /** * N-04. Terminal disposal: one state transition, no further admission, no @@ -253,7 +234,7 @@ export function createTelemetryAdapter( lifecycleState = "DISPOSED"; scheduleGeneration += 1; scheduled = false; - lifecycle?.removeEventListener("pagehide", flushBeforePageExit); + stopPageExitFlush(); if (rateTimer !== null) clearTimer(rateTimer); rateTimer = null; queue.length = 0; diff --git a/src/adapters/telemetry/feature-telemetry.ts b/src/adapters/telemetry/feature-telemetry.ts index 2b242e9f..f4a7a603 100644 --- a/src/adapters/telemetry/feature-telemetry.ts +++ b/src/adapters/telemetry/feature-telemetry.ts @@ -6,6 +6,10 @@ import { type TelemetryPipelineBudget, type TelemetryTransport, } from "../../platform/telemetry/telemetry-pipeline.ts"; +import { + createTelemetryCollector, + type TelemetryCollector, +} from "./telemetry-collector.ts"; /** * Spec §24–§27. Adapter side of the provider-neutral feature telemetry port. @@ -15,26 +19,31 @@ import { * transport here, never in feature code. */ export function createFetchTelemetryTransport( - options: Readonly<{ endpoint: string; fetcher?: typeof fetch }>, + options: Readonly<{ + endpoint: string; + fetcher?: typeof fetch; + /** Q-6.9-4. Posts through this shared collector instead of a private one. */ + collector?: TelemetryCollector; + /** Aborts in-flight batches (feature telemetry disposal). */ + signal?: AbortSignal; + }>, ): TelemetryTransport { - const fetcher = options.fetcher ?? fetch; + const collector = + options.collector ?? + createTelemetryCollector({ + endpoint: options.endpoint, + ...(options.fetcher === undefined ? {} : { fetcher: options.fetcher }), + }); return Object.freeze({ - async send(batch: readonly TelemetryBatchItem[]): Promise { - const response = await fetcher(options.endpoint, { - method: "POST", - headers: { "Content-Type": "application/json" }, - body: JSON.stringify({ - events: batch.map((item) => ({ - ...item.event, - fingerprint: item.fingerprint, - occurrences: item.occurrences, - })), - }), - keepalive: true, - credentials: "omit", - cache: "no-store", - }); - if (!response.ok) throw new Error("telemetry collector rejected batch"); + send(batch: readonly TelemetryBatchItem[]): Promise { + return collector.post( + batch.map((item) => ({ + ...item.event, + fingerprint: item.fingerprint, + occurrences: item.occurrences, + })), + options.signal, + ); }, }); } @@ -65,14 +74,42 @@ export function createFeatureTelemetry( endpoint?: string; fetcher?: typeof fetch; budget?: TelemetryPipelineBudget; + /** + * Q-6.9-4. The collector shared with the application telemetry port: one + * send-rate window and one page-exit flush for the endpoint. When set, it + * owns `fetcher` and the send rate. + */ + collector?: TelemetryCollector; }>, ): TelemetryPipeline { if (!options.enabled || !options.endpoint) return DISABLED_FEATURE_TELEMETRY; - return createTelemetryPipeline({ - transport: createFetchTelemetryTransport({ + const budget = options.budget ?? DEFAULT_TELEMETRY_PIPELINE_BUDGET; + const collector = + options.collector ?? + createTelemetryCollector({ endpoint: options.endpoint, ...(options.fetcher === undefined ? {} : { fetcher: options.fetcher }), + maxSendsPerMinute: budget.maxSendsPerMinute, + }); + const lifetime = new AbortController(); + const pipeline = createTelemetryPipeline({ + transport: createFetchTelemetryTransport({ + endpoint: options.endpoint, + collector, + signal: lifetime.signal, }), - budget: options.budget ?? DEFAULT_TELEMETRY_PIPELINE_BUDGET, + budget, + sendRate: collector.sendRate, + }); + const stopPageExitFlush = collector.onPageExit(() => { + void pipeline.flush(); + }); + return Object.freeze({ + ...pipeline, + dispose(): void { + stopPageExitFlush(); + lifetime.abort(); + pipeline.dispose(); + }, }); } diff --git a/src/adapters/telemetry/index.ts b/src/adapters/telemetry/index.ts index 5c1f6d57..1d762dd5 100644 --- a/src/adapters/telemetry/index.ts +++ b/src/adapters/telemetry/index.ts @@ -10,3 +10,9 @@ export { createFeatureTelemetry, createFetchTelemetryTransport, } from "./feature-telemetry.ts"; +/** Q-6.9-4. 두 텔레메트리 포트가 공유하는 수집기 전송(rate·타임아웃·pagehide). */ +export { + createTelemetryCollector, + type TelemetryCollector, + type TelemetryCollectorOptions, +} from "./telemetry-collector.ts"; diff --git a/src/adapters/telemetry/telemetry-collector.ts b/src/adapters/telemetry/telemetry-collector.ts new file mode 100644 index 00000000..db74f0c7 --- /dev/null +++ b/src/adapters/telemetry/telemetry-collector.ts @@ -0,0 +1,123 @@ +import { + createTelemetrySendRate, + type TelemetrySendRate, +} from "../../platform/telemetry/telemetry-pipeline.ts"; +import { createAbortableOperation } from "../platform/abortable-operation.ts"; +import { assertBoundedCapacity } from "../platform/bounded-capacity.ts"; + +/** + * Q-6.9-4. The one transport layer behind both telemetry ports. + * + * The application port (`best-effort-telemetry.ts`) and the feature port + * (`feature-telemetry.ts`) keep their own queue and body projection, but every + * POST to the collector goes through here: one send-rate window for the + * endpoint, no cookies, no HTTP cache, a deadline on every request, and one + * `pagehide` listener that flushes every queue. + */ +export type TelemetryCollector = Readonly<{ + /** Spec §27. Shared by every queue posting to this collector. */ + sendRate: TelemetrySendRate; + /** + * POSTs `{ events }`. Rejects when the collector refuses the batch, the + * deadline passes, or `signal` aborts — a hung collector never stalls the + * caller's next flush. + */ + post(events: readonly unknown[], signal?: AbortSignal): Promise; + /** Runs `flush` on `pagehide`. Returns the unsubscribe. */ + onPageExit(flush: () => void): () => void; +}>; + +export type TelemetryCollectorOptions = Readonly<{ + endpoint: string; + fetcher?: typeof fetch; + /** Sends per rolling minute across every queue (default 20). */ + maxSendsPerMinute?: number; + /** Per-request deadline (default 10s). */ + timeoutMs?: number; + /** Monotonic clock for the send-rate window (default `performance.now`). */ + now?: () => number; + lifecycle?: Pick; +}>; + +export const DEFAULT_TELEMETRY_SENDS_PER_MINUTE = 20; +export const DEFAULT_TELEMETRY_TIMEOUT_MS = 10_000; +/** Also bounds the send-time window the rate keeps in memory. */ +const MAX_SENDS_PER_MINUTE = 10_000; +const MAX_TIMEOUT_MS = 60_000; + +export function createTelemetryCollector( + options: TelemetryCollectorOptions, +): TelemetryCollector { + const { endpoint } = options; + const fetcher = options.fetcher ?? fetch; + const timeoutMs = assertBoundedCapacity( + options.timeoutMs ?? DEFAULT_TELEMETRY_TIMEOUT_MS, + MAX_TIMEOUT_MS, + "telemetry timeoutMs", + ); + const sendRate = createTelemetrySendRate( + assertBoundedCapacity( + options.maxSendsPerMinute ?? DEFAULT_TELEMETRY_SENDS_PER_MINUTE, + MAX_SENDS_PER_MINUTE, + "telemetry maxSendsPerMinute", + ), + options.now, + ); + const lifecycle = + options.lifecycle ?? + (typeof globalThis.addEventListener === "function" && + typeof globalThis.removeEventListener === "function" + ? globalThis + : undefined); + const exitFlushes = new Set<() => void>(); + const onPageHide = () => { + for (const flush of [...exitFlushes]) flush(); + }; + + async function post( + events: readonly unknown[], + signal?: AbortSignal, + ): Promise { + const operation = createAbortableOperation({ + ...(signal === undefined ? {} : { signal }), + timeoutMs, + }); + try { + const outcome = await operation.race( + Promise.resolve( + fetcher(endpoint, { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ events }), + keepalive: true, + credentials: "omit", + cache: "no-store", + signal: operation.signal, + }), + ), + ); + if (outcome.kind !== "VALUE" || !outcome.value.ok) { + throw new Error("telemetry collector did not accept the batch"); + } + } finally { + operation.close(); + } + } + + return Object.freeze({ + sendRate, + post, + onPageExit(flush: () => void): () => void { + // The listener exists only while some queue wants a page-exit flush. + if (exitFlushes.size === 0) { + lifecycle?.addEventListener("pagehide", onPageHide); + } + exitFlushes.add(flush); + return () => { + if (exitFlushes.delete(flush) && exitFlushes.size === 0) { + lifecycle?.removeEventListener("pagehide", onPageHide); + } + }; + }, + }); +} diff --git a/src/bootstrap/runtime-adapters.ts b/src/bootstrap/runtime-adapters.ts index 36a1580f..91e73ce6 100644 --- a/src/bootstrap/runtime-adapters.ts +++ b/src/bootstrap/runtime-adapters.ts @@ -33,6 +33,7 @@ import { createBrowserMutationIntentFactory } from "../adapters/platform/index.t import { createFeatureTelemetry, createTelemetryAdapter, + createTelemetryCollector, } from "../adapters/telemetry/index.ts"; import type { AuthSessionPort } from "../application/ports/auth-session-port.ts"; import type { ReleaseInfo } from "../application/ports/release-info-port.ts"; @@ -307,10 +308,20 @@ export async function createRuntimeAdapters( ? createExternalAuthSessionAdapter(externalOwner) : createUnavailableSessionAdapter(); const diagnostics = createDiagnosticsAdapter(); + // Q-6.9-4. Both telemetry ports post through one collector transport: one + // send-rate window, one page-exit flush and one fetch policy per endpoint. + const telemetryCollector = + config.TELEMETRY_ENABLED && config.TELEMETRY_ENDPOINT + ? createTelemetryCollector({ + endpoint: config.TELEMETRY_ENDPOINT, + ...(context.fetcher === undefined ? {} : { fetcher: context.fetcher }), + }) + : undefined; const telemetry = createTelemetryAdapter({ enabled: config.TELEMETRY_ENABLED, endpoint: config.TELEMETRY_ENDPOINT, fetcher: context.fetcher, + ...(telemetryCollector === undefined ? {} : { collector: telemetryCollector }), onDrop(event) { const attributes = event.attributes && typeof event.attributes === "object" @@ -543,6 +554,7 @@ export async function createRuntimeAdapters( ? {} : { endpoint: config.TELEMETRY_ENDPOINT }), ...(context.fetcher === undefined ? {} : { fetcher: context.fetcher }), + ...(telemetryCollector === undefined ? {} : { collector: telemetryCollector }), }); // Each installed contribution receives only the capabilities it declares. const featureCapabilities = Object.freeze({ diff --git a/src/platform/telemetry/telemetry-pipeline.ts b/src/platform/telemetry/telemetry-pipeline.ts index fe3c96cf..94ba7799 100644 --- a/src/platform/telemetry/telemetry-pipeline.ts +++ b/src/platform/telemetry/telemetry-pipeline.ts @@ -93,12 +93,53 @@ function assertPositive(name: string, value: number): void { } } +/** + * Spec §27. A rolling one-minute send budget. Several queues that post to the + * same collector share one instance, so the limit belongs to the collector + * rather than to each queue (Q-6.9-4). + */ +export interface TelemetrySendRate { + /** + * Takes a send slot and returns 0, or returns the milliseconds until a slot + * reopens. `force` always takes one: page exit may exceed the window once. + */ + take(force?: boolean): number; +} + +export function createTelemetrySendRate( + maxSendsPerMinute: number, + now: () => number = () => performance.now(), +): TelemetrySendRate { + assertPositive("maxSendsPerMinute", maxSendsPerMinute); + /** Send instants inside the current window; never longer than the limit. */ + const sendTimes: number[] = []; + return Object.freeze({ + take(force = false): number { + const at = now(); + while (sendTimes.length > 0 && at - (sendTimes[0] as number) >= RATE_WINDOW_MS) { + sendTimes.shift(); + } + if (!force && sendTimes.length >= maxSendsPerMinute) { + return Math.max(1, (sendTimes[0] as number) + RATE_WINDOW_MS - at); + } + sendTimes.push(at); + if (sendTimes.length > maxSendsPerMinute) sendTimes.shift(); + return 0; + }, + }); +} + export function createTelemetryPipeline( options: Readonly<{ transport: TelemetryTransport; budget?: TelemetryPipelineBudget; /** Monotonic clock. */ now?: () => number; + /** + * A send-rate window shared with other queues posting to the same + * collector. Default: a private one from `budget.maxSendsPerMinute`. + */ + sendRate?: TelemetrySendRate; /** Schedules a flush soon (default: microtask). */ schedule?: (callback: () => void) => void; /** Schedules a flush after a rate window reopens (default: setTimeout). */ @@ -136,8 +177,8 @@ export function createTelemetryPipeline( }); /** Duplicates counted but not yet reported, per fingerprint. */ const held = new Map; count: number }>(); - /** Send timestamps inside the current rate window; never above the limit. */ - const sendTimes: number[] = []; + const sendRate = + options.sendRate ?? createTelemetrySendRate(budget.maxSendsPerMinute, now); let disposed = false; let flushScheduled = false; @@ -156,16 +197,8 @@ export function createTelemetryPipeline( peakBuffered: 0, }; - function rateAllows(at: number): boolean { - while (sendTimes.length > 0 && at - (sendTimes[0] as number) >= RATE_WINDOW_MS) { - sendTimes.shift(); - } - return sendTimes.length < budget.maxSendsPerMinute; - } - - function armRateTimer(at: number): void { + function armRateTimer(reopenIn: number): void { if (rateTimer !== null || disposed) return; - const reopenIn = Math.max(1, (sendTimes[0] ?? at) + RATE_WINDOW_MS - at); rateTimer = setTimer(() => { rateTimer = null; void flush(); @@ -227,13 +260,12 @@ export function createTelemetryPipeline( async function drain(): Promise { while (!disposed && pending()) { - const at = now(); - if (!rateAllows(at)) { - armRateTimer(at); + const reopenIn = sendRate.take(); + if (reopenIn > 0) { + armRateTimer(reopenIn); return; } const batch = takeBatch(); - sendTimes.push(at); counters.sends += 1; try { await options.transport.send(batch); diff --git a/tests/unit/telemetry.test.ts b/tests/unit/telemetry.test.ts index 4d501f6f..e1f8aa38 100644 --- a/tests/unit/telemetry.test.ts +++ b/tests/unit/telemetry.test.ts @@ -5,6 +5,11 @@ import { createTelemetryAdapter, safeTraceparent, } from "../../src/adapters/telemetry/best-effort-telemetry.ts"; +import { + createFeatureTelemetry, + createFetchTelemetryTransport, +} from "../../src/adapters/telemetry/feature-telemetry.ts"; +import { createTelemetryCollector } from "../../src/adapters/telemetry/telemetry-collector.ts"; import { TELEMETRY_REGISTRY, projectTelemetryEvent, @@ -357,6 +362,238 @@ describe("best-effort telemetry adapter", () => { ); }); +describe("telemetry collector payloads (Q-6.9-4)", () => { + function recordingFetcher() { + const calls: Array> = []; + const fetcher = vi.fn(async (url: RequestInfo | URL, init?: RequestInit) => { + calls.push({ url: String(url), init: init ?? {} }); + return new Response(null, { status: 204 }); + }); + return { calls, fetcher: fetcher as unknown as typeof fetch }; + } + + it("posts the contract projection for the application port", async () => { + const { calls, fetcher } = recordingFetcher(); + const adapter = createTelemetryAdapter({ + enabled: true, + endpoint: "https://telemetry.test/events", + schedule: () => {}, + now: () => Date.parse("2026-09-24T00:00:00.000Z"), + fetcher, + }); + adapter.emit("api.request.failed", validAttributes); + await adapter.flush(); + + expect(calls).toHaveLength(1); + expect(calls[0]?.url).toBe("https://telemetry.test/events"); + expect(calls[0]?.init).toMatchObject({ + method: "POST", + headers: { "Content-Type": "application/json" }, + keepalive: true, + }); + expect(JSON.parse(String(calls[0]?.init.body))).toEqual({ + events: [ + { + eventName: "api.request.failed", + timestamp: "2026-09-24T00:00:00.000Z", + attributes: validAttributes, + }, + ], + }); + adapter.dispose(); + }); + + it("posts the pipeline projection for the feature port", async () => { + const { calls, fetcher } = recordingFetcher(); + const transport = createFetchTelemetryTransport({ + endpoint: "https://telemetry.test/events", + fetcher, + }); + await transport.send([ + { + event: { kind: "catalog.load.failed", severity: "error", featureId: "catalog" }, + fingerprint: "fp-1", + occurrences: 3, + }, + ]); + + expect(calls).toHaveLength(1); + expect(calls[0]?.url).toBe("https://telemetry.test/events"); + expect(calls[0]?.init).toMatchObject({ + method: "POST", + headers: { "Content-Type": "application/json" }, + keepalive: true, + credentials: "omit", + cache: "no-store", + }); + expect(JSON.parse(String(calls[0]?.init.body))).toEqual({ + events: [ + { + kind: "catalog.load.failed", + severity: "error", + featureId: "catalog", + fingerprint: "fp-1", + occurrences: 3, + }, + ], + }); + }); + + it("rejects a feature batch the collector refuses", async () => { + const transport = createFetchTelemetryTransport({ + endpoint: "https://telemetry.test/events", + fetcher: (async () => new Response(null, { status: 503 })) as typeof fetch, + }); + await expect(transport.send([])).rejects.toThrow(); + }); +}); + +describe("one collector transport for both telemetry ports (Q-6.9-4)", () => { + const featureEvent = { + kind: "catalog.load.failed", + severity: "error", + featureId: "catalog", + } as const; + const hungFetcher = () => { + const signals: AbortSignal[] = []; + // Never settles and ignores its signal: only the collector can end it. + const fetcher = vi.fn((_url: RequestInfo | URL, init?: RequestInit) => { + if (init?.signal) signals.push(init.signal); + return new Promise(() => {}); + }); + return { signals, fetcher: fetcher as unknown as typeof fetch, calls: fetcher }; + }; + + it("sends application telemetry without cookies or HTTP cache", async () => { + const fetcher = vi.fn(async () => new Response(null, { status: 204 })); + const adapter = createTelemetryAdapter({ + enabled: true, + endpoint: "https://telemetry.test/events", + schedule: () => {}, + fetcher: fetcher as unknown as typeof fetch, + }); + adapter.emit("api.request.failed", validAttributes); + await adapter.flush(); + + expect(fetcher).toHaveBeenCalledWith( + "https://telemetry.test/events", + expect.objectContaining({ credentials: "omit", cache: "no-store" }), + ); + adapter.dispose(); + }); + + it("times out a hung collector so later application flushes still send", async () => { + const { fetcher, calls } = hungFetcher(); + const collector = createTelemetryCollector({ + endpoint: "https://telemetry.test/events", + fetcher, + timeoutMs: 5, + }); + const adapter = createTelemetryAdapter({ + enabled: true, + endpoint: "https://telemetry.test/events", + schedule: () => {}, + collector, + }); + adapter.emit("api.request.failed", validAttributes); + await adapter.flush(); + expect(adapter.dropReasons()).toEqual({ "sink-failure": 1 }); + + adapter.emit("api.request.failed", validAttributes); + await adapter.flush(); + expect(calls).toHaveBeenCalledTimes(2); + adapter.dispose(); + }); + + it("times out a hung collector for feature telemetry", async () => { + const { fetcher } = hungFetcher(); + const telemetry = createFeatureTelemetry({ + enabled: true, + endpoint: "https://telemetry.test/events", + collector: createTelemetryCollector({ + endpoint: "https://telemetry.test/events", + fetcher, + timeoutMs: 5, + }), + }); + await telemetry.emit(featureEvent); + await telemetry.flush(); + expect(telemetry.stats()).toMatchObject({ sends: 1, failedSends: 1 }); + telemetry.dispose(); + }); + + it("shares one send-rate window between the two ports", async () => { + const fetcher = vi.fn(async () => new Response(null, { status: 204 })); + const collector = createTelemetryCollector({ + endpoint: "https://telemetry.test/events", + fetcher: fetcher as unknown as typeof fetch, + maxSendsPerMinute: 1, + }); + const adapter = createTelemetryAdapter({ + enabled: true, + endpoint: "https://telemetry.test/events", + schedule: () => {}, + setTimer: () => 0, + clearTimer: () => {}, + collector, + }); + const telemetry = createFeatureTelemetry({ + enabled: true, + endpoint: "https://telemetry.test/events", + collector, + }); + + adapter.emit("api.request.failed", validAttributes); + await adapter.flush(); + await telemetry.emit(featureEvent); + await telemetry.flush(); + + expect(fetcher).toHaveBeenCalledOnce(); + expect(telemetry.stats().buffered).toBe(1); + adapter.dispose(); + telemetry.dispose(); + }); + + it("flushes feature telemetry on page exit and stops listening on dispose", async () => { + const lifecycle = new EventTarget(); + const remove = vi.spyOn(lifecycle, "removeEventListener"); + const fetcher = vi.fn(async () => new Response(null, { status: 204 })); + const telemetry = createFeatureTelemetry({ + enabled: true, + endpoint: "https://telemetry.test/events", + collector: createTelemetryCollector({ + endpoint: "https://telemetry.test/events", + fetcher: fetcher as unknown as typeof fetch, + lifecycle, + }), + }); + await telemetry.emit(featureEvent); + await vi.waitFor(() => expect(fetcher).toHaveBeenCalledOnce()); + // A duplicate is held until the next flush; page exit is that flush. + await telemetry.emit(featureEvent); + expect(fetcher).toHaveBeenCalledOnce(); + + lifecycle.dispatchEvent(new Event("pagehide")); + await vi.waitFor(() => expect(fetcher).toHaveBeenCalledTimes(2)); + telemetry.dispose(); + expect(remove).toHaveBeenCalledWith("pagehide", expect.any(Function)); + }); + + it("aborts an in-flight feature batch on dispose", async () => { + const { fetcher, signals } = hungFetcher(); + const telemetry = createFeatureTelemetry({ + enabled: true, + endpoint: "https://telemetry.test/events", + fetcher, + }); + await telemetry.emit(featureEvent); + await vi.waitFor(() => expect(signals).toHaveLength(1)); + + telemetry.dispose(); + expect(signals[0]?.aborted).toBe(true); + }); +}); + describe("telemetry adapter send-rate limit (spec §27)", () => { function harness(maxSendsPerMinute = 3) { let now = 0;