@jeffjassky/telemetry 0.4.0 → 0.5.0

package/dist/index.cjs

@@ -70,7 +70,13 @@ var newCounters = () => ({
   deduped: 0,
   truncated: 0,
   rollupSkippedBy: {},
-  undeclaredAttrs: {}
+  undeclaredAttrs: {},
+  subjectsLinked: 0,
+  subjectLinkMisses: 0,
+  subjectLinkErrors: 0,
+  subjectLinkTimeouts: 0,
+  subjectLinkUndeclared: 0,
+  subjectLinkCapped: 0
 });
 var COUNTER_MAP_MAX = 1e3;
 var COUNTER_OVERFLOW_KEY = "(other)|(other)";
@@ -672,6 +678,110 @@ function noteUndeclaredAttrs(counters, name, spec, attrs) {
     bumpCounterMap(counters.undeclaredAttrs, `${name}|${key}`);
   }
 }
+var SUBJECT_MAX = 8;
+var SUBJECT_LINK_TIMEOUT_MS = 50;
+var LINK_TIMEOUT = /* @__PURE__ */ Symbol("telemetry.subjectLink.timeout");
+function createSubjectLinking(opts) {
+  const { linker, counters, logger } = opts;
+  if (!linker) return null;
+  const timeoutMs = opts.timeoutMs ?? SUBJECT_LINK_TIMEOUT_MS;
+  const warned = /* @__PURE__ */ new Set();
+  const warnOnce = (key, msg) => {
+    if (warned.has(key) || warned.size >= COUNTER_MAP_MAX) return;
+    warned.add(key);
+    logger.warn(msg);
+  };
+  return async function linkSubjects(name, spec, tenantId, declared) {
+    const have = Array.isArray(declared) ? declared : [];
+    const seen = /* @__PURE__ */ new Set();
+    const view = [];
+    for (const s of have) {
+      const ref = wellFormed(s);
+      if (!ref) continue;
+      seen.add(`${ref.type}:${ref.id}`);
+      view.push(ref);
+    }
+    let out;
+    let timer;
+    try {
+      out = await Promise.race([
+        // the async wrapper turns a SYNCHRONOUS throw into a rejection, so a
+        // linker that dies on its first line lands in the same catch as one
+        // whose promise rejects
+        (async () => linker.link(view, { name, tenantId }))(),
+        new Promise((_, reject) => {
+          timer = setTimeout(() => reject(LINK_TIMEOUT), timeoutMs);
+        })
+      ]);
+    } catch (e) {
+      if (e === LINK_TIMEOUT) {
+        counters.subjectLinkTimeouts++;
+        warnOnce(
+          "timeout",
+          `[telemetry] subjectLinker.link() exceeded ${timeoutMs}ms \u2014 records are being written UNLINKED rather than waiting. The hook is expected to answer from a cache; a resolver that queries per record cannot keep up with ingest. Warned once \u2014 the count is counters.subjectLinkTimeouts.`
+        );
+      } else {
+        counters.subjectLinkErrors++;
+        warnOnce(
+          "threw",
+          `[telemetry] subjectLinker.link() threw \u2014 records are being written unlinked: ${e}. Warned once \u2014 the count is counters.subjectLinkErrors.`
+        );
+      }
+      return null;
+    } finally {
+      clearTimeout(timer);
+    }
+    if (!Array.isArray(out)) {
+      counters.subjectLinkErrors++;
+      warnOnce(
+        "shape",
+        `[telemetry] subjectLinker.link() resolved to ${typeof out}, not an array \u2014 records are being written unlinked. Return [] when nothing links. Warned once \u2014 the count is counters.subjectLinkErrors.`
+      );
+      return null;
+    }
+    if (!out.length) {
+      counters.subjectLinkMisses++;
+      return null;
+    }
+    let room = Math.max(0, SUBJECT_MAX - have.length);
+    let capped2 = 0;
+    const add = [];
+    for (const s of out) {
+      const ref = wellFormed(s);
+      if (!ref) {
+        counters.subjectLinkErrors++;
+        warnOnce(
+          "entry",
+          "[telemetry] subjectLinker returned an entry that is not { type, id } \u2014 dropped. Warned once \u2014 the count is counters.subjectLinkErrors."
+        );
+        continue;
+      }
+      const key = `${ref.type}:${ref.id}`;
+      if (seen.has(key)) continue;
+      if (!spec.subjects.includes(ref.type)) {
+        counters.subjectLinkUndeclared++;
+      }
+      if (room <= 0) {
+        capped2++;
+        continue;
+      }
+      seen.add(key);
+      room--;
+      add.push(ref);
+    }
+    counters.subjectLinkCapped += capped2;
+    if (!add.length) return null;
+    counters.subjectsLinked += add.length;
+    return [...have, ...add];
+  };
+}
+function wellFormed(s) {
+  if (!s || typeof s !== "object") return null;
+  const { type, id, role } = s;
+  if (typeof type !== "string" || !type) return null;
+  if (typeof id !== "string" || !id) return null;
+  return typeof role === "string" && role ? { type, id, role } : { type, id };
+}
 function createEmitter(ctx) {
   const { registry, byKind, RollupModel, rejects, counters } = ctx;
   const burstBuckets = /* @__PURE__ */ new Map();
@@ -708,11 +818,15 @@ function createEmitter(ctx) {
     const durable = kind === TelemetryKind.Usage || (doc.durable ?? spec.durable ?? false);
     const Model = byKind[kind];
     const { forceKeep: _drop, durable: _durable, ...rest } = doc;
+    const linked = ctx.linkSubjects ? await ctx.linkSubjects(name, spec, doc.tenantId, doc.subjects) : null;
     const safe = (o) => new Map(Object.entries(o ?? {}).map(([k, v]) => [k.replace(/\./g, "_"), v]));
     const payload = {
       ...rest,
       _id: id,
       name,
+      // computed like everything below it, and absent when nothing linked, so a
+      // host with no linker hands the model the exact object 0.4.0 did
+      ...linked ? { subjects: linked } : {},
       sampleRate: forced ? 1 : baseRate,
       forced,
       attrs: safe(doc.attrs),
@@ -1221,6 +1335,8 @@ function createIngest(opts) {
         const occurredAt = Number.isFinite(occurredRaw) ? new Date(occurredRaw - clockSkewMs) : receivedAt;
         const safeMap = (o) => o && typeof o === "object" ? new Map(Object.entries(o).map(([k, v]) => [k.replace(/\./g, "_"), v])) : /* @__PURE__ */ new Map();
         noteUndeclaredAttrs(t.counters, name, spec, rec.attrs);
+        const subjects = mergeSubjects(rec.subjects);
+        const linked = t.linkSubjects ? await t.linkSubjects(name, spec, tenantId, subjects) : null;
         const Model = t.models.byKind[spec.kind];
         const d = new Model({
           // facts the wire may not assert: tenant, service, env, origin, plane
@@ -1231,7 +1347,7 @@ function createIngest(opts) {
           tenantId,
           occurredAt,
           severity: typeof rec.severity === "string" ? rec.severity : void 0,
-          subjects: mergeSubjects(rec.subjects),
+          subjects: linked ?? subjects,
           actor: ctx.actor ?? (typeof rec.actor === "string" ? rec.actor : batchActor),
           onBehalfOf: typeof rec.onBehalfOf === "string" ? rec.onBehalfOf : void 0,
           service: key.service,
@@ -3634,7 +3750,22 @@ function createTelemetry(config) {
     inFlight.add(p);
     void p.finally(() => inFlight.delete(p));
   };
-  const emit = createEmitter({ registry, byKind, RollupModel, rejects, counters, logger, track });
+  const linkSubjects = createSubjectLinking({
+    linker: config.subjectLinker,
+    timeoutMs: config.subjectLinkTimeoutMs,
+    counters,
+    logger
+  });
+  const emit = createEmitter({
+    registry,
+    byKind,
+    RollupModel,
+    rejects,
+    counters,
+    logger,
+    track,
+    linkSubjects
+  });
   const forget = createForget({
     TelemetryModel,
     RollupModel,
@@ -3697,6 +3828,17 @@ function createTelemetry(config) {
     counters,
     /** the registry, exposed for the router factories — hosts should import their own */
     registry,
+    /**
+     * Write-time subject linking, exposed for the router factories. `null` when
+     * no `subjectLinker` is configured.
+     *
+     * The wire path does not go through emit() — createIngest() builds its
+     * record itself, because at-least-once delivery inverts the plane order
+     * (insert first, THEN aggregate). So it reaches the linker the same way it
+     * reaches the registry and the models: off the instance, running the one
+     * implementation, rather than growing a second copy of the rules.
+     */
+    linkSubjects,
     logger,
     /** mint an ingest key; the full key string is returned once, never again */
     createKey: (input) => createKey(KeyModel, input),
@@ -3727,6 +3869,8 @@ exports.PLATFORM_SCOPE = PLATFORM_SCOPE;
 exports.RETENTION_DAYS = RETENTION_DAYS;
 exports.SAMPLE_RATE = SAMPLE_RATE;
 exports.SCHEMA_VERSION = SCHEMA_VERSION;
+exports.SUBJECT_LINK_TIMEOUT_MS = SUBJECT_LINK_TIMEOUT_MS;
+exports.SUBJECT_MAX = SUBJECT_MAX;
 exports.TelemetryKind = TelemetryKind;
 exports.TenantMode = TenantMode;
 exports.boundedMeta = boundedMeta;