@nodii/telemetry 0.0.2 → 0.3.0

package/dist/redaction.js

@@ -0,0 +1,173 @@
+// PII redaction per D15. SDK-side canonical, fail-closed. Two passes:
+//   1. Structured-field-key match against D2 PII list.
+//   2. Regex pass on the message string.
+//
+// On exception during redaction: the line is DROPPED and a
+// `telemetry.sdk.redaction_failure_total{reason}` counter increments. We
+// surface that counter via the metrics module (§ 5.4); this module just
+// reports the drop + reason via `attemptRedaction` returning a tagged
+// result. The collector-side pass (D59) is defense-in-depth — the
+// SDK-side pass is canonical.
+const REDACTED = "[REDACTED]";
+/**
+ * D2 PII field-name allowlist. Keys whose name matches one of these
+ * (case-insensitive) get their value stripped to `[REDACTED]` before
+ * the log/span attribute is emitted.
+ *
+ * Source: the legacy telemetry doctrine D2 PII list, transcribed for
+ * v0.1.0. Adding new keys is an ADR-gated change.
+ */
+export const PII_FIELD_NAMES = [
+    "password",
+    "passwd",
+    "secret",
+    "token",
+    "access_token",
+    "refresh_token",
+    "id_token",
+    "api_key",
+    "apikey",
+    "private_key",
+    "client_secret",
+    "session_id",
+    "cookie",
+    "authorization",
+    "ssn",
+    "tax_id",
+    "pan",
+    "aadhaar",
+    "credit_card",
+    "card_number",
+    "cvv",
+    "iban",
+    "account_number",
+    "routing_number",
+    "phone",
+    "phone_number",
+    "mobile",
+    "email",
+    "email_address",
+    "address",
+    "street",
+    "postal_code",
+    "zip",
+    "dob",
+    "date_of_birth",
+    "first_name",
+    "last_name",
+    "full_name",
+    "passport",
+    "drivers_license",
+];
+const PII_FIELD_SET = new Set(PII_FIELD_NAMES.map((s) => s.toLowerCase()));
+/**
+ * D15 regex pass — runs on `msg` strings (logs) and span attribute
+ * values when their key doesn't match a structured PII key but the
+ * value looks like a known PII pattern.
+ *
+ * Each regex is anchored loosely; matches are replaced with [REDACTED].
+ * Order matters: more-specific patterns first.
+ */
+const REGEX_PATTERNS = [
+    // Bearer tokens / JWT-shaped: 3 base64-ish segments separated by dots.
+    {
+        name: "jwt",
+        re: /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g,
+    },
+    // Credit-card-like: 13–19 digits, possibly grouped by spaces or dashes.
+    {
+        name: "credit_card",
+        re: /\b(?:\d[ -]?){13,19}\b/g,
+    },
+    // Email addresses.
+    {
+        name: "email",
+        re: /\b[\w.!#$%&'*+/=?^`{|}~-]+@[\w-]+(?:\.[\w-]+)+\b/g,
+    },
+    // SSN-like: NNN-NN-NNNN.
+    {
+        name: "ssn",
+        re: /\b\d{3}-\d{2}-\d{4}\b/g,
+    },
+    // Phone-like (loose, intl): + then 10–15 digits with optional dashes/spaces.
+    {
+        name: "phone_intl",
+        re: /\+(?:\d[ -]?){10,15}\b/g,
+    },
+];
+/**
+ * Returns true iff the key name matches the D2 PII field-name list.
+ * Comparison is case-insensitive on the bare key (no normalization
+ * beyond `toLowerCase()`).
+ */
+export function isPiiFieldName(key) {
+    return PII_FIELD_SET.has(key.toLowerCase());
+}
+/**
+ * Redacts an arbitrary record by replacing values whose keys match the
+ * D2 PII list with `[REDACTED]`. Nested records are walked recursively.
+ * Arrays are walked element-by-element. Primitives at the top level are
+ * returned untouched (this function is for records only).
+ *
+ * Throws nothing under normal input; if a value is a non-serializable
+ * object (e.g. circular reference encountered via JSON.stringify
+ * elsewhere) the caller wraps this in `attemptRedaction()` to catch.
+ */
+export function redactFields(input) {
+    const out = {};
+    for (const [k, v] of Object.entries(input)) {
+        if (isPiiFieldName(k)) {
+            out[k] = REDACTED;
+            continue;
+        }
+        out[k] = redactValue(v);
+    }
+    return out;
+}
+function redactValue(v) {
+    if (v === null || v === undefined)
+        return v;
+    if (typeof v === "string")
+        return redactString(v);
+    if (Array.isArray(v))
+        return v.map(redactValue);
+    if (typeof v === "object") {
+        return redactFields(v);
+    }
+    return v;
+}
+/**
+ * Apply the D15 regex pass to a string. Returns the redacted string.
+ * Each pattern that fires replaces its match with [REDACTED]; multiple
+ * matches per string are all replaced.
+ */
+export function redactString(s) {
+    let out = s;
+    for (const { re } of REGEX_PATTERNS) {
+        out = out.replace(re, REDACTED);
+    }
+    return out;
+}
+export function attemptRedactFields(input) {
+    try {
+        return { ok: true, redacted: redactFields(input) };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            reason: err instanceof Error ? err.name : "redaction_error",
+        };
+    }
+}
+export function attemptRedactString(s) {
+    try {
+        return { ok: true, redacted: redactString(s) };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            reason: err instanceof Error ? err.name : "redaction_error",
+        };
+    }
+}
+//# sourceMappingURL=redaction.js.map

