@jeffjassky/telemetry 0.4.0 → 0.5.0

package/dist/index.js

@@ -61,7 +61,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)";
@@ -663,6 +669,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();
@@ -699,11 +809,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),
@@ -1212,6 +1326,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
@@ -1222,7 +1338,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,
@@ -3625,7 +3741,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,
@@ -3688,6 +3819,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),
@@ -3704,6 +3846,6 @@ function createTelemetry(config) {
   };
 }
 
-export { BODY_MAX_CHARS, COUNTER_MAP_MAX, COUNTER_OVERFLOW_KEY, DEFAULT_LIMITS, Env, INDEX_BUDGET, KeyKind, LogLevel, MAX_SUGGESTIONS, Origin, PLATFORM_SCOPE, RETENTION_DAYS, SAMPLE_RATE, SCHEMA_VERSION, TelemetryKind, TenantMode, boundedMeta, createDashboard, createIngest, createKey, createQueries, createTelemetry, createValues, defaultSpaDir, defineRegistry, deriveCatalog, deriveSuggestions, deriveViews, executeReport, findFamily, foldRollups, hashSecret, intervalForRange, isPlatformScope, median, newId, normalizeQuery, parseKeyString, parseReportQuery, plain, projectRegistry, rangeOf, reportToQuery, requireMilestoneFamily, resolveDim, resolveReport, summarizeStages, traceKeep, truncate, validateRegistry, verifySecret };
+export { BODY_MAX_CHARS, COUNTER_MAP_MAX, COUNTER_OVERFLOW_KEY, DEFAULT_LIMITS, Env, INDEX_BUDGET, KeyKind, LogLevel, MAX_SUGGESTIONS, Origin, PLATFORM_SCOPE, RETENTION_DAYS, SAMPLE_RATE, SCHEMA_VERSION, SUBJECT_LINK_TIMEOUT_MS, SUBJECT_MAX, TelemetryKind, TenantMode, boundedMeta, createDashboard, createIngest, createKey, createQueries, createTelemetry, createValues, defaultSpaDir, defineRegistry, deriveCatalog, deriveSuggestions, deriveViews, executeReport, findFamily, foldRollups, hashSecret, intervalForRange, isPlatformScope, median, newId, normalizeQuery, parseKeyString, parseReportQuery, plain, projectRegistry, rangeOf, reportToQuery, requireMilestoneFamily, resolveDim, resolveReport, summarizeStages, traceKeep, truncate, validateRegistry, verifySecret };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map