@nodii/telemetry 0.0.2 → 0.3.0

package/dist/intent.js

@@ -0,0 +1,123 @@
+// Intent lifecycle per D46 + D155.
+//
+// API: `intent.begin/progress/complete/abandon/current`.
+//   begin     sync UUIDv7 mint + async outbox `core.intent.begun.v1`;
+//             HARD validates against intent_types registry (D155).
+//             Activates ALS context: sets `intent_id` on the current
+//             NodiiContext via `_setIntentIdInCurrentScope`.
+//   progress  no-op stub at v0.1.0 per M02 carry-forward (D155). Kept
+//             on the surface so callers don't break when the real
+//             behavior lands.
+//   complete  emits outbox `core.intent.completed.v1`; deactivates
+//             context (intent_id back to null OR to the parent in the
+//             nested-begin stack, see below).
+//   abandon   emits outbox `core.intent.abandoned.v1`; deactivates
+//             context same as complete.
+//   current   sync ALS read; returns the active intent_id or null.
+//
+// Nested begins stack by ID match (D155). The library tracks an
+// in-process stack keyed by trailing intent_id; complete/abandon pop
+// the matching entry. If a complete/abandon arrives for an id not at
+// the top of the stack, we still emit the event but log a warning —
+// nested-begin discipline is a caller-side rule.
+import { _setIntentIdInCurrentScope, getContext } from "./context";
+import { requireTelemetry } from "./init";
+import { emitOutbox } from "./outbox-emit";
+import { uuidv7 } from "./uuid";
+/** Per-typeName runtime registry; populated by `initTelemetry`. */
+function intentTypeDef(typeName) {
+    const cfg = requireTelemetry();
+    return cfg.intentTypes[typeName] ?? null;
+}
+const stack = [];
+async function begin(typeName, payload) {
+    const def = intentTypeDef(typeName);
+    if (!def) {
+        throw new IntentTypeNotRegistered(typeName);
+    }
+    // D45/D46 (E5 reframe): per-flow server/client mintable enforcement
+    // is a runtime concern that the gateway / SDK middleware should set
+    // via context; for v0.1.0 we accept all begins from server-side code
+    // and rely on the gateway to mint for HTTP-initiated. The flag is
+    // surfaced on the def so consumers can branch if they need to.
+    const id = uuidv7();
+    stack.push(id);
+    _setIntentIdInCurrentScope(id);
+    await emitOutbox({
+        topic: "core.intent.begun.v1",
+        event_id: id,
+        schema_version: 1,
+        payload: {
+            intent_type: typeName,
+            timeout_seconds: def.timeout_seconds,
+            payload: payload ?? null,
+        },
+    });
+    return id;
+}
+async function complete(id, result) {
+    requireTelemetry();
+    popStack(id, "complete");
+    _setIntentIdInCurrentScope(currentStackTop());
+    await emitOutbox({
+        topic: "core.intent.completed.v1",
+        event_id: id,
+        schema_version: 1,
+        payload: { intent_id: id, result: result ?? null },
+    });
+}
+async function abandon(id, reason) {
+    requireTelemetry();
+    popStack(id, "abandon");
+    _setIntentIdInCurrentScope(currentStackTop());
+    await emitOutbox({
+        topic: "core.intent.abandoned.v1",
+        event_id: id,
+        schema_version: 1,
+        payload: { intent_id: id, reason },
+    });
+}
+function progress(_id, _payload) {
+    // No-op at v0.1.0 per D155 § M02 carry-forward. Surface kept stable
+    // so callers don't break when behavior lands at a later version.
+}
+function current() {
+    return getContext()?.intent_id ?? null;
+}
+function popStack(id, op) {
+    const idx = stack.lastIndexOf(id);
+    if (idx === -1) {
+        // Not in stack — likely a misuse, but per D155 we still emit the
+        // event so the outbox stays a faithful chronology. Log a warning.
+        // eslint-disable-next-line no-console
+        console.warn(`[@nodii/telemetry] intent.${op}(${id}) called but id is not on the active stack; emitting event anyway.`);
+        return;
+    }
+    // Pop entries above this one too (treats out-of-order as orphaned
+    // begins — they get implicitly abandoned for the in-process stack).
+    stack.length = idx;
+}
+function currentStackTop() {
+    return stack.length > 0 ? (stack[stack.length - 1] ?? null) : null;
+}
+/** Thrown by `intent.begin` when the type isn't in the registry (D155 HARD). */
+export class IntentTypeNotRegistered extends Error {
+    typeName;
+    constructor(typeName) {
+        super(`intent type "${typeName}" is not registered. Add it to the intent_types registry passed to initTelemetry().`);
+        this.typeName = typeName;
+        this.name = "IntentTypeNotRegistered";
+    }
+}
+/** Test-only stack reset. */
+export function _resetIntentStackForTests() {
+    stack.length = 0;
+}
+export const intent = {
+    begin,
+    progress,
+    complete,
+    abandon,
+    current,
+};
+//# sourceMappingURL=intent.js.map

