diff --git a/src/adapters/telemetry/best-effort-telemetry.js b/src/adapters/telemetry/best-effort-telemetry.js new file mode 100644 index 0000000..116289c --- /dev/null +++ b/src/adapters/telemetry/best-effort-telemetry.js @@ -0,0 +1,99 @@ +import { projectTelemetryEvent } from "../../contracts/telemetry.js"; + +export const noOpTelemetry = Object.freeze({ + emit: () => {}, +}); + +/** + * @param {{ + * enabled: boolean, + * endpoint?: string, + * fetcher?: typeof fetch, + * maxQueue?: number, + * schedule?: (callback: () => void) => void + * }} options + */ +export function createTelemetryAdapter(options) { + if (!options.enabled || !options.endpoint) { + return Object.freeze({ + ...noOpTelemetry, + flush: async () => {}, + pendingCount: () => 0, + droppedCount: () => 0, + }); + } + + const endpoint = /** @type {string} */ (options.endpoint); + const fetcher = options.fetcher ?? fetch; + const maxQueue = options.maxQueue ?? 100; + const schedule = options.schedule ?? queueMicrotask; + const queue = + /** @type {Array<{eventName: string, attributes: Readonly>}>} */ ( + [] + ); + let scheduled = false; + let flushing = false; + let dropped = 0; + + /** @param {string} eventName @param {Record} attributes */ + function emit(eventName, attributes) { + const projected = projectTelemetryEvent(eventName, attributes); + if (!projected.success) { + dropped += 1; + return; + } + + if (queue.length >= maxQueue) { + queue.shift(); + dropped += 1; + } + queue.push(projected.event); + + if (!scheduled) { + scheduled = true; + schedule(() => { + scheduled = false; + void flush(); + }); + } + } + + async function flush() { + if (flushing || queue.length === 0) return; + flushing = true; + const batch = queue.splice(0, queue.length); + try { + const response = await fetcher(endpoint, { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ events: batch }), + keepalive: true, + }); + if (!response.ok) dropped += batch.length; + } catch { + dropped += batch.length; + } finally { + flushing = false; + } + } + + return Object.freeze({ + emit, + flush, + pendingCount: () => queue.length, + droppedCount: () => dropped, + }); +} + +/** + * Propagates only a structurally valid W3C traceparent. Invalid/raw headers are + * discarded rather than logged or surfaced. + * + * @param {string | null | undefined} traceparent + */ +export function safeTraceparent(traceparent) { + return typeof traceparent === "string" && + /^00-[0-9a-f]{32}-[0-9a-f]{16}-0[01]$/i.test(traceparent) + ? traceparent.toLowerCase() + : null; +} diff --git a/src/contracts/telemetry.js b/src/contracts/telemetry.js new file mode 100644 index 0000000..301ac22 --- /dev/null +++ b/src/contracts/telemetry.js @@ -0,0 +1,145 @@ +export const TELEMETRY_ATTRIBUTE_ALLOWLIST = Object.freeze([ + "app_version", + "build_id", + "release_id", + "config_schema_version", + "api_contract_version", + "route_id", + "operation_id", + "error_kind", + "http_status_group", + "attempt_count_bucket", + "duration_bucket", + "component_boundary", + "active_release_id", + "mismatch_kind", + "reason", + "queue_size_bucket", +]); + +export const TELEMETRY_FORBIDDEN_ATTRIBUTES = Object.freeze([ + "access_token", + "refresh_token", + "authorization_header", + "cookie", + "email", + "user_name", + "raw_user_id", + "raw_url", + "query_string", + "request_body", + "response_body", + "storage_value", + "stack_in_user_message", +]); + +/** + * @typedef {{ + * eventName: string, + * trigger: string, + * requiredAttributes: readonly string[], + * optionalAttributes: readonly string[], + * forbiddenAttributes: readonly string[], + * sampling: string, + * delivery: string + * }} TelemetryDefinition + */ + +/** + * @param {string} eventName + * @param {string} trigger + * @param {string[]} requiredAttributes + * @param {string[]} [optionalAttributes] + * @param {string} [sampling] + * @returns {Readonly} + */ +const event = ( + eventName, + trigger, + requiredAttributes, + optionalAttributes = [], + sampling = "all", +) => + Object.freeze({ + eventName, + trigger, + requiredAttributes: Object.freeze(requiredAttributes), + optionalAttributes: Object.freeze(optionalAttributes), + forbiddenAttributes: TELEMETRY_FORBIDDEN_ATTRIBUTES, + sampling, + delivery: "best-effort", + }); + +export const TELEMETRY_REGISTRY = Object.freeze({ + "app.boot.failed": event("app.boot.failed", "boot validation failure", [ + "error_kind", + "build_id", + "config_schema_version", + ]), + "api.request.failed": event("api.request.failed", "terminal API failure", [ + "error_kind", + "http_status_group", + "attempt_count_bucket", + "route_id", + ]), + "ui.render.failed": event("ui.render.failed", "React boundary catch", [ + "route_id", + "build_id", + "component_boundary", + ]), + "release.mismatch.detected": event( + "release.mismatch.detected", + "release tuple mismatch", + ["build_id", "active_release_id", "mismatch_kind"], + ), + "telemetry.delivery.dropped": event( + "telemetry.delivery.dropped", + "queue or sink failure", + ["reason", "queue_size_bucket"], + [], + "internal-counter", + ), +}); + +/** + * @param {string} eventName + * @param {Record} attributes + */ +export function projectTelemetryEvent(eventName, attributes) { + const registry = + /** @type {Record} */ ( + TELEMETRY_REGISTRY + ); + const definition = registry[eventName]; + if (!definition) { + return { + success: /** @type {false} */ (false), + reason: "unregistered-event", + }; + } + + const projected = Object.fromEntries( + Object.entries(attributes).filter( + ([key]) => + TELEMETRY_ATTRIBUTE_ALLOWLIST.includes(key) && + !TELEMETRY_FORBIDDEN_ATTRIBUTES.includes(key), + ), + ); + const missing = definition.requiredAttributes.filter( + (key) => projected[key] === undefined, + ); + if (missing.length > 0) { + return { + success: /** @type {false} */ (false), + reason: "missing-required-attributes", + }; + } + + return { + success: /** @type {true} */ (true), + event: Object.freeze({ + eventName, + attributes: Object.freeze(projected), + }), + }; +} diff --git a/tests/unit/telemetry.test.js b/tests/unit/telemetry.test.js new file mode 100644 index 0000000..3400abd --- /dev/null +++ b/tests/unit/telemetry.test.js @@ -0,0 +1,105 @@ +import { describe, expect, it, vi } from "vitest"; + +import { + createTelemetryAdapter, + safeTraceparent, +} from "../../src/adapters/telemetry/best-effort-telemetry.js"; +import { + TELEMETRY_REGISTRY, + projectTelemetryEvent, +} from "../../src/contracts/telemetry.js"; + +const validAttributes = { + error_kind: "SERVER_FAILURE", + http_status_group: "5xx", + attempt_count_bucket: "3", + route_id: "SAMPLE_RESOURCE_LIST", +}; + +describe("telemetry registry and redaction", () => { + it("defines all event contract fields", () => { + for (const definition of Object.values(TELEMETRY_REGISTRY)) { + expect(definition).toEqual( + expect.objectContaining({ + eventName: expect.any(String), + trigger: expect.any(String), + requiredAttributes: expect.any(Array), + optionalAttributes: expect.any(Array), + forbiddenAttributes: expect.any(Array), + sampling: expect.any(String), + delivery: "best-effort", + }), + ); + } + }); + + it("uses a default-deny attribute projection", () => { + const projected = projectTelemetryEvent("api.request.failed", { + ...validAttributes, + raw_url: "https://api.test/path?token=secret", + unregistered: "private", + }); + + expect(projected.success).toBe(true); + expect(JSON.stringify(projected)).not.toMatch(/raw_url|token|secret|unregistered/); + }); + + it("validates traceparent without exposing invalid values", () => { + expect( + safeTraceparent( + "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01", + ), + ).toBe("00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"); + expect(safeTraceparent("Bearer secret")).toBeNull(); + }); +}); + +describe("best-effort telemetry adapter", () => { + it("bounds the queue using oldest-drop without blocking callers", () => { + const scheduled = []; + const adapter = createTelemetryAdapter({ + enabled: true, + endpoint: "https://telemetry.test/events", + maxQueue: 2, + schedule: (callback) => scheduled.push(callback), + fetcher: vi.fn(), + }); + + adapter.emit("api.request.failed", validAttributes); + adapter.emit("api.request.failed", validAttributes); + adapter.emit("api.request.failed", validAttributes); + + expect(adapter.pendingCount()).toBe(2); + expect(adapter.droppedCount()).toBe(1); + expect(scheduled).toHaveLength(1); + }); + + it("degrades on sink failure without throwing or recursive events", async () => { + const adapter = createTelemetryAdapter({ + enabled: true, + endpoint: "https://telemetry.test/events", + schedule: () => {}, + fetcher: async () => { + throw new Error("sink unavailable"); + }, + }); + expect(() => adapter.emit("api.request.failed", validAttributes)).not.toThrow(); + await expect(adapter.flush()).resolves.toBeUndefined(); + expect(adapter.droppedCount()).toBe(1); + expect(adapter.pendingCount()).toBe(0); + }); + + it("performs no network or queue work when disabled", async () => { + const fetcher = vi.fn(); + const adapter = createTelemetryAdapter({ + enabled: false, + endpoint: "https://telemetry.test/events", + fetcher, + }); + adapter.emit("api.request.failed", validAttributes); + await adapter.flush(); + + expect(fetcher).not.toHaveBeenCalled(); + expect(adapter.pendingCount()).toBe(0); + }); +});