package/dist/redaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redaction.js","sourceRoot":"","sources":["../src/redaction.ts"],"names":[],"mappings":"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"}

package/dist/sdk-counters.d.ts

@@ -0,0 +1,14 @@
+type LabelMap = Record<string, string>;
+interface CounterPoint {
+    name: string;
+    labels: LabelMap;
+    value: number;
+}
+/** Increment by 1 (default) or by `n`. Internal SDK use. */
+export declare function incSdkCounter(name: string, labels?: LabelMap, n?: number): void;
+/** Snapshot — used by the metrics flush path + tests. */
+export declare function snapshotSdkCounters(): readonly CounterPoint[];
+/** Test-only reset. NOT exported via the public barrel. */
+export declare function _resetSdkCountersForTests(): void;
+export {};
+//# sourceMappingURL=sdk-counters.d.ts.map

package/dist/sdk-counters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-counters.d.ts","sourceRoot":"","sources":["../src/sdk-counters.ts"],"names":[],"mappings":"AAWA,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEvC,UAAU,YAAY;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,QAAQ,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAYD,4DAA4D;AAC5D,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,QAAa,EACrB,CAAC,SAAI,GACJ,IAAI,CAQN;AAED,yDAAyD;AACzD,wBAAgB,mBAAmB,IAAI,SAAS,YAAY,EAAE,CAM7D;AAED,2DAA2D;AAC3D,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD"}

package/dist/sdk-counters.js

@@ -0,0 +1,42 @@
+// SDK-internal observability counters. These exist BEFORE the public
+// metrics API is wired (because the metrics module itself may report
+// failures through them), so they are intentionally a tiny in-process
+// map with a flush hook the metrics module reads.
+//
+// Counter names (locked):
+//   - `telemetry.sdk.redaction_failure_total{reason}` (D15 fail-closed drop)
+//   - `telemetry.sdk.cardinality_rejected_total{family, reason}` (D18)
+//   - `telemetry.sdk.export_failures_total{signal, reason}` (D153)
+//   - `telemetry.sdk.trace_propagation_missing_total` (§ 5.9)
+const points = new Map();
+function keyFor(name, labels) {
+    const labelStr = Object.entries(labels)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([k, v]) => `${k}=${v}`)
+        .join(",");
+    return `${name}|${labelStr}`;
+}
+/** Increment by 1 (default) or by `n`. Internal SDK use. */
+export function incSdkCounter(name, labels = {}, n = 1) {
+    const k = keyFor(name, labels);
+    const existing = points.get(k);
+    if (existing) {
+        existing.value += n;
+    }
+    else {
+        points.set(k, { name, labels, value: n });
+    }
+}
+/** Snapshot — used by the metrics flush path + tests. */
+export function snapshotSdkCounters() {
+    return Array.from(points.values()).map((p) => ({
+        name: p.name,
+        labels: { ...p.labels },
+        value: p.value,
+    }));
+}
+/** Test-only reset. NOT exported via the public barrel. */
+export function _resetSdkCountersForTests() {
+    points.clear();
+}
+//# sourceMappingURL=sdk-counters.js.map