package/dist/intent.js.map

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

package/dist/logger.d.ts

@@ -0,0 +1,19 @@
+import type { LogEnvelope } from "./types";
+/** A sink that consumes formed log envelopes. Default = JSON to stdio. */
+export type LogSink = (envelope: LogEnvelope, fields: Record<string, unknown>) => void;
+/**
+ * SDK-internal: the OTel adapter installs an OTLP-log sink in TS-12.
+ * Public callers MUST NOT call this; the override is for internal
+ * substitution only (and tests).
+ */
+export declare function _setLogSink(s: LogSink): void;
+/** Test-only restore. */
+export declare function _resetLogSinkForTests(): void;
+/** D13/D14 logger. Envelope fields are SDK-injected; do not supply them. */
+export declare const logger: {
+    readonly debug: (msg: string, fields?: Record<string, unknown>) => void;
+    readonly info: (msg: string, fields?: Record<string, unknown>) => void;
+    readonly warn: (msg: string, fields?: Record<string, unknown>) => void;
+    readonly error: (msg: string, fields?: Record<string, unknown>) => void;
+};
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,WAAW,EAAY,MAAM,SAAS,CAAC;AAErD,0EAA0E;AAC1E,MAAM,MAAM,OAAO,GAAG,CACpB,QAAQ,EAAE,WAAW,EACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,IAAI,CAAC;AAIV;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAE5C;AAED,yBAAyB;AACzB,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AA+DD,4EAA4E;AAC5E,eAAO,MAAM,MAAM;0BACN,MAAM,WAAW,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,IAAI;yBAGhD,MAAM,WAAW,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,IAAI;yBAG/C,MAAM,WAAW,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,IAAI;0BAG9C,MAAM,WAAW,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,IAAI;CAGlD,CAAC"}

package/dist/logger.js

