@jeffjassky/telemetry 0.4.0 → 0.6.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)";
@@ -554,10 +560,11 @@ var truncate = (d, b) => {
   if (b === "day") return day;
   return new Date(day.getTime() - (day.getUTCDay() + 6) % 7 * 864e5);
 };
-async function recordRollup(RollupModel, doc, name, spec, counters) {
+async function recordRollup(RollupModel, doc, name, spec, counters, opts) {
+  const dry = opts?.dryRun === true;
   if (spec.actors && doc.actor) {
     const actorType = String(doc.actor).split(":")[0];
-    if (!spec.actors.includes(actorType)) return;
+    if (!spec.actors.includes(actorType)) return 0;
   }
   const as = spec.as ?? name;
   const at = doc.occurredAt;
@@ -569,9 +576,11 @@ async function recordRollup(RollupModel, doc, name, spec, counters) {
     let v = resolveDim(src, doc);
     if (v == null || v === "") {
       if (spec.dimDefault === void 0) {
-        counters.rollupSkipped++;
-        bumpCounterMap(counters.rollupSkippedBy, `${as}|${label(src)}`);
-        return;
+        if (!dry) {
+          counters.rollupSkipped++;
+          bumpCounterMap(counters.rollupSkippedBy, `${as}|${label(src)}`);
+        }
+        return 0;
       }
       v = spec.dimDefault;
     }
@@ -581,48 +590,48 @@ async function recordRollup(RollupModel, doc, name, spec, counters) {
   const refs = fansOut ? (doc.subjectKeys ?? []).filter(
     (r) => !spec.subjects || spec.subjects.includes(r.split(":")[0])
   ) : [null];
-  if (!refs.length) return;
+  if (!refs.length) return 0;
   const firstCapture = Object.fromEntries(
     (spec.capture ?? []).map((src) => [label(src), resolveDim(src, doc)]).filter(([, v]) => v != null).map(([k, v]) => [k, String(v)])
   );
   const expiresAt = spec.retentionDays != null ? new Date(at.getTime() + spec.retentionDays * 864e5) : void 0;
-  await RollupModel.bulkWrite(
-    refs.map((ref) => {
-      const dims = spec.by.map((src) => src === "subject" ? ref : fixed.get(src));
-      const isNewFirst = {
-        $or: [{ $eq: [{ $type: "$firstAt" }, "missing"] }, { $lt: [at, "$firstAt"] }]
-      };
-      const sums = Object.fromEntries(
-        (spec.sum ?? []).map((k) => [k, doc.metrics?.get(k)]).filter(([, v]) => typeof v === "number").map(([k, v]) => [`sums.${k}`, { $add: [{ $ifNull: [`$sums.${k}`, 0] }, v] }])
-      );
-      return {
-        updateOne: {
-          filter: { _id: `${doc.tenantId}|${as}|${dims.join("|")}|${bucketKey}` },
-          update: [
-            {
-              $set: {
-                tenantId: doc.tenantId,
-                as,
-                dims,
-                ...ref ? { subjectType: ref.split(":")[0] } : {},
-                ...bucketAt ? { bucketAt } : {},
-                ...expiresAt ? { expiresAt } : {},
-                // aggregation $min/$max ignore missing, so correct on insert too
-                firstAt: { $min: ["$firstAt", at] },
-                lastAt: { $max: ["$lastAt", at] },
-                count: { $add: [{ $ifNull: ["$count", 0] }, 1] },
-                ...sums,
-                firstTraceId: { $cond: [isNewFirst, doc.traceId ?? null, "$firstTraceId"] },
-                firstCapture: { $cond: [isNewFirst, { $literal: firstCapture }, "$firstCapture"] }
-              }
+  const ops = refs.map((ref) => {
+    const dims = spec.by.map((src) => src === "subject" ? ref : fixed.get(src));
+    const isNewFirst = {
+      $or: [{ $eq: [{ $type: "$firstAt" }, "missing"] }, { $lt: [at, "$firstAt"] }]
+    };
+    const sums = Object.fromEntries(
+      (spec.sum ?? []).map((k) => [k, doc.metrics?.get(k)]).filter(([, v]) => typeof v === "number").map(([k, v]) => [`sums.${k}`, { $add: [{ $ifNull: [`$sums.${k}`, 0] }, v] }])
+    );
+    return {
+      updateOne: {
+        filter: { _id: `${doc.tenantId}|${as}|${dims.join("|")}|${bucketKey}` },
+        update: [
+          {
+            $set: {
+              tenantId: doc.tenantId,
+              as,
+              dims,
+              ...ref ? { subjectType: ref.split(":")[0] } : {},
+              ...bucketAt ? { bucketAt } : {},
+              ...expiresAt ? { expiresAt } : {},
+              // aggregation $min/$max ignore missing, so correct on insert too
+              firstAt: { $min: ["$firstAt", at] },
+              lastAt: { $max: ["$lastAt", at] },
+              count: { $add: [{ $ifNull: ["$count", 0] }, 1] },
+              ...sums,
+              firstTraceId: { $cond: [isNewFirst, doc.traceId ?? null, "$firstTraceId"] },
+              firstCapture: { $cond: [isNewFirst, { $literal: firstCapture }, "$firstCapture"] }
             }
-          ],
-          upsert: true
-        }
-      };
-    }),
-    { ordered: false }
-  );
+          }
+        ],
+        upsert: true
+      }
+    };
+  });
+  if (dry) return ops.length;
+  await RollupModel.bulkWrite(ops, { ordered: false });
+  return ops.length;
 }
 function buildCheckpointModel(connection, modelName, collection) {
   const existing = connection.models?.[modelName];
@@ -672,6 +681,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 +821,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),
@@ -878,6 +995,109 @@ function createForget(ctx) {
   };
 }
 
+// src/server/relink.ts
+var RELINK_BATCH_SIZE = 500;
+var refKey = (s) => `${s.type}:${s.id}`;
+function createRelink(ctx) {
+  const { registry, TelemetryModel, RollupModel, counters, logger, linkSubjects } = ctx;
+  return async function relink(opts = {}) {
+    const dryRun = opts.dryRun !== false;
+    const batchSize = opts.batchSize ?? RELINK_BATCH_SIZE;
+    const result = {
+      examined: 0,
+      linked: 0,
+      subjects: 0,
+      rollups: 0,
+      misses: 0,
+      errors: 0,
+      skipped: 0
+    };
+    if (opts.names) {
+      const unknown = opts.names.filter((n) => !registry[n]);
+      if (unknown.length) {
+        throw new Error(
+          `telemetry: relink() was given names this registry does not declare: ${unknown.join(", ")}. A name with no spec has no rollup families to replay, so relinking it could only desynchronize its rows from its aggregates. Omit \`names\` to sweep everything.`
+        );
+      }
+    }
+    if (!linkSubjects) {
+      logger.warn(
+        "[telemetry] relink() has no subjectLinker to ask \u2014 nothing was read and nothing was written. Configure createTelemetry({ subjectLinker }) first; relink() backfills what that hook would have done, it does not replace it."
+      );
+      result.skipped = 1;
+      return result;
+    }
+    if (opts.limit != null && opts.limit <= 0) return result;
+    const filter = {};
+    if (opts.names) filter.name = { $in: opts.names };
+    if (opts.since) filter.occurredAt = { $gte: opts.since };
+    const query = TelemetryModel.find(filter).hint({ _id: 1 }).batchSize(batchSize);
+    if (opts.limit != null) query.limit(opts.limit);
+    const progress = () => {
+      if (!opts.onProgress) return;
+      try {
+        opts.onProgress({ ...result });
+      } catch (e) {
+        logger.warn(`[telemetry] relink() onProgress threw \u2014 ignored, the backfill continues: ${e}`);
+      }
+    };
+    const cursor = query.cursor();
+    let sinceProgress = 0;
+    try {
+      for await (const doc of cursor) {
+        result.examined++;
+        sinceProgress++;
+        if (sinceProgress >= batchSize) {
+          sinceProgress = 0;
+          progress();
+        }
+        const spec = registry[doc.name];
+        if (!spec) {
+          result.skipped++;
+          continue;
+        }
+        const declared = (doc.subjects ?? []).map(
+          (s) => s.role ? { type: s.type, id: s.id, role: s.role } : { type: s.type, id: s.id }
+        );
+        const m0 = counters.subjectLinkMisses;
+        const e0 = counters.subjectLinkErrors + counters.subjectLinkTimeouts;
+        const merged = await linkSubjects(doc.name, spec, doc.tenantId, declared);
+        result.misses += counters.subjectLinkMisses - m0;
+        if (counters.subjectLinkErrors + counters.subjectLinkTimeouts > e0) result.errors++;
+        if (!merged) continue;
+        const had = new Set(declared.map(refKey));
+        const mergedKeys = [];
+        const newKeys = [];
+        for (const s of merged) {
+          const key = refKey(s);
+          if (mergedKeys.includes(key)) continue;
+          mergedKeys.push(key);
+          if (!had.has(key)) newKeys.push(key);
+        }
+        if (!newKeys.length) continue;
+        result.linked++;
+        result.subjects += newKeys.length;
+        if (!dryRun) {
+          await TelemetryModel.updateOne(
+            { _id: doc._id },
+            { $set: { subjects: merged, subjectKeys: mergedKeys } }
+          );
+        }
+        doc.subjectKeys = newKeys;
+        for (const r of spec.rollups ?? []) {
+          if (!r.by.includes("subject")) continue;
+          result.rollups += await recordRollup(RollupModel, doc, doc.name, r, counters, { dryRun });
+        }
+      }
+    } finally {
+      await cursor.close().catch(() => {
+      });
+    }
+    if (sinceProgress) progress();
+    return result;
+  };
+}
+
 // src/server/indexes.ts
 var INDEX_BUDGET = 24;
 function createSyncIndexes(ctx) {
@@ -1221,6 +1441,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 +1453,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 +3856,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,
@@ -3652,6 +3889,14 @@ function createTelemetry(config) {
     },
     globalSubjectRefs: () => config.globalSubjectRefs === true
   });
+  const relink = createRelink({
+    registry,
+    TelemetryModel,
+    RollupModel,
+    counters,
+    logger,
+    linkSubjects
+  });
   const syncIndexes = createSyncIndexes({
     registry,
     TelemetryModel,
@@ -3663,6 +3908,21 @@ function createTelemetry(config) {
     emit,
     /** erasure: delete sole-party rows, redact shared ones, rekey rollups, drop aliases */
     forget,
+    /**
+     * Backfill: re-ask the `subjectLinker` about records ALREADY on disk, and
+     * replay the rollups the new subjects reach.
+     *
+     * Linking happens at write time, so configuring it fixes the future and
+     * nothing else — a lifetime `by:['subject']` family is keyed on the subject
+     * the record was written with, and a read-time join cannot reach back into
+     * it. This is how a host catches up the backlog it adopted the hook with.
+     *
+     * DRY RUN BY DEFAULT: it rewrites historical aggregates, so the short call
+     * reports and the writing call says `{ dryRun: false }`. Idempotent by
+     * construction — a row that already carries the linked subject yields
+     * nothing new, so a second run is a no-op.
+     */
+    relink,
     /**
      * Tenant scope is not optional — force every read through here. The five
      * dashboard query primitives (records/series/distribution/rollups/journey)
@@ -3697,6 +3957,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),
@@ -3724,9 +3995,12 @@ exports.LogLevel = LogLevel;
 exports.MAX_SUGGESTIONS = MAX_SUGGESTIONS;
 exports.Origin = Origin;
 exports.PLATFORM_SCOPE = PLATFORM_SCOPE;
+exports.RELINK_BATCH_SIZE = RELINK_BATCH_SIZE;
 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;