motionspec 1.0.0

package/src/router/telemetry.js

@@ -0,0 +1,68 @@
+"use strict";
+/*
+ * Telemetrie — jede geroutete Anfrage ist ein Messpunkt (Konzept §3.3).
+ * Haeuft sich 'escalate' bei einer Anfrageklasse, ist das das Signal, ein
+ * neues Primitiv in den Katalog aufzunehmen (Kapazitaet -1 <- +1).
+ *
+ * Phase C / C1: Speicherung laeuft ueber einen austauschbaren Sink (siehe
+ * telemetry-sink.js).  Default ist der FileSink (JSONL, append-only,
+ * telemetry/events.jsonl, gitignored) — verhaltensgleich zu vorher.  Auf dem
+ * Worker wird via setSink() ein AnalyticsEngineSink eingehaengt.  Die
+ * Aggregation (byOutcome/escalations) bleibt hier; der Sink macht nur I/O.
+ *
+ * Audit-Befunde #7/#12 (2026-06-12): jedes Feld laengenbegrenzt, damit kein
+ * riesiges request/error-Feld die Ablage aufblaeht.  #17: validate-Rauschen
+ * ist als outcome erkennbar und wird in der Eskalations-Sicht ausgeblendet.
+ */
+const path = require("path");
+const { FileSink } = require("./telemetry-sink.js");
+
+const MAX_FIELD = 500;
+const NOISE_OUTCOMES = ["mcp-validate-ok", "mcp-validate-fail", "cache-hit", "cache-invalidated"];
+
+/* Default-Telemetrie-Datei LAZY aufloesen: __dirname existiert nur in Node (CJS),
+ * nicht im ESM-Worker-Bundle.  Der Worker setzt ohnehin via setSink() einen
+ * fs-freien Sink, BEVOR geloggt wird, daher wird die Datei dort nie berechnet. */
+let _defaultFile = null;
+function defaultTelemetryFile() {
+  if (_defaultFile === null) _defaultFile = path.join(__dirname, "..", "..", "telemetry", "events.jsonl");
+  return _defaultFile;
+}
+
+let sink = null;
+function activeSink() {
+  if (sink === null) sink = new FileSink(defaultTelemetryFile());
+  return sink;
+}
+function setSink(s) { sink = s; }
+function getSink() { return activeSink(); }
+
+function clamp(v) {
+  if (typeof v === "string") return v.length > MAX_FIELD ? v.slice(0, MAX_FIELD) : v;
+  if (Array.isArray(v)) return v.slice(0, 20).map(clamp);
+  return v;
+}
+
+function log(event) {
+  const safe = {};
+  for (const k of Object.keys(event)) safe[k] = clamp(event[k]);
+  safe.ts = new Date().toISOString();
+  activeSink().append(safe);
+}
+
+async function summary() {
+  const records = await activeSink().readAll();
+  const byOutcome = {};
+  const escalations = {};
+  for (const e of records) {
+    byOutcome[e.outcome] = (byOutcome[e.outcome] || 0) + 1;
+    /* #17: nur echte Eskalationen zaehlen fuer das Katalog-Wachstums-Signal */
+    if (typeof e.outcome === "string" && e.outcome.startsWith("escalate") && NOISE_OUTCOMES.indexOf(e.outcome) === -1)
+      escalations[e.outcome] = (escalations[e.outcome] || 0) + 1;
+  }
+  return { total: records.length, byOutcome, escalations };
+}
+
+module.exports = { log, summary, setSink, getSink, NOISE_OUTCOMES };
+/* TELEMETRY_FILE als lazy Getter erhalten (Tests lesen es; kein __dirname beim Laden). */
+Object.defineProperty(module.exports, "TELEMETRY_FILE", { enumerable: true, get: defaultTelemetryFile });