@@ -0,0 +1,99 @@
+// Logger per D13/D14/D15.
+//
+// API:
+//   logger.debug | info | warn | error (msg, fields?)
+//
+// The 11-field envelope is auto-attached from initTelemetry config +
+// active NodiiContext + active OTel span. Caller passes only `msg` +
+// optional `fields`. Fields go through the D15 redaction passes
+// (structured key + regex on string values) before emission. Failure
+// in either pass = drop the line + bump
+// `telemetry.sdk.redaction_failure_total{reason}` (D15 fail-closed).
+//
+// Sink: the default sink writes JSON to stdout/stderr. Real OTel-LP
+// export wiring is deferred to TS-12; the sink is a single injection
+// point that the OTel adapter replaces.
+import { getActiveSpan } from "./active-span";
+import { getContext } from "./context";
+import { requireTelemetry } from "./init";
+import { attemptRedactFields, attemptRedactString } from "./redaction";
+import { incSdkCounter } from "./sdk-counters";
+let sink = defaultJsonSink;
+/**
+ * SDK-internal: the OTel adapter installs an OTLP-log sink in TS-12.
+ * Public callers MUST NOT call this; the override is for internal
+ * substitution only (and tests).
+ */
+export function _setLogSink(s) {
+    sink = s;
+}
+/** Test-only restore. */
+export function _resetLogSinkForTests() {
+    sink = defaultJsonSink;
+}
+function defaultJsonSink(envelope, fields) {
+    const line = JSON.stringify({ ...envelope, ...fields });
+    if (envelope.level === "error" || envelope.level === "warn") {
+        // eslint-disable-next-line no-console
+        process.stderr.write(`${line}\n`);
+    }
+    else {
+        // eslint-disable-next-line no-console
+        process.stdout.write(`${line}\n`);
+    }
+}
+function emit(level, msg, fields) {
+    const cfg = requireTelemetry();
+    const ctx = getContext();
+    // D15 redaction (fail-closed). Run BOTH passes before forming the
+    // envelope; if either throws, drop the line + bump the counter.
+    const msgResult = attemptRedactString(msg);
+    if (!msgResult.ok) {
+        incSdkCounter("telemetry.sdk.redaction_failure_total", {
+            reason: msgResult.reason,
+        });
+        return;
+    }
+    const fieldsResult = fields
+        ? attemptRedactFields(fields)
+        : { ok: true, redacted: {} };
+    if (!fieldsResult.ok) {
+        incSdkCounter("telemetry.sdk.redaction_failure_total", {
+            reason: fieldsResult.reason,
+        });
+        return;
+    }
+    const span = getActiveSpan();
+    const envelope = {
+        level,
+        ts: new Date().toISOString(),
+        msg: msgResult.redacted,
+        service: cfg.serviceName,
+        env: cfg.env,
+        tenant_id: ctx?.tenant_id ?? "",
+        user_id: ctx?.user_id ?? null,
+        on_behalf_of: ctx?.on_behalf_of ?? null,
+        actor_type: ctx?.actor_type,
+        request_id: ctx?.request_id ?? "",
+        trace_id: span?.trace_id ?? null,
+        span_id: span?.span_id ?? null,
+        intent_id: ctx?.intent_id ?? null,
+    };
+    sink(envelope, fieldsResult.redacted);
+}
+/** D13/D14 logger. Envelope fields are SDK-injected; do not supply them. */
+export const logger = {
+    debug(msg, fields) {
+        emit("debug", msg, fields);
+    },
+    info(msg, fields) {
+        emit("info", msg, fields);
+    },
+    warn(msg, fields) {
+        emit("warn", msg, fields);
+    },
+    error(msg, fields) {
+        emit("error", msg, fields);
+    },
+};
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

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

package/dist/metrics.d.ts

@@ -0,0 +1,53 @@
+import { type MetricFamily } from "./types";
+/** Thrown by `metrics.counter/histogram` when registration is rejected. */
+export declare class MetricVocabularyError extends Error {
+    readonly metric: string;
+    readonly reason: string;
+    constructor(metric: string, reason: string);
+}
+export interface CounterHandle {
+    readonly name: string;
+    readonly family: MetricFamily;
+    readonly description: string;
+    inc(labels?: Record<string, string | number>): void;
+    inc(by: number, labels?: Record<string, string | number>): void;
+}
+export interface HistogramHandle {
+    readonly name: string;
+    readonly family: MetricFamily;
+    readonly description: string;
+    readonly maxBuckets: number;
+    record(value: number, labels?: Record<string, string | number>): void;
+}
+/**
+ * Backend that records the actual data points. The default backend
+ * stores points in-process for tests + the SDK counters; the real OTel
+ * meter wires in via TS-12 by replacing this through `_setBackend`.
+ */
+export interface MetricsBackend {
+    recordCounter(name: string, by: number, labels: Record<string, string | number>): void;
+    recordHistogram(name: string, value: number, labels: Record<string, string | number>): void;
+}
+export declare function _setMetricsBackend(b: MetricsBackend): void;
+export declare function _resetMetricsBackendForTests(): void;
+export interface MetricRegistration {
+    family: MetricFamily;
+    description: string;
+    labelKeys?: readonly string[];
+}
+declare function counter(name: string, reg: MetricRegistration): CounterHandle;
+declare function histogram(name: string, reg: MetricRegistration & {
+    maxBuckets?: number;
+}): HistogramHandle;
+/**
+ * The `metrics.*` namespace (D149 verbatim name). Use:
+ *
+ *   const c = metrics.counter('billing_payments_total', { family: 'async_worker', description: '...' });
+ *   c.inc({ tenant_id, pgw, status });
+ */
+export declare const metrics: {
+    readonly counter: typeof counter;
+    readonly histogram: typeof histogram;
+};
+export {};
+//# sourceMappingURL=metrics.d.ts.map