package/dist/sdk-counters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-counters.js","sourceRoot":"","sources":["../src/sdk-counters.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,qEAAqE;AACrE,sEAAsE;AACtE,kDAAkD;AAClD,EAAE;AACF,0BAA0B;AAC1B,6EAA6E;AAC7E,uEAAuE;AACvE,mEAAmE;AACnE,8DAA8D;AAU9D,MAAM,MAAM,GAAG,IAAI,GAAG,EAAwB,CAAC;AAE/C,SAAS,MAAM,CAAC,IAAY,EAAE,MAAgB;IAC5C,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;SACpC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;SACtC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;SAC5B,IAAI,CAAC,GAAG,CAAC,CAAC;IACb,OAAO,GAAG,IAAI,IAAI,QAAQ,EAAE,CAAC;AAC/B,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,aAAa,CAC3B,IAAY,EACZ,SAAmB,EAAE,EACrB,CAAC,GAAG,CAAC;IAEL,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC/B,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC/B,IAAI,QAAQ,EAAE,CAAC;QACb,QAAQ,CAAC,KAAK,IAAI,CAAC,CAAC;IACtB,CAAC;SAAM,CAAC;QACN,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;IAC5C,CAAC;AACH,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,mBAAmB;IACjC,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC7C,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,MAAM,EAAE,EAAE,GAAG,CAAC,CAAC,MAAM,EAAE;QACvB,KAAK,EAAE,CAAC,CAAC,KAAK;KACf,CAAC,CAAC,CAAC;AACN,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,yBAAyB;IACvC,MAAM,CAAC,KAAK,EAAE,CAAC;AACjB,CAAC"}

package/dist/tracer.d.ts

@@ -0,0 +1,63 @@
+export type SpanKind = "INTERNAL" | "SERVER" | "CLIENT" | "PRODUCER" | "CONSUMER";
+export type SpanStatus = "UNSET" | "OK" | "ERROR";
+export interface SpanRecord {
+    trace_id: string;
+    span_id: string;
+    parent_span_id: string | null;
+    name: string;
+    kind: SpanKind;
+    start_ns: bigint;
+    end_ns: bigint;
+    attributes: Record<string, unknown>;
+    status: SpanStatus;
+    status_message?: string;
+    events: SpanEvent[];
+}
+export interface SpanEvent {
+    name: string;
+    ts_ns: bigint;
+    attributes?: Record<string, unknown>;
+}
+/** Per-span handle the caller manipulates while the span is live. */
+export interface Span {
+    readonly trace_id: string;
+    readonly span_id: string;
+    setAttribute(key: string, value: unknown): void;
+    setAttributes(attrs: Record<string, unknown>): void;
+    addEvent(name: string, attributes?: Record<string, unknown>): void;
+    recordException(err: unknown): void;
+    setStatus(status: SpanStatus, message?: string): void;
+}
+/** Backend hook. TS-12 replaces the no-op with the OTel emitter. */
+export interface SpanEmitter {
+    emit(record: SpanRecord): void;
+}
+export declare function _setSpanEmitter(e: SpanEmitter): void;
+export declare function _resetSpanEmitterForTests(): void;
+/**
+ * `tracer.span(name, fn)` opens a span, runs `fn`, then closes the
+ * span. Mandatory attributes stamped on start; D27 status mapping
+ * applied automatically.
+ */
+declare function span<T>(name: string, fn: (span: Span) => Promise<T> | T, opts?: {
+    kind?: SpanKind;
+    attributes?: Record<string, unknown>;
+}): Promise<T>;
+declare function withSpanAttributes<T>(attrs: Record<string, unknown>, fn: () => Promise<T> | T): Promise<T> | T;
+/**
+ * `getSagaTracer()` — tactical hold per D149. Returns a tracer whose
+ * spans default to the SAGA shape (INTERNAL, parent=SERVER subtree).
+ * Sunsets at v0.2.0 when every service in D169 has adopted `@nodii/saga`.
+ */
+declare function getSagaTracer(): {
+    span<T>(name: string, fn: (span: Span) => Promise<T> | T, opts?: {
+        attributes?: Record<string, unknown>;
+    }): Promise<T>;
+};
+/** Test-only reset of active span stack. */
+export declare function _resetTracerStackForTests(): void;
+export declare const tracer: {
+    readonly span: typeof span;
+};
+export { withSpanAttributes, getSagaTracer };
+//# sourceMappingURL=tracer.d.ts.map

