feat: add redacted best-effort telemetry contract
This commit is contained in:
donghyeon-ka
@@ -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<Record<string, unknown>>}>} */ (
|
||||
[]
|
||||
);
|
||||
let scheduled = false;
|
||||
let flushing = false;
|
||||
let dropped = 0;
|
||||
|
||||
/** @param {string} eventName @param {Record<string, unknown>} 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;
|
||||
}
|
||||
@@ -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<TelemetryDefinition>}
|
||||
*/
|
||||
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<string, unknown>} attributes
|
||||
*/
|
||||
export function projectTelemetryEvent(eventName, attributes) {
|
||||
const registry =
|
||||
/** @type {Record<string, (typeof TELEMETRY_REGISTRY)[keyof typeof TELEMETRY_REGISTRY]>} */ (
|
||||
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),
|
||||
}),
|
||||
};
|
||||
}
|
||||
@@ -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);
|
||||
});
|
||||
});
|
||||
Reference in New Issue
Block a user