package/dist/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"AAsBA,OAAO,EAEL,KAAK,YAAY,EAElB,MAAM,SAAS,CAAC;AAEjB,2EAA2E;AAC3E,qBAAa,qBAAsB,SAAQ,KAAK;aAE5B,MAAM,EAAE,MAAM;aACd,MAAM,EAAE,MAAM;gBADd,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM;CAKjC;AAsED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,GAAG,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,IAAI,CAAC;IACpD,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,IAAI,CAAC;CACjE;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,IAAI,CAAC;CACvE;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,aAAa,CACX,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GACtC,IAAI,CAAC;IACR,eAAe,CACb,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GACtC,IAAI,CAAC;CACT;AAaD,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,cAAc,GAAG,IAAI,CAE1D;AAED,wBAAgB,4BAA4B,IAAI,IAAI,CAEnD;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,YAAY,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/B;AAED,iBAAS,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,kBAAkB,GAAG,aAAa,CAwBrE;AAED,iBAAS,SAAS,CAChB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,kBAAkB,GAAG;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAChD,eAAe,CAoBjB;AAED;;;;;GAKG;AACH,eAAO,MAAM,OAAO;;;CAGV,CAAC"}

package/dist/metrics.js

@@ -0,0 +1,152 @@
+// Metrics per D18 / D19 / D20 / D21 / D22 / D23 / D24.
+//
+// Discipline at v0.1.0:
+//   - `metrics.counter()` and `metrics.histogram()` accept a name +
+//     family + description. The name MUST exist in the vocabulary
+//     registry loaded by `initTelemetry({ vocabularyRegistry })` per
+//     D24. Names not in the registry are rejected with
+//     `telemetry.sdk.cardinality_rejected_total{family, reason='not_in_vocabulary'}`
+//     and a thrown `MetricVocabularyError`.
+//   - `family` is one of the six locked families (D18). Mismatches with
+//     the registry-declared family are rejected the same way.
+//   - `tenant_id` is a bare label (D20) — the registration helper
+//     validates label keys against a deny-list that excludes `tenant.id`
+//     and `tenantId` variants.
+//   - Histograms are exponential (D19); the wrapper exposes
+//     `histogram.record(value, labels)` and stores the configuration
+//     for the OTel adapter to consume in TS-12. Max 160 buckets (D19).
+//   - Delta temporality (D21) is declared on the wrapper; the OTel
+//     adapter sets the OTLP export accordingly.
+import { requireTelemetry } from "./init";
+import { incSdkCounter } from "./sdk-counters";
+import { METRIC_FAMILIES, } from "./types";
+/** Thrown by `metrics.counter/histogram` when registration is rejected. */
+export class MetricVocabularyError extends Error {
+    metric;
+    reason;
+    constructor(metric, reason) {
+        super(`metric "${metric}" rejected: ${reason}`);
+        this.metric = metric;
+        this.reason = reason;
+        this.name = "MetricVocabularyError";
+    }
+}
+/**
+ * D20: bare-label discipline. Reject `tenant.id` and `tenantId`
+ * variants at registration. Also reject any underscored Postgres-y
+ * variants like `tenantid`. The locked correct key is `tenant_id`.
+ */
+const FORBIDDEN_LABEL_KEYS = new Set([
+    "tenant.id",
+    "tenantId",
+    "tenantid",
+    "TENANT_ID",
+]);
+function validateLabelKeys(metric, family, labelKeys) {
+    for (const k of labelKeys) {
+        if (FORBIDDEN_LABEL_KEYS.has(k)) {
+            const reason = "label_key_forbidden";
+            incSdkCounter("telemetry.sdk.cardinality_rejected_total", {
+                family,
+                reason,
+            });
+            throw new MetricVocabularyError(metric, `label key '${k}' forbidden — use bare 'tenant_id' per D20`);
+        }
+    }
+}
+function validateRegistration(metric, family) {
+    if (!METRIC_FAMILIES.includes(family)) {
+        const reason = "family_unknown";
+        incSdkCounter("telemetry.sdk.cardinality_rejected_total", {
+            family,
+            reason,
+        });
+        throw new MetricVocabularyError(metric, reason);
+    }
+    const cfg = requireTelemetry();
+    const entry = cfg.vocabularyRegistry[metric];
+    if (!entry) {
+        const reason = "not_in_vocabulary";
+        incSdkCounter("telemetry.sdk.cardinality_rejected_total", {
+            family,
+            reason,
+        });
+        throw new MetricVocabularyError(metric, reason);
+    }
+    if (entry.family !== family) {
+        const reason = "family_mismatch";
+        incSdkCounter("telemetry.sdk.cardinality_rejected_total", {
+            family,
+            reason,
+        });
+        throw new MetricVocabularyError(metric, `family mismatch — registry says '${entry.family}', caller said '${family}'`);
+    }
+    return entry;
+}
+const inProcessBackend = {
+    recordCounter(_name, _by, _labels) {
+        /* no-op; TS-12 replaces */
+    },
+    recordHistogram(_name, _value, _labels) {
+        /* no-op; TS-12 replaces */
+    },
+};
+let backend = inProcessBackend;
+export function _setMetricsBackend(b) {
+    backend = b;
+}
+export function _resetMetricsBackendForTests() {
+    backend = inProcessBackend;
+}
+function counter(name, reg) {
+    const entry = validateRegistration(name, reg.family);
+    validateLabelKeys(name, reg.family, reg.labelKeys ?? []);
+    const description = reg.description || entry.description;
+    return {
+        name,
+        family: reg.family,
+        description,
+        inc(byOrLabels, maybeLabels) {
+            let by;
+            let labels;
+            if (typeof byOrLabels === "number") {
+                by = byOrLabels;
+                labels = maybeLabels ?? {};
+            }
+            else {
+                by = 1;
+                labels = byOrLabels ?? {};
+            }
+            backend.recordCounter(name, by, labels);
+        },
+    };
+}
+function histogram(name, reg) {
+    const entry = validateRegistration(name, reg.family);
+    validateLabelKeys(name, reg.family, reg.labelKeys ?? []);
+    const description = reg.description || entry.description;
+    const maxBuckets = reg.maxBuckets ?? 160;
+    if (maxBuckets > 160) {
+        throw new MetricVocabularyError(name, `maxBuckets ${maxBuckets} exceeds D19 cap (160)`);
+    }
+    return {
+        name,
+        family: reg.family,
+        description,
+        maxBuckets,
+        record(value, labels = {}) {
+            backend.recordHistogram(name, value, labels);
+        },
+    };
+}
+/**
+ * The `metrics.*` namespace (D149 verbatim name). Use:
+ *
+ *   const c = metrics.counter('billing_payments_total', { family: 'async_worker', description: '...' });
+ *   c.inc({ tenant_id, pgw, status });
+ */
+export const metrics = {
+    counter,
+    histogram,
+};
+//# sourceMappingURL=metrics.js.map