package/dist/tracer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracer.d.ts","sourceRoot":"","sources":["../src/tracer.ts"],"names":[],"mappings":"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"}

package/dist/tracer.js

@@ -0,0 +1,214 @@
+// Tracer per D26 / D27 / D28 / D30. Surface only; the real OTel wiring
+// lands in TS-12 by replacing the in-process `SpanEmitter` via
+// `_setSpanEmitter`. The default emitter is a no-op so tests can run
+// without an OTLP endpoint.
+//
+// What's locked at v0.1.0:
+//   - `NodiiContextSpanProcessor` semantics in `_emitSpan`: stamps the
+//     three mandatory attributes (`tenant_id, request_id, intent_id`)
+//     onto every span on start (D26).
+//   - 4 KB per-value cap on attributes (truncates with `_truncated`
+//     marker). PII redaction applied to attribute values in `onEnd`
+//     (D26 + D15).
+//   - Status mapping (D27): if `recordException` ran or any error was
+//     attached, the span ends with status ERROR; otherwise UNSET.
+//   - `getSagaTracer()` ships as a tactical hold per D149; sunsets at
+//     v0.2.0.
+import { getContext } from "./context";
+import { _setActiveSpanGetter } from "./active-span";
+import { attemptRedactFields } from "./redaction";
+import { incSdkCounter } from "./sdk-counters";
+import { uuidv7 } from "./uuid";
+const noopEmitter = {
+    emit() {
+        /* no-op; TS-12 replaces */
+    },
+};
+let emitter = noopEmitter;
+export function _setSpanEmitter(e) {
+    emitter = e;
+}
+export function _resetSpanEmitterForTests() {
+    emitter = noopEmitter;
+}
+const ATTR_VALUE_CAP_BYTES = 4 * 1024;
+function capValue(v) {
+    if (typeof v !== "string")
+        return v;
+    if (Buffer.byteLength(v, "utf8") <= ATTR_VALUE_CAP_BYTES)
+        return v;
+    // Truncate by bytes — slice to the cap, mark.
+    const truncated = Buffer.from(v, "utf8")
+        .subarray(0, ATTR_VALUE_CAP_BYTES)
+        .toString("utf8");
+    return `${truncated}[_truncated=true]`;
+}
+function capAttributes(attrs) {
+    const out = {};
+    for (const [k, v] of Object.entries(attrs))
+        out[k] = capValue(v);
+    return out;
+}
+/** Stack of active spans (per-async-scope discipline is ALS, not this stack). */
+const activeStack = [];
+// Wire the active-span getter so logger.ts can stamp trace_id / span_id.
+_setActiveSpanGetter(() => {
+    const top = activeStack[activeStack.length - 1];
+    if (!top)
+        return null;
+    return { trace_id: top.trace_id, span_id: top.span_id };
+});
+/**
+ * `tracer.span(name, fn)` opens a span, runs `fn`, then closes the
+ * span. Mandatory attributes stamped on start; D27 status mapping
+ * applied automatically.
+ */
+async function span(name, fn, opts) {
+    const ctx = getContext();
+    const parent = activeStack[activeStack.length - 1];
+    const traceId = parent ? parent.trace_id : newTraceId();
+    const spanId = newSpanId();
+    const startNs = process.hrtime.bigint();
+    // D26 mandatory attributes envelope. tenant_id and request_id come
+    // from NodiiContext when present.
+    const record = {
+        trace_id: traceId,
+        span_id: spanId,
+        parent_span_id: parent?.span_id ?? null,
+        name,
+        kind: opts?.kind ?? "INTERNAL",
+        start_ns: startNs,
+        end_ns: 0n,
+        attributes: {
+            ...(ctx
+                ? {
+                    tenant_id: ctx.tenant_id,
+                    request_id: ctx.request_id,
+                    intent_id: ctx.intent_id,
+                }
+                : {}),
+            ...(opts?.attributes ? capAttributes(opts.attributes) : {}),
+        },
+        status: "UNSET",
+        events: [],
+    };
+    activeStack.push(record);
+    let recordedException = false;
+    const handle = {
+        trace_id: traceId,
+        span_id: spanId,
+        setAttribute(key, value) {
+            record.attributes[key] = capValue(value);
+        },
+        setAttributes(attrs) {
+            Object.assign(record.attributes, capAttributes(attrs));
+        },
+        addEvent(eventName, attributes) {
+            record.events.push({
+                name: eventName,
+                ts_ns: process.hrtime.bigint(),
+                attributes,
+            });
+        },
+        recordException(err) {
+            recordedException = true;
+            const message = err instanceof Error ? err.message : String(err);
+            const stack = err instanceof Error ? err.stack : undefined;
+            record.events.push({
+                name: "exception",
+                ts_ns: process.hrtime.bigint(),
+                attributes: {
+                    "exception.message": capValue(message),
+                    "exception.stacktrace": stack ? capValue(stack) : undefined,
+                },
+            });
+        },
+        setStatus(status, message) {
+            record.status = status;
+            record.status_message = message;
+        },
+    };
+    try {
+        const result = await fn(handle);
+        if (record.status === "UNSET")
+            record.status = "OK";
+        return result;
+    }
+    catch (err) {
+        handle.recordException(err);
+        record.status = "ERROR";
+        throw err;
+    }
+    finally {
+        if (recordedException && record.status !== "ERROR") {
+            // D27: recordException auto-paired with ERROR.
+            record.status = "ERROR";
+        }
+        record.end_ns = process.hrtime.bigint();
+        // D26 onEnd: PII redaction over attribute values. Fail-closed: if
+        // redaction throws, drop the span by NOT emitting + bump the
+        // counter. (We still pop the stack regardless.)
+        const redacted = attemptRedactFields(record.attributes);
+        if (redacted.ok) {
+            record.attributes = redacted.redacted;
+            emitter.emit(record);
+        }
+        else {
+            incSdkCounter("telemetry.sdk.redaction_failure_total", {
+                reason: redacted.reason,
+            });
+        }
+        activeStack.pop();
+    }
+}
+function newTraceId() {
+    // OTel trace_id is 16 bytes (32 hex). Reuse uuidv7's randomness path
+    // by stripping dashes from a fresh v7.
+    return uuidv7().replace(/-/g, "");
+}
+function newSpanId() {
+    // OTel span_id is 8 bytes (16 hex). Take the trailing 16 hex chars
+    // of a uuidv7 (the random tail, not the timestamp).
+    return uuidv7().replace(/-/g, "").slice(16, 32);
+}
+/**
+ * `withSpanAttributes` per D149 § 5.3 ergonomic helper. Wraps a block
+ * so that every span opened inside it gets the supplied attributes
+ * merged onto its attribute envelope. Implementation: stores the
+ * attributes on a stack consulted by `tracer.span` at start.
+ */
+const attrScope = [];
+function withSpanAttributes(attrs, fn) {
+    attrScope.push(attrs);
+    try {
+        return fn();
+    }
+    finally {
+        attrScope.pop();
+    }
+}
+/**
+ * `getSagaTracer()` — tactical hold per D149. Returns a tracer whose
+ * spans default to the SAGA shape (INTERNAL, parent=SERVER subtree).
+ * Sunsets at v0.2.0 when every service in D169 has adopted `@nodii/saga`.
+ */
+function getSagaTracer() {
+    return {
+        span(name, fn, opts) {
+            return span(name, fn, {
+                kind: "INTERNAL",
+                attributes: { "saga.tactical_hold": true, ...(opts?.attributes ?? {}) },
+            });
+        },
+    };
+}
+/** Test-only reset of active span stack. */
+export function _resetTracerStackForTests() {
+    activeStack.length = 0;
+    attrScope.length = 0;
+}
+export const tracer = {
+    span,
+};
+export { withSpanAttributes, getSagaTracer };
+//# sourceMappingURL=tracer.js.map

package/dist/tracer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracer.js","sourceRoot":"","sources":["../src/tracer.ts"],"names":[],"mappings":"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"}