refactor: 도메인이 100개 1000개씩 늘어나도 유지보수 쉬운 구조로 변경
This commit is contained in:
@@ -0,0 +1,144 @@
|
||||
/**
|
||||
* Spec §28. Redaction before buffering.
|
||||
*
|
||||
* The sanitizer copies only plain own data into fresh objects/arrays: it never
|
||||
* preserves prototypes and never invokes getters or `toJSON` on untrusted
|
||||
* payloads. Traversal is iterative and capped by a structural budget, so an
|
||||
* adversarial payload cannot make telemetry itself unbounded.
|
||||
*/
|
||||
export type TelemetryPayloadBudget = Readonly<{
|
||||
maxDepth: number;
|
||||
maxKeys: number;
|
||||
maxArrayItems: number;
|
||||
maxStringLength: number;
|
||||
}>;
|
||||
|
||||
export const DEFAULT_TELEMETRY_PAYLOAD_BUDGET: TelemetryPayloadBudget =
|
||||
Object.freeze({
|
||||
maxDepth: 6,
|
||||
maxKeys: 64,
|
||||
maxArrayItems: 32,
|
||||
maxStringLength: 256,
|
||||
});
|
||||
|
||||
export const REDACTED = "[redacted]";
|
||||
export const TRUNCATED = "[truncated]";
|
||||
|
||||
/**
|
||||
* Case/separator-insensitive secret key detection. `accessToken`,
|
||||
* `access_token` and `ACCESS-TOKEN` all normalize to `accesstoken`.
|
||||
*/
|
||||
const SECRET_KEY_FRAGMENTS = Object.freeze([
|
||||
"password",
|
||||
"passwd",
|
||||
"secret",
|
||||
"authorization",
|
||||
"cookie",
|
||||
"token",
|
||||
"apikey",
|
||||
"credential",
|
||||
"session",
|
||||
"privatekey",
|
||||
"signature",
|
||||
]);
|
||||
|
||||
export function isSecretTelemetryKey(key: string): boolean {
|
||||
const normalized = key.toLowerCase().replace(/[^a-z0-9]/gu, "");
|
||||
return SECRET_KEY_FRAGMENTS.some((fragment) => normalized.includes(fragment));
|
||||
}
|
||||
|
||||
/** Values that look like bearer credentials are redacted wherever they occur. */
|
||||
const SECRET_VALUE = /^(?:bearer|basic)\s+\S+|^eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\./iu;
|
||||
|
||||
function readOwnData(
|
||||
source: object,
|
||||
key: string,
|
||||
): Readonly<{ ok: true; value: unknown }> | Readonly<{ ok: false }> {
|
||||
const descriptor = Object.getOwnPropertyDescriptor(source, key);
|
||||
if (!descriptor || !("value" in descriptor)) return { ok: false };
|
||||
return { ok: true, value: descriptor.value };
|
||||
}
|
||||
|
||||
function sanitizeLeaf(value: unknown, budget: TelemetryPayloadBudget): unknown {
|
||||
switch (typeof value) {
|
||||
case "string":
|
||||
if (SECRET_VALUE.test(value)) return REDACTED;
|
||||
return value.length > budget.maxStringLength
|
||||
? `${value.slice(0, budget.maxStringLength)}${TRUNCATED}`
|
||||
: value;
|
||||
case "number":
|
||||
return Number.isFinite(value) ? value : null;
|
||||
case "boolean":
|
||||
return value;
|
||||
default:
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
type Pending = Readonly<{
|
||||
source: unknown;
|
||||
depth: number;
|
||||
assign: (value: unknown) => void;
|
||||
}>;
|
||||
|
||||
export function redactTelemetryPayload(
|
||||
payload: unknown,
|
||||
budget: TelemetryPayloadBudget = DEFAULT_TELEMETRY_PAYLOAD_BUDGET,
|
||||
): unknown {
|
||||
let result: unknown = null;
|
||||
const stack: Pending[] = [
|
||||
{
|
||||
source: payload,
|
||||
depth: 0,
|
||||
assign: (value) => {
|
||||
result = value;
|
||||
},
|
||||
},
|
||||
];
|
||||
while (stack.length > 0) {
|
||||
const { source, depth, assign } = stack.pop() as Pending;
|
||||
if (source === null || typeof source !== "object") {
|
||||
assign(source === undefined ? null : sanitizeLeaf(source, budget));
|
||||
continue;
|
||||
}
|
||||
if (depth >= budget.maxDepth) {
|
||||
assign(TRUNCATED);
|
||||
continue;
|
||||
}
|
||||
if (Array.isArray(source)) {
|
||||
const length = Math.min(source.length, budget.maxArrayItems);
|
||||
const copy: unknown[] = new Array<unknown>(length).fill(null);
|
||||
assign(copy);
|
||||
for (let index = 0; index < length; index += 1) {
|
||||
const item = readOwnData(source, String(index));
|
||||
if (!item.ok) continue;
|
||||
stack.push({
|
||||
source: item.value,
|
||||
depth: depth + 1,
|
||||
assign: (value) => {
|
||||
copy[index] = value;
|
||||
},
|
||||
});
|
||||
}
|
||||
continue;
|
||||
}
|
||||
const copy: Record<string, unknown> = {};
|
||||
assign(copy);
|
||||
for (const key of Object.keys(source).slice(0, budget.maxKeys)) {
|
||||
if (key === "__proto__" || key === "constructor" || key === "prototype") {
|
||||
continue;
|
||||
}
|
||||
if (isSecretTelemetryKey(key)) continue;
|
||||
const entry = readOwnData(source, key);
|
||||
if (!entry.ok) continue;
|
||||
stack.push({
|
||||
source: entry.value,
|
||||
depth: depth + 1,
|
||||
assign: (value) => {
|
||||
copy[key] = value;
|
||||
},
|
||||
});
|
||||
}
|
||||
}
|
||||
return result;
|
||||
}
|
||||
@@ -0,0 +1,125 @@
|
||||
import {
|
||||
TELEMETRY_SEVERITY_RANK,
|
||||
type TelemetryEvent,
|
||||
} from "./telemetry-event.ts";
|
||||
|
||||
/**
|
||||
* Spec §25 / §27. Bounded, severity-aware telemetry buffer.
|
||||
*
|
||||
* The buffer never exceeds `maxEvents` or `maxBytes`. When full, the lowest
|
||||
* severity (oldest first) event is evicted; an incoming event that is not more
|
||||
* important than everything buffered is dropped instead. Buffer growth is
|
||||
* never used as backpressure.
|
||||
*/
|
||||
export type BufferedTelemetryEvent = Readonly<{
|
||||
event: TelemetryEvent<unknown>;
|
||||
bytes: number;
|
||||
/** Deduplication key assigned by the pipeline, when there is one. */
|
||||
fingerprint?: string;
|
||||
}>;
|
||||
|
||||
export interface TelemetryBuffer {
|
||||
readonly size: number;
|
||||
readonly bytes: number;
|
||||
readonly dropped: number;
|
||||
readonly items: readonly TelemetryEvent<unknown>[];
|
||||
push(
|
||||
event: TelemetryEvent<unknown>,
|
||||
bytes?: number,
|
||||
fingerprint?: string,
|
||||
): boolean;
|
||||
take(maxEvents: number): readonly BufferedTelemetryEvent[];
|
||||
clear(): void;
|
||||
}
|
||||
|
||||
const UTF8 = new TextEncoder();
|
||||
|
||||
export function estimateTelemetryBytes(event: TelemetryEvent<unknown>): number {
|
||||
try {
|
||||
return UTF8.encode(JSON.stringify(event)).byteLength;
|
||||
} catch {
|
||||
return Number.POSITIVE_INFINITY;
|
||||
}
|
||||
}
|
||||
|
||||
export function createTelemetryBuffer(
|
||||
options: Readonly<{ maxEvents: number; maxBytes: number }>,
|
||||
): TelemetryBuffer {
|
||||
const { maxEvents, maxBytes } = options;
|
||||
if (!Number.isSafeInteger(maxEvents) || maxEvents < 1) {
|
||||
throw new TypeError(`telemetry buffer maxEvents must be positive: ${maxEvents}`);
|
||||
}
|
||||
if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) {
|
||||
throw new TypeError(`telemetry buffer maxBytes must be positive: ${maxBytes}`);
|
||||
}
|
||||
const entries: BufferedTelemetryEvent[] = [];
|
||||
let bytes = 0;
|
||||
let dropped = 0;
|
||||
|
||||
function lowestIndex(): number {
|
||||
let index = -1;
|
||||
let rank = Number.POSITIVE_INFINITY;
|
||||
for (let i = 0; i < entries.length; i += 1) {
|
||||
const candidate = TELEMETRY_SEVERITY_RANK[(entries[i] as BufferedTelemetryEvent).event.severity];
|
||||
if (candidate < rank) {
|
||||
rank = candidate;
|
||||
index = i;
|
||||
}
|
||||
}
|
||||
return index;
|
||||
}
|
||||
|
||||
return {
|
||||
get size() {
|
||||
return entries.length;
|
||||
},
|
||||
get bytes() {
|
||||
return bytes;
|
||||
},
|
||||
get dropped() {
|
||||
return dropped;
|
||||
},
|
||||
get items() {
|
||||
return entries.map((entry) => entry.event);
|
||||
},
|
||||
push(event, size = estimateTelemetryBytes(event), fingerprint) {
|
||||
if (!Number.isFinite(size) || size > maxBytes) {
|
||||
dropped += 1;
|
||||
return false;
|
||||
}
|
||||
const incomingRank = TELEMETRY_SEVERITY_RANK[event.severity];
|
||||
while (entries.length >= maxEvents || bytes + size > maxBytes) {
|
||||
const victim = lowestIndex();
|
||||
const victimEntry = entries[victim];
|
||||
if (
|
||||
!victimEntry ||
|
||||
TELEMETRY_SEVERITY_RANK[victimEntry.event.severity] > incomingRank
|
||||
) {
|
||||
dropped += 1;
|
||||
return false;
|
||||
}
|
||||
entries.splice(victim, 1);
|
||||
bytes -= victimEntry.bytes;
|
||||
dropped += 1;
|
||||
}
|
||||
entries.push(
|
||||
Object.freeze(
|
||||
fingerprint === undefined
|
||||
? { event, bytes: size }
|
||||
: { event, bytes: size, fingerprint },
|
||||
),
|
||||
);
|
||||
bytes += size;
|
||||
return true;
|
||||
},
|
||||
take(count) {
|
||||
const batch = entries.splice(0, Math.max(0, count));
|
||||
for (const entry of batch) bytes -= entry.bytes;
|
||||
return batch;
|
||||
},
|
||||
clear() {
|
||||
entries.length = 0;
|
||||
bytes = 0;
|
||||
},
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,73 @@
|
||||
/**
|
||||
* Spec §27. Bounded fingerprint deduplication.
|
||||
*
|
||||
* Each fingerprint is admitted once per window; later occurrences inside the
|
||||
* window only increment a counter. The table never holds more than
|
||||
* `maxEntries` fingerprints: expired entries are evicted first, then the
|
||||
* least recently seen one (Map insertion order is maintained as LRU order).
|
||||
*/
|
||||
export type TelemetryDeduplicatorOptions = Readonly<{
|
||||
maxEntries: number;
|
||||
windowMs: number;
|
||||
}>;
|
||||
|
||||
type Entry = { firstSeenAt: number; count: number };
|
||||
|
||||
export class TelemetryDeduplicator {
|
||||
readonly maxEntries: number;
|
||||
readonly windowMs: number;
|
||||
readonly #entries = new Map<string, Entry>();
|
||||
|
||||
constructor(options: TelemetryDeduplicatorOptions) {
|
||||
if (!Number.isSafeInteger(options.maxEntries) || options.maxEntries < 1) {
|
||||
throw new TypeError(`dedup maxEntries must be a positive safe integer: ${options.maxEntries}`);
|
||||
}
|
||||
if (!Number.isSafeInteger(options.windowMs) || options.windowMs < 1) {
|
||||
throw new TypeError(`dedup windowMs must be a positive safe integer: ${options.windowMs}`);
|
||||
}
|
||||
this.maxEntries = options.maxEntries;
|
||||
this.windowMs = options.windowMs;
|
||||
}
|
||||
|
||||
get size(): number {
|
||||
return this.#entries.size;
|
||||
}
|
||||
|
||||
/**
|
||||
* Records one occurrence. Returns `true` when this is the first occurrence
|
||||
* in the current window (the event should continue down the pipeline) and
|
||||
* `false` when it is a duplicate.
|
||||
*/
|
||||
record(fingerprint: string, now: number): boolean {
|
||||
const existing = this.#entries.get(fingerprint);
|
||||
if (existing && now - existing.firstSeenAt < this.windowMs) {
|
||||
existing.count += 1;
|
||||
// Refresh LRU position.
|
||||
this.#entries.delete(fingerprint);
|
||||
this.#entries.set(fingerprint, existing);
|
||||
return false;
|
||||
}
|
||||
if (existing) this.#entries.delete(fingerprint);
|
||||
this.#evict(now);
|
||||
this.#entries.set(fingerprint, { firstSeenAt: now, count: 1 });
|
||||
return true;
|
||||
}
|
||||
|
||||
count(fingerprint: string): number {
|
||||
return this.#entries.get(fingerprint)?.count ?? 0;
|
||||
}
|
||||
|
||||
#evict(now: number): void {
|
||||
if (this.#entries.size < this.maxEntries) return;
|
||||
for (const [fingerprint, entry] of this.#entries) {
|
||||
if (now - entry.firstSeenAt >= this.windowMs) {
|
||||
this.#entries.delete(fingerprint);
|
||||
}
|
||||
}
|
||||
while (this.#entries.size >= this.maxEntries) {
|
||||
const oldest = this.#entries.keys().next();
|
||||
if (oldest.done) break;
|
||||
this.#entries.delete(oldest.value);
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,52 @@
|
||||
import type { ErrorSeverity } from "../errors/app-error.ts";
|
||||
|
||||
/**
|
||||
* Spec §23–§24. The provider-neutral telemetry envelope.
|
||||
*
|
||||
* The platform owns the envelope and its bounded dimensions. The concrete
|
||||
* `kind` and `payload` belong to the emitting feature; there is no global
|
||||
* union of every feature's telemetry payload.
|
||||
*/
|
||||
export type TelemetrySeverity = ErrorSeverity;
|
||||
|
||||
export interface TelemetryEvent<TPayload = unknown> {
|
||||
/** Stable low-cardinality `owner.event` identifier. */
|
||||
readonly kind: string;
|
||||
readonly severity: TelemetrySeverity;
|
||||
readonly contextId?: string;
|
||||
readonly featureId?: string;
|
||||
/**
|
||||
* Request-cardinality correlation. Used as the deterministic sampling key
|
||||
* and never as a fingerprint dimension.
|
||||
*/
|
||||
readonly interactionId?: string;
|
||||
readonly traceId?: string;
|
||||
readonly payload?: TPayload;
|
||||
}
|
||||
|
||||
export const TELEMETRY_SEVERITY_RANK: Readonly<Record<TelemetrySeverity, number>> =
|
||||
Object.freeze({
|
||||
info: 0,
|
||||
warning: 1,
|
||||
error: 2,
|
||||
critical: 3,
|
||||
});
|
||||
|
||||
const TELEMETRY_KIND = /^[a-z][a-z0-9-]{0,39}(?:\.[a-z][a-z0-9-]{0,39}){1,4}$/u;
|
||||
const TELEMETRY_OWNER_ID = /^[a-z][a-z0-9-]{0,63}$/u;
|
||||
const TELEMETRY_CORRELATION = /^[A-Za-z0-9._:-]{1,128}$/u;
|
||||
|
||||
/** Envelope-level admission: bounded identifiers only, payload checked later. */
|
||||
export function isTelemetryEnvelopeValid(event: TelemetryEvent<unknown>): boolean {
|
||||
return (
|
||||
typeof event === "object" &&
|
||||
event !== null &&
|
||||
TELEMETRY_KIND.test(event.kind) &&
|
||||
Object.hasOwn(TELEMETRY_SEVERITY_RANK, event.severity) &&
|
||||
(event.contextId === undefined || TELEMETRY_OWNER_ID.test(event.contextId)) &&
|
||||
(event.featureId === undefined || TELEMETRY_OWNER_ID.test(event.featureId)) &&
|
||||
(event.interactionId === undefined ||
|
||||
TELEMETRY_CORRELATION.test(event.interactionId)) &&
|
||||
(event.traceId === undefined || /^[0-9a-f]{32}$/u.test(event.traceId))
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,89 @@
|
||||
import type { TelemetryEvent } from "./telemetry-event.ts";
|
||||
|
||||
/**
|
||||
* Spec §27. Deterministic fingerprint over the bounded dimensions of an event.
|
||||
*
|
||||
* Request-cardinality fields (`interactionId`, `traceId`) are excluded on
|
||||
* purpose: the same failure hitting ten thousand interactions must collapse to
|
||||
* one fingerprint. The payload contributes through a stable key-sorted
|
||||
* serialization of its (already redacted) value.
|
||||
*/
|
||||
|
||||
/** Structural punctuation, kept distinct from any payload string. */
|
||||
class Token {
|
||||
readonly text: string;
|
||||
constructor(text: string) {
|
||||
this.text = text;
|
||||
}
|
||||
}
|
||||
|
||||
const CLOSE_ARRAY = new Token("]");
|
||||
const CLOSE_OBJECT = new Token("}");
|
||||
const COMMA = new Token(",");
|
||||
|
||||
export function stableSerialize(value: unknown): string {
|
||||
const parts: string[] = [];
|
||||
const stack: unknown[] = [value];
|
||||
while (stack.length > 0) {
|
||||
const current = stack.pop();
|
||||
if (current instanceof Token) {
|
||||
parts.push(current.text);
|
||||
continue;
|
||||
}
|
||||
if (current === null || typeof current !== "object") {
|
||||
parts.push(JSON.stringify(current ?? null) ?? "null");
|
||||
continue;
|
||||
}
|
||||
if (Array.isArray(current)) {
|
||||
parts.push("[");
|
||||
stack.push(CLOSE_ARRAY);
|
||||
for (let index = current.length - 1; index >= 0; index -= 1) {
|
||||
stack.push(current[index]);
|
||||
if (index > 0) stack.push(COMMA);
|
||||
}
|
||||
continue;
|
||||
}
|
||||
parts.push("{");
|
||||
stack.push(CLOSE_OBJECT);
|
||||
const keys = Object.keys(current).sort();
|
||||
for (let index = keys.length - 1; index >= 0; index -= 1) {
|
||||
const key = keys[index] as string;
|
||||
stack.push((current as Record<string, unknown>)[key]);
|
||||
stack.push(new Token(`${index > 0 ? "," : ""}${JSON.stringify(key)}:`));
|
||||
}
|
||||
}
|
||||
return parts.join("");
|
||||
}
|
||||
|
||||
function fnv1a32(text: string, seed: number): number {
|
||||
let hash = seed >>> 0;
|
||||
for (let index = 0; index < text.length; index += 1) {
|
||||
hash ^= text.charCodeAt(index);
|
||||
hash = Math.imul(hash, 0x01000193) >>> 0;
|
||||
}
|
||||
return hash >>> 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* Two independently seeded 32-bit FNV-1a hashes rendered as 16 hex
|
||||
* characters. Not cryptographic; collision resistance only needs to keep
|
||||
* distinct low-cardinality failures apart.
|
||||
*/
|
||||
export function stableHash64(text: string): string {
|
||||
return (
|
||||
fnv1a32(text, 0x811c9dc5).toString(16).padStart(8, "0") +
|
||||
fnv1a32(text, 0x01000193 ^ 0x9e3779b9).toString(16).padStart(8, "0")
|
||||
);
|
||||
}
|
||||
|
||||
export function fingerprintTelemetryEvent(event: TelemetryEvent<unknown>): string {
|
||||
return stableHash64(
|
||||
stableSerialize({
|
||||
kind: event.kind,
|
||||
severity: event.severity,
|
||||
contextId: event.contextId ?? null,
|
||||
featureId: event.featureId ?? null,
|
||||
payload: event.payload ?? null,
|
||||
}),
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,283 @@
|
||||
import {
|
||||
createTelemetryBuffer,
|
||||
estimateTelemetryBytes,
|
||||
} from "./telemetry-buffer.ts";
|
||||
import { TelemetryDeduplicator } from "./telemetry-deduplicator.ts";
|
||||
import {
|
||||
isTelemetryEnvelopeValid,
|
||||
TELEMETRY_SEVERITY_RANK,
|
||||
type TelemetryEvent,
|
||||
} from "./telemetry-event.ts";
|
||||
import { fingerprintTelemetryEvent } from "./telemetry-fingerprint.ts";
|
||||
import type { TelemetryPort } from "./telemetry-port.ts";
|
||||
import {
|
||||
DEFAULT_TELEMETRY_PAYLOAD_BUDGET,
|
||||
redactTelemetryPayload,
|
||||
type TelemetryPayloadBudget,
|
||||
} from "./redact-telemetry.ts";
|
||||
import { createDeterministicSampler } from "./telemetry-sampler.ts";
|
||||
|
||||
/**
|
||||
* Spec §25–§28. The bounded, fail-open telemetry pipeline:
|
||||
*
|
||||
* redact -> fingerprint -> deduplicate -> sample -> buffer
|
||||
* -> rate limit -> batch -> transport
|
||||
*
|
||||
* Every stage has an explicit ceiling, and no stage can throw or reject into
|
||||
* the business caller: internal failures become dropped-event counters.
|
||||
*/
|
||||
export type TelemetryBatchItem = Readonly<{
|
||||
event: TelemetryEvent<unknown>;
|
||||
fingerprint: string;
|
||||
/** Occurrences collapsed into this fingerprint in the current window. */
|
||||
occurrences: number;
|
||||
}>;
|
||||
|
||||
export interface TelemetryTransport {
|
||||
send(batch: readonly TelemetryBatchItem[]): void | Promise<void>;
|
||||
}
|
||||
|
||||
export interface TelemetryPipelineBudget {
|
||||
readonly maxBufferedEvents: number;
|
||||
readonly maxBufferedBytes: number;
|
||||
readonly maxBatchEvents: number;
|
||||
readonly maxSendsPerMinute: number;
|
||||
readonly dedupWindowMs: number;
|
||||
readonly maxFingerprints: number;
|
||||
/** Sampling rate for `info`/`warning`; `error`/`critical` are never sampled out. */
|
||||
readonly sampleRate: number;
|
||||
readonly payload?: TelemetryPayloadBudget;
|
||||
}
|
||||
|
||||
export const DEFAULT_TELEMETRY_PIPELINE_BUDGET: TelemetryPipelineBudget =
|
||||
Object.freeze({
|
||||
maxBufferedEvents: 200,
|
||||
maxBufferedBytes: 256 * 1024,
|
||||
maxBatchEvents: 50,
|
||||
maxSendsPerMinute: 20,
|
||||
dedupWindowMs: 60_000,
|
||||
maxFingerprints: 500,
|
||||
sampleRate: 1,
|
||||
});
|
||||
|
||||
export type TelemetryPipelineStats = Readonly<{
|
||||
accepted: number;
|
||||
invalid: number;
|
||||
deduplicated: number;
|
||||
sampledOut: number;
|
||||
dropped: number;
|
||||
sends: number;
|
||||
failedSends: number;
|
||||
buffered: number;
|
||||
bufferedBytes: number;
|
||||
peakBuffered: number;
|
||||
fingerprints: number;
|
||||
}>;
|
||||
|
||||
export interface TelemetryPipeline extends TelemetryPort {
|
||||
emit(event: TelemetryEvent<unknown>): Promise<void>;
|
||||
flush(): Promise<void>;
|
||||
stats(): TelemetryPipelineStats;
|
||||
dispose(): void;
|
||||
}
|
||||
|
||||
const RATE_WINDOW_MS = 60_000;
|
||||
|
||||
function assertPositive(name: string, value: number): void {
|
||||
if (!Number.isSafeInteger(value) || value < 1) {
|
||||
throw new TypeError(`telemetry budget ${name} must be a positive safe integer: ${value}`);
|
||||
}
|
||||
}
|
||||
|
||||
export function createTelemetryPipeline(
|
||||
options: Readonly<{
|
||||
transport: TelemetryTransport;
|
||||
budget?: TelemetryPipelineBudget;
|
||||
/** Monotonic clock. */
|
||||
now?: () => number;
|
||||
/** Schedules a flush soon (default: microtask). */
|
||||
schedule?: (callback: () => void) => void;
|
||||
/** Schedules a flush after a rate window reopens (default: setTimeout). */
|
||||
setTimer?: (callback: () => void, ms: number) => unknown;
|
||||
clearTimer?: (handle: unknown) => void;
|
||||
}>,
|
||||
): TelemetryPipeline {
|
||||
const budget = options.budget ?? DEFAULT_TELEMETRY_PIPELINE_BUDGET;
|
||||
assertPositive("maxBufferedEvents", budget.maxBufferedEvents);
|
||||
assertPositive("maxBufferedBytes", budget.maxBufferedBytes);
|
||||
assertPositive("maxBatchEvents", budget.maxBatchEvents);
|
||||
assertPositive("maxSendsPerMinute", budget.maxSendsPerMinute);
|
||||
const payloadBudget = budget.payload ?? DEFAULT_TELEMETRY_PAYLOAD_BUDGET;
|
||||
const now = options.now ?? (() => performance.now());
|
||||
const schedule = options.schedule ?? queueMicrotask;
|
||||
const setTimer =
|
||||
options.setTimer ??
|
||||
((callback: () => void, ms: number) => setTimeout(callback, ms));
|
||||
const clearTimer =
|
||||
options.clearTimer ??
|
||||
((handle: unknown) => clearTimeout(handle as ReturnType<typeof setTimeout>));
|
||||
|
||||
const dedup = new TelemetryDeduplicator({
|
||||
maxEntries: budget.maxFingerprints,
|
||||
windowMs: budget.dedupWindowMs,
|
||||
});
|
||||
const sampler = createDeterministicSampler({ rate: budget.sampleRate });
|
||||
const buffer = createTelemetryBuffer({
|
||||
maxEvents: budget.maxBufferedEvents,
|
||||
maxBytes: budget.maxBufferedBytes,
|
||||
});
|
||||
/** Send timestamps inside the current rate window; never above the limit. */
|
||||
const sendTimes: number[] = [];
|
||||
|
||||
let disposed = false;
|
||||
let flushScheduled = false;
|
||||
let rateTimer: unknown = null;
|
||||
let activeFlush: Promise<void> | null = null;
|
||||
const counters = {
|
||||
accepted: 0,
|
||||
invalid: 0,
|
||||
deduplicated: 0,
|
||||
sampledOut: 0,
|
||||
sends: 0,
|
||||
failedSends: 0,
|
||||
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 {
|
||||
if (rateTimer !== null || disposed) return;
|
||||
const reopenIn = Math.max(1, (sendTimes[0] ?? at) + RATE_WINDOW_MS - at);
|
||||
rateTimer = setTimer(() => {
|
||||
rateTimer = null;
|
||||
void flush();
|
||||
}, reopenIn);
|
||||
}
|
||||
|
||||
function scheduleFlush(): void {
|
||||
if (flushScheduled || disposed) return;
|
||||
flushScheduled = true;
|
||||
schedule(() => {
|
||||
flushScheduled = false;
|
||||
void flush();
|
||||
});
|
||||
}
|
||||
|
||||
async function drain(): Promise<void> {
|
||||
while (!disposed && buffer.size > 0) {
|
||||
const at = now();
|
||||
if (!rateAllows(at)) {
|
||||
armRateTimer(at);
|
||||
return;
|
||||
}
|
||||
const batch = buffer.take(budget.maxBatchEvents).map((entry) =>
|
||||
Object.freeze({
|
||||
event: entry.event,
|
||||
fingerprint: entry.fingerprint ?? "",
|
||||
occurrences: Math.max(1, dedup.count(entry.fingerprint ?? "")),
|
||||
}),
|
||||
);
|
||||
sendTimes.push(at);
|
||||
counters.sends += 1;
|
||||
try {
|
||||
await options.transport.send(batch);
|
||||
} catch {
|
||||
// Best effort: a failed batch is counted, never retried unboundedly.
|
||||
counters.failedSends += batch.length;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
function flush(): Promise<void> {
|
||||
if (activeFlush) return activeFlush;
|
||||
if (disposed || buffer.size === 0) return Promise.resolve();
|
||||
activeFlush = drain()
|
||||
.catch(() => undefined)
|
||||
.finally(() => {
|
||||
activeFlush = null;
|
||||
});
|
||||
return activeFlush;
|
||||
}
|
||||
|
||||
function admit(event: TelemetryEvent<unknown>): void {
|
||||
if (disposed) return;
|
||||
if (!isTelemetryEnvelopeValid(event)) {
|
||||
counters.invalid += 1;
|
||||
return;
|
||||
}
|
||||
// 1. redact (before anything is retained)
|
||||
const redacted: TelemetryEvent<unknown> = Object.freeze({
|
||||
kind: event.kind,
|
||||
severity: event.severity,
|
||||
...(event.contextId === undefined ? {} : { contextId: event.contextId }),
|
||||
...(event.featureId === undefined ? {} : { featureId: event.featureId }),
|
||||
...(event.interactionId === undefined
|
||||
? {}
|
||||
: { interactionId: event.interactionId }),
|
||||
...(event.traceId === undefined ? {} : { traceId: event.traceId }),
|
||||
...(event.payload === undefined
|
||||
? {}
|
||||
: { payload: redactTelemetryPayload(event.payload, payloadBudget) }),
|
||||
});
|
||||
// 2. fingerprint 3. deduplicate
|
||||
const fingerprint = fingerprintTelemetryEvent(redacted);
|
||||
if (!dedup.record(fingerprint, now())) {
|
||||
counters.deduplicated += 1;
|
||||
return;
|
||||
}
|
||||
// 4. sample (deterministic by interaction; severe events always kept)
|
||||
if (
|
||||
TELEMETRY_SEVERITY_RANK[redacted.severity] < TELEMETRY_SEVERITY_RANK.error &&
|
||||
!sampler.keep(redacted.interactionId ?? fingerprint)
|
||||
) {
|
||||
counters.sampledOut += 1;
|
||||
return;
|
||||
}
|
||||
// 5. buffer
|
||||
if (buffer.push(redacted, estimateTelemetryBytes(redacted), fingerprint)) {
|
||||
counters.accepted += 1;
|
||||
counters.peakBuffered = Math.max(counters.peakBuffered, buffer.size);
|
||||
}
|
||||
// 6-8. rate limit, batch and transport happen on flush.
|
||||
scheduleFlush();
|
||||
}
|
||||
|
||||
return Object.freeze({
|
||||
emit(event: TelemetryEvent<unknown>): Promise<void> {
|
||||
try {
|
||||
admit(event);
|
||||
} catch {
|
||||
counters.invalid += 1;
|
||||
}
|
||||
return Promise.resolve();
|
||||
},
|
||||
flush,
|
||||
stats(): TelemetryPipelineStats {
|
||||
return Object.freeze({
|
||||
accepted: counters.accepted,
|
||||
invalid: counters.invalid,
|
||||
deduplicated: counters.deduplicated,
|
||||
sampledOut: counters.sampledOut,
|
||||
dropped: buffer.dropped + counters.failedSends + counters.invalid,
|
||||
sends: counters.sends,
|
||||
failedSends: counters.failedSends,
|
||||
buffered: buffer.size,
|
||||
bufferedBytes: buffer.bytes,
|
||||
peakBuffered: counters.peakBuffered,
|
||||
fingerprints: dedup.size,
|
||||
});
|
||||
},
|
||||
dispose(): void {
|
||||
if (disposed) return;
|
||||
disposed = true;
|
||||
if (rateTimer !== null) clearTimer(rateTimer);
|
||||
rateTimer = null;
|
||||
buffer.clear();
|
||||
},
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,35 @@
|
||||
import type { TelemetryEvent } from "./telemetry-event.ts";
|
||||
|
||||
/**
|
||||
* Spec §24. The only observability surface feature code may use.
|
||||
*
|
||||
* `emit` is best-effort: an implementation must never throw or reject into
|
||||
* business behavior. Vendor SDKs live behind an adapter-side transport, never
|
||||
* in feature code.
|
||||
*/
|
||||
export interface TelemetryPort {
|
||||
emit(event: TelemetryEvent<unknown>): void | Promise<void>;
|
||||
}
|
||||
|
||||
export const NO_OP_TELEMETRY_PORT: TelemetryPort = Object.freeze({
|
||||
emit() {},
|
||||
});
|
||||
|
||||
/**
|
||||
* Wraps any port so that a synchronous throw or an asynchronous rejection is
|
||||
* contained at the call site (spec §26).
|
||||
*/
|
||||
export function failOpenTelemetryPort(port: TelemetryPort): TelemetryPort {
|
||||
return Object.freeze({
|
||||
emit(event: TelemetryEvent<unknown>): Promise<void> {
|
||||
try {
|
||||
return Promise.resolve(port.emit(event)).then(
|
||||
() => undefined,
|
||||
() => undefined,
|
||||
);
|
||||
} catch {
|
||||
return Promise.resolve();
|
||||
}
|
||||
},
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,32 @@
|
||||
import { stableHash64 } from "./telemetry-fingerprint.ts";
|
||||
|
||||
/**
|
||||
* Spec §25. Deterministic sampling by a stable key (interaction or trace id).
|
||||
*
|
||||
* The same key always yields the same decision, so one interaction's events
|
||||
* are kept or dropped together instead of producing partial traces.
|
||||
*/
|
||||
export interface TelemetrySampler {
|
||||
readonly rate: number;
|
||||
keep(key: string): boolean;
|
||||
}
|
||||
|
||||
export function createDeterministicSampler(
|
||||
options: Readonly<{ rate: number }>,
|
||||
): TelemetrySampler {
|
||||
const { rate } = options;
|
||||
if (!Number.isFinite(rate) || rate < 0 || rate > 1) {
|
||||
throw new TypeError(`sampling rate must be within [0, 1]: ${rate}`);
|
||||
}
|
||||
// 32-bit bucket from the stable hash; exact at the 0 and 1 edges.
|
||||
const threshold = Math.floor(rate * 0x1_0000_0000);
|
||||
return Object.freeze({
|
||||
rate,
|
||||
keep(key: string): boolean {
|
||||
if (rate >= 1) return true;
|
||||
if (rate <= 0) return false;
|
||||
const bucket = Number.parseInt(stableHash64(key).slice(0, 8), 16);
|
||||
return bucket < threshold;
|
||||
},
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,103 @@
|
||||
/**
|
||||
* Spec §29. One interaction trace identity propagated to every child request.
|
||||
*
|
||||
* The header names follow the conventions already in the repository: the W3C
|
||||
* `traceparent` (validated by `safeTraceparent` in the telemetry adapter) and
|
||||
* the `x-correlation-id` the HTTP runtime already reads back from responses.
|
||||
* No second, competing correlation header is introduced.
|
||||
*/
|
||||
export const TRACEPARENT_HEADER = "traceparent";
|
||||
export const CORRELATION_ID_HEADER = "x-correlation-id";
|
||||
|
||||
export type TraceContext = Readonly<{
|
||||
traceId: string;
|
||||
spanId: string;
|
||||
sampled: boolean;
|
||||
traceparent: string;
|
||||
}>;
|
||||
|
||||
const TRACE_ID = /^[0-9a-f]{32}$/u;
|
||||
const SPAN_ID = /^[0-9a-f]{16}$/u;
|
||||
const CORRELATION_ID = /^[A-Za-z0-9._:-]{1,128}$/u;
|
||||
|
||||
export function isValidTraceId(value: string): boolean {
|
||||
return TRACE_ID.test(value) && !/^0+$/u.test(value);
|
||||
}
|
||||
|
||||
export function isValidSpanId(value: string): boolean {
|
||||
return SPAN_ID.test(value) && !/^0+$/u.test(value);
|
||||
}
|
||||
|
||||
function randomHex(bytes: number, random: () => number): string {
|
||||
let out = "";
|
||||
for (let index = 0; index < bytes; index += 1) {
|
||||
out += Math.floor(random() * 256)
|
||||
.toString(16)
|
||||
.padStart(2, "0");
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function secureRandomHex(bytes: number): string {
|
||||
const buffer = new Uint8Array(bytes);
|
||||
globalThis.crypto.getRandomValues(buffer);
|
||||
return Array.from(buffer, (byte) => byte.toString(16).padStart(2, "0")).join("");
|
||||
}
|
||||
|
||||
export function createTraceContext(
|
||||
options: Readonly<{
|
||||
traceId?: string;
|
||||
spanId?: string;
|
||||
sampled?: boolean;
|
||||
/** Test seam; production uses `crypto.getRandomValues`. */
|
||||
random?: () => number;
|
||||
}> = {},
|
||||
): TraceContext {
|
||||
const generate = (bytes: number) =>
|
||||
options.random ? randomHex(bytes, options.random) : secureRandomHex(bytes);
|
||||
let traceId = options.traceId ?? generate(16);
|
||||
let spanId = options.spanId ?? generate(8);
|
||||
if (!isValidTraceId(traceId)) {
|
||||
if (options.traceId !== undefined) {
|
||||
throw new TypeError("traceId must be 32 lowercase hex characters, not all zero");
|
||||
}
|
||||
traceId = `${traceId.slice(0, 31)}1`;
|
||||
}
|
||||
if (!isValidSpanId(spanId)) {
|
||||
if (options.spanId !== undefined) {
|
||||
throw new TypeError("spanId must be 16 lowercase hex characters, not all zero");
|
||||
}
|
||||
spanId = `${spanId.slice(0, 15)}1`;
|
||||
}
|
||||
const sampled = options.sampled ?? true;
|
||||
return Object.freeze({
|
||||
traceId,
|
||||
spanId,
|
||||
sampled,
|
||||
traceparent: `00-${traceId}-${spanId}-${sampled ? "01" : "00"}`,
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* The trace/correlation headers for one physical request. Every child request
|
||||
* of the same interaction carries the same `traceparent` and correlation id.
|
||||
*/
|
||||
export function buildTraceHeaders(
|
||||
context: Readonly<{
|
||||
interaction: Readonly<{ id: string }>;
|
||||
trace?: TraceContext;
|
||||
}>,
|
||||
): Readonly<Record<string, string>> {
|
||||
const headers: Record<string, string> = {};
|
||||
if (CORRELATION_ID.test(context.interaction.id)) {
|
||||
headers[CORRELATION_ID_HEADER] = context.interaction.id;
|
||||
}
|
||||
if (context.trace) headers[TRACEPARENT_HEADER] = context.trace.traceparent;
|
||||
return Object.freeze(headers);
|
||||
}
|
||||
|
||||
export function buildRequestHeaders(
|
||||
context: Parameters<typeof buildTraceHeaders>[0],
|
||||
): Headers {
|
||||
return new Headers(buildTraceHeaders(context));
|
||||
}
|
||||
Reference in New Issue
Block a user