package/dist/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,EAAE;AACF,wBAAwB;AACxB,oEAAoE;AACpE,kEAAkE;AAClE,qEAAqE;AACrE,uDAAuD;AACvD,qFAAqF;AACrF,4CAA4C;AAC5C,wEAAwE;AACxE,8DAA8D;AAC9D,kEAAkE;AAClE,yEAAyE;AACzE,+BAA+B;AAC/B,4DAA4D;AAC5D,qEAAqE;AACrE,uEAAuE;AACvE,mEAAmE;AACnE,gDAAgD;AAEhD,OAAO,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EACL,eAAe,GAGhB,MAAM,SAAS,CAAC;AAEjB,2EAA2E;AAC3E,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAE5B;IACA;IAFlB,YACkB,MAAc,EACd,MAAc;QAE9B,KAAK,CAAC,WAAW,MAAM,eAAe,MAAM,EAAE,CAAC,CAAC;QAHhC,WAAM,GAAN,MAAM,CAAQ;QACd,WAAM,GAAN,MAAM,CAAQ;QAG9B,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAAC;IACnC,WAAW;IACX,UAAU;IACV,UAAU;IACV,WAAW;CACZ,CAAC,CAAC;AAEH,SAAS,iBAAiB,CACxB,MAAc,EACd,MAAoB,EACpB,SAA4B;IAE5B,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;QAC1B,IAAI,oBAAoB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YAChC,MAAM,MAAM,GAAG,qBAAqB,CAAC;YACrC,aAAa,CAAC,0CAA0C,EAAE;gBACxD,MAAM;gBACN,MAAM;aACP,CAAC,CAAC;YACH,MAAM,IAAI,qBAAqB,CAC7B,MAAM,EACN,cAAc,CAAC,4CAA4C,CAC5D,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,oBAAoB,CAC3B,MAAc,EACd,MAAoB;IAEpB,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QACtC,MAAM,MAAM,GAAG,gBAAgB,CAAC;QAChC,aAAa,CAAC,0CAA0C,EAAE;YACxD,MAAM;YACN,MAAM;SACP,CAAC,CAAC;QACH,MAAM,IAAI,qBAAqB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClD,CAAC;IACD,MAAM,GAAG,GAAG,gBAAgB,EAAE,CAAC;IAC/B,MAAM,KAAK,GAAG,GAAG,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC7C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,MAAM,GAAG,mBAAmB,CAAC;QACnC,aAAa,CAAC,0CAA0C,EAAE;YACxD,MAAM;YACN,MAAM;SACP,CAAC,CAAC;QACH,MAAM,IAAI,qBAAqB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClD,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,iBAAiB,CAAC;QACjC,aAAa,CAAC,0CAA0C,EAAE;YACxD,MAAM;YACN,MAAM;SACP,CAAC,CAAC;QACH,MAAM,IAAI,qBAAqB,CAC7B,MAAM,EACN,oCAAoC,KAAK,CAAC,MAAM,mBAAmB,MAAM,GAAG,CAC7E,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAoCD,MAAM,gBAAgB,GAAmB;IACvC,aAAa,CAAC,KAAK,EAAE,GAAG,EAAE,OAAO;QAC/B,2BAA2B;IAC7B,CAAC;IACD,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO;QACpC,2BAA2B;IAC7B,CAAC;CACF,CAAC;AAEF,IAAI,OAAO,GAAmB,gBAAgB,CAAC;AAE/C,MAAM,UAAU,kBAAkB,CAAC,CAAiB;IAClD,OAAO,GAAG,CAAC,CAAC;AACd,CAAC;AAED,MAAM,UAAU,4BAA4B;IAC1C,OAAO,GAAG,gBAAgB,CAAC;AAC7B,CAAC;AAQD,SAAS,OAAO,CAAC,IAAY,EAAE,GAAuB;IACpD,MAAM,KAAK,GAAG,oBAAoB,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACrD,iBAAiB,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;IACzD,MAAM,WAAW,GAAG,GAAG,CAAC,WAAW,IAAI,KAAK,CAAC,WAAW,CAAC;IACzD,OAAO;QACL,IAAI;QACJ,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,WAAW;QACX,GAAG,CACD,UAAqD,EACrD,WAA6C;YAE7C,IAAI,EAAU,CAAC;YACf,IAAI,MAAuC,CAAC;YAC5C,IAAI,OAAO,UAAU,KAAK,QAAQ,EAAE,CAAC;gBACnC,EAAE,GAAG,UAAU,CAAC;gBAChB,MAAM,GAAG,WAAW,IAAI,EAAE,CAAC;YAC7B,CAAC;iBAAM,CAAC;gBACN,EAAE,GAAG,CAAC,CAAC;gBACP,MAAM,GAAG,UAAU,IAAI,EAAE,CAAC;YAC5B,CAAC;YACD,OAAO,CAAC,aAAa,CAAC,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC;QAC1C,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAChB,IAAY,EACZ,GAAiD;IAEjD,MAAM,KAAK,GAAG,oBAAoB,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACrD,iBAAiB,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;IACzD,MAAM,WAAW,GAAG,GAAG,CAAC,WAAW,IAAI,KAAK,CAAC,WAAW,CAAC;IACzD,MAAM,UAAU,GAAG,GAAG,CAAC,UAAU,IAAI,GAAG,CAAC;IACzC,IAAI,UAAU,GAAG,GAAG,EAAE,CAAC;QACrB,MAAM,IAAI,qBAAqB,CAC7B,IAAI,EACJ,cAAc,UAAU,wBAAwB,CACjD,CAAC;IACJ,CAAC;IACD,OAAO;QACL,IAAI;QACJ,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,WAAW;QACX,UAAU;QACV,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,EAAE;YACvB,OAAO,CAAC,eAAe,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;QAC/C,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG;IACrB,OAAO;IACP,SAAS;CACD,CAAC"}

package/dist/otlp-adapter.d.ts

@@ -0,0 +1,44 @@
+import { LoggerProvider } from "@opentelemetry/sdk-logs";
+import { MeterProvider } from "@opentelemetry/sdk-metrics";
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import { type CounterHandle, type HistogramHandle } from "./metrics";
+import type { ErrorHandlingConfig, ResourceAttributes } from "./types";
+/** Config for the OTLP adapter — the subset of init config it needs. */
+export interface OtlpAdapterConfig {
+    serviceName: string;
+    env: string;
+    serviceVersion?: string;
+    deploymentRegion?: string;
+    otlpEndpoint: string;
+    errorHandling: ErrorHandlingConfig;
+    resourceAttributes: Record<string, string | number | boolean>;
+}
+/** Handle returned by `installOtlpAdapter` so callers can shut down. */
+export interface OtlpAdapterHandle {
+    /** Force-flushes all signal pipelines (spans + logs + metrics). */
+    forceFlush(): Promise<void>;
+    /** Shuts everything down. Calls flush first. */
+    shutdown(): Promise<void>;
+    /** Direct accessor — used by Lambda lifecycle wrappers. */
+    tracerProvider: NodeTracerProvider;
+    loggerProvider: LoggerProvider;
+    meterProvider: MeterProvider;
+}
+/**
+ * Installs the real OTLP exporters by replacing the no-op emitter,
+ * sink, and backend with adapters that flush to OTel SDK providers
+ * wired to OTLP gRPC.
+ *
+ * Idempotent — second call returns the same handle.
+ */
+export declare function installOtlpAdapter(cfg: OtlpAdapterConfig): OtlpAdapterHandle;
+/** Force-flushes the active OTLP pipelines. No-op when not installed. */
+export declare function forceFlush(): Promise<void>;
+/** Shuts down the OTLP pipelines. No-op when not installed. */
+export declare function shutdownOtlpAdapter(): Promise<void>;
+/** For tests + introspection. */
+export declare function getOtlpAdapterHandle(): OtlpAdapterHandle | null;
+/** Test-only reset; does NOT shutdown providers. */
+export declare function _resetOtlpAdapterForTests(): void;
+export type { CounterHandle, HistogramHandle, ResourceAttributes };
+//# sourceMappingURL=otlp-adapter.d.ts.map

package/dist/otlp-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otlp-adapter.d.ts","sourceRoot":"","sources":["../src/otlp-adapter.ts"],"names":[],"mappings":"AAkCA,OAAO,EAEL,cAAc,EACf,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAEL,aAAa,EAEd,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAEL,kBAAkB,EACnB,MAAM,+BAA+B,CAAC;AAQvC,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,eAAe,EAGrB,MAAM,WAAW,CAAC;AAGnB,OAAO,KAAK,EACV,mBAAmB,EAEnB,kBAAkB,EACnB,MAAM,SAAS,CAAC;AAEjB,wEAAwE;AACxE,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,mBAAmB,CAAC;IACnC,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;CAC/D;AAED,wEAAwE;AACxE,MAAM,WAAW,iBAAiB;IAChC,mEAAmE;IACnE,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,gDAAgD;IAChD,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,2DAA2D;IAC3D,cAAc,EAAE,kBAAkB,CAAC;IACnC,cAAc,EAAE,cAAc,CAAC;IAC/B,aAAa,EAAE,aAAa,CAAC;CAC9B;AAID;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,iBAAiB,GAAG,iBAAiB,CA2M5E;AAED,yEAAyE;AACzE,wBAAsB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAGhD;AAED,+DAA+D;AAC/D,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAGzD;AAED,iCAAiC;AACjC,wBAAgB,oBAAoB,IAAI,iBAAiB,GAAG,IAAI,CAE/D;AAED,oDAAoD;AACpD,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD;AAkHD,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,kBAAkB,EAAE,CAAC"}