@autter/runtime-node 1.5.0 → 1.6.1

package/README.md

@@ -48,6 +48,38 @@ expectOperation(runtime, "POST /checkout").toHaveOutcome("degraded").toHaveError
 
 Full guide: [Requests, coded errors and background work](../../docs/REQUESTS-AND-ERRORS.md).
 
+# Breadcrumbs (1.6.0)
+
+The steps before an error, scoped to the current request:
+
+```ts
+import { addBreadcrumb, runtimeLogger } from "@autter/runtime-node";
+
+app.post("/checkout", async (req, res) => {
+  addBreadcrumb({ message: "Loaded cart", data: { items: 3 } });  // type "custom"
+  runtimeLogger.info("Charging card", { provider: "stripe" });     // recorded as a "log" breadcrumb
+  await charge();                                                  // a throw here carries both
+});
+```
+
+- Scope: inside `autterRequests()` / `withRuntimeRequest()` /
+  `withRuntimeOperation()` the trail belongs to the request and is shared with
+  its child operations and forks (AsyncLocalStorage). Inside a traced request
+  without the middleware it belongs to the trace; outside both, to the process
+  (so a crash outside any request carries what happened before it).
+- The last 30 are kept. `captureException`, `captureMessage` and errors thrown
+  out of operations attach them to the exception span event as
+  `autter.breadcrumbs` (a JSON string, at most 16 KB, or less when
+  `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` is lower).
+- Every `runtimeLogger` / `runtimeContext.debug|info|warn|error` entry is
+  recorded as a `log` breadcrumb with its level and up to 10 primitive
+  attributes.
+- Messages (≤ 500 characters) and data (≤ 10 keys of strings, numbers,
+  booleans or null) are scrubbed with your `redact` settings.
+- The browser relay forwards browser breadcrumbs, re-validated and re-scrubbed.
+- Needs ingester 1.6.0. Logger-only mode (`initAutterLogging`) and
+  `@autter/runtime-edge` don't attach them yet.
+
 # @autter/runtime-node
 
 The server tracker exports per-instance RSS, heap, memory limit, and GC
@@ -113,6 +145,12 @@ const autter = initAutterServer({
 // handled errors — always recorded, never sampled out:
 autter.captureException(err, { "order.id": "…" });
 
+// fingerprint override — every error carrying the same fingerprint is one
+// issue, whatever its message or stack (a string or up to 10 strings, each
+// ≤200 chars; sent as `autter.fingerprint` on the exception event; needs
+// ingester 1.6.0+, older ingesters ignore it):
+autter.captureException(err, { fingerprint: ["checkout", "card-timeout"] });
+
 // warnings/info without an exception — same grouping+aggregation as
 // errors, just a lower severity ("fatal" | "error" | "warning" | "info"):
 autter.captureMessage("Legacy /orders lookup used", "warning");
@@ -142,10 +180,11 @@ Defaults (cheap by construction):
 | Traces containing an error | 100% (tail retention, `retainTracesOnError`) |
 | `withProcessSpan` spans | 100% (same always-on tracer) |
 | LLM/GenAI call spans | 100% (`llmTracing`, on by default) |
-| Healthy traces | 1% head sampling (`traceSampleRate`) |
+| Healthy traces | 1% head sampling (`traceSampleRate`; also for requests whose incoming `traceparent` is unsampled, such as browser fetches from `@autter/runtime-browser`) |
 | Request metrics | exported every 60 s |
 | Logs | not collected |
 | PII in custom attributes | redacted before export (`redactAttributes`) |
+| Query strings in span URLs | parameter names only (`keepQueryParams`) |
 | Forgotten `shutdown()` | exporters still flushed on exit (`autoFlush`) |
 
 **Error-linked trace retention.** Errors export at 100% while traces are
@@ -167,6 +206,63 @@ import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";
 initAutterServer({ ..., instrumentations: [new ExpressInstrumentation()] });
 ```
 
+### Server errors keep their stacks
+
+When a handler throws, the framework answers 500 — and on its own that 500
+is all the tracker sees: a stackless `HttpServerError` grouped by route. Add
+your framework's hook and the thrown error is recorded, with its stack, on
+the request span; the framework then carries on exactly as before.
+
+```ts
+import { autterErrorHandler, autterFastifyErrors, autterKoa, captureRequestError } from "@autter/runtime-node";
+
+// Express / Connect: after your routes, before your own error handlers.
+// Records the error, then calls next(err) unchanged.
+app.use(autterErrorHandler());
+
+// Fastify 4/5: an onError hook (Fastify's error handler still answers).
+// autterFastify (request summaries) already includes it.
+app.register(autterFastifyErrors);   // or autterFastifyErrors(app)
+
+// Koa 2/3: mount first; records and rethrows, so app.on("error") still fires.
+app.use(autterKoa());
+
+// Anything else (NestJS exception filters, hapi onPreResponse, …):
+captureRequestError(err, { "app.handler": "checkout" });
+```
+
+All three report errors with status ≥ 500 (or none), RuntimeErrors and coded
+errors — `ctx.throw(404)` and validation failures stay out of your issues.
+Pass `{ capture: true }` to report every error, or a predicate. An error is
+reported once, even if your handler already called `captureException`, and it
+lands on the request's HTTP server span even when an instrumentation's child
+span is active (`captureRequestError` still adds its attributes to that span
+when the error was already reported). Errors from another JavaScript realm
+(a `vm` context, Next's edge sandbox under `next start`) keep their own type,
+message and stack. `autterErrorResponse()` reports the same way and also
+answers the request.
+
+### Unhandled promise rejections
+
+Recorded as errors (severity `error`, `autter.unhandled_rejection: true`, not
+fatal) — without changing whether your process crashes. Any
+`unhandledRejection` listener switches off Node's default crash, so the SDK
+does what Node would have done when its listener is the only one:
+
+| `--unhandled-rejections` | Your own listener? | What happens | Recorded as |
+| --- | --- | --- | --- |
+| `throw` (default) | no | rethrown on the next tick: exit code 1, as before | fatal crash (`autter.unhandled`) |
+| `throw` (default) | yes | your listener decides | error |
+| `strict` | either | Node crashes first, as before | fatal crash |
+| `warn`, `none` | either | no crash, as before | error |
+| `warn-with-error-code` | no | Node's warning and exit code 1, as before | error |
+
+The one visible difference: after the rethrow, `uncaughtException` listeners
+receive origin `"uncaughtException"` rather than `"unhandledRejection"`.
+`captureUnhandledRejections: false` (or `captureGlobalErrors: false`) restores
+the 1.5.0 behaviour, where a rejection is seen only when it crashes the
+process.
+
 ### Version compatibility: checked for you
 
 Some features need a minimum ingester version: operation logging needs
@@ -288,6 +384,48 @@ This closes the server-side gap to match the browser relay's payload
 whitelist; it is best-effort scrubbing of obvious PII shapes, not a DLP
 engine — keep secrets out of attributes in the first place.
 
+**Query strings (1.6.1+).** Query strings carry what a path never should:
+emails, one-time codes, API keys, session ids, search terms. So no span
+leaves the process with query values, whichever instrumentation made it
+(HTTP server and client spans, undici/fetch, Express, Fastify, Next.js's own
+spans):
+
+- `http.target`, `http.url`, `url.full` and `url.original` are cut at the `?`
+  (and `#`): `/search?email=jane@example.com&page=2` becomes `/search`;
+- `url.query` keeps only the parameter names, `email=[redacted]&page=[redacted]`.
+  It is added from the URL when the instrumentation did not set it, so you
+  still see which parameters a request used. A parameter without `=`
+  (`/verify?<token>`) may itself be the secret and is masked whole;
+- span names lose their query too (Next.js names a request span
+  `GET /search?q=…` until it knows the route).
+
+List the parameters whose values are safe to keep, such as pagination or
+sorting (exact names, after percent-decoding; kept values are still scrubbed
+by `redactAttributes`):
+
+```ts
+initAutterServer({ ..., keepQueryParams: ["page", "sort"] });
+// url.query: "email=[redacted]&page=2"
+```
+
+This runs at export, like the scrubbing above, and also with
+`redactAttributes: false`. Route templates (`http.route`) and request
+summaries never contained a query.
+
+### One SDK per process, however many copies are loaded
+
+Bundlers can load this package more than once: Next.js bundles one copy
+into `instrumentation.ts` and another into each route (unless it is in
+`serverExternalPackages`), and a process can load both the ESM and the CJS
+build. Since 1.6.1 every copy shares one process-wide state
+(`globalThis[Symbol.for("@autter/runtime-node")]`): the copy that ran
+`initAutterServer` (or `initAutterLogging`) is the SDK for all of them, so
+`withRuntimeRequest`, `captureException`, `runtimeLogger` and the rest export
+through it from any copy, and an error one copy reported is never reported
+again by another. Before any copy starts, and after `shutdown()`, every copy
+behaves as before: records go to the console. The shared object is
+versioned; a copy that finds a layout it does not know keeps its own state.
+
 ## 3. LLM tracing
 
 For the field contract, manual reporting patterns, and provider-agnostic

package/dist/{chunk-GI47WGRR.cjs → chunk-4MVWIRBI.cjs}

@@ -90,6 +90,35 @@ var compat_manifest_default = {
       ingester: "1.5.0",
       migrations: ["0013-occurrence-codes"],
       sdks: { "@autter/runtime-node": "1.5.0", "@autter/runtime-next": "1.5.0", "@autter/runtime-browser": "1.4.0", "@autter/runtime-edge": "1.0.0" }
+    },
+    {
+      id: "breadcrumbs",
+      title: "Breadcrumbs: the steps before an error",
+      ingester: "1.6.0",
+      migrations: [],
+      sdks: { "@autter/runtime-browser": "1.6.0", "@autter/runtime-node": "1.6.0", "@autter/runtime-next": "1.6.0" }
+    },
+    {
+      id: "source_map_debug_ids",
+      title: "Source map debug ids",
+      ingester: "1.6.0",
+      migrations: ["0017-source-maps-debug-id"],
+      route: "/v1/sourcemaps/check",
+      sdks: { "@autter/runtime-browser": "1.6.0", "@autter/runtime-next": "1.6.0" }
+    },
+    {
+      id: "fingerprint_override",
+      title: "Fingerprint override",
+      ingester: "1.6.0",
+      migrations: [],
+      sdks: { "@autter/runtime-browser": "1.6.0", "@autter/runtime-node": "1.6.0", "@autter/runtime-next": "1.6.0", "@autter/runtime-edge": "1.1.0" }
+    },
+    {
+      id: "browser_trace_propagation",
+      title: "Browser trace propagation (browser errors linked to server traces)",
+      ingester: "1.6.0",
+      migrations: [],
+      sdks: { "@autter/runtime-browser": "1.6.0", "@autter/runtime-next": "1.6.0", "@autter/runtime-node": "1.6.0" }
     }
   ]
 };
@@ -435,7 +464,7 @@ var _https = require('https');
 // package.json
 var package_default = {
   name: "@autter/runtime-node",
-  version: "1.5.0",
+  version: "1.6.1",
   description: "Autter Runtime for Node.js: request wide events, coded errors, operation logging, same-origin browser relay and a curated OpenTelemetry server tracker",
   license: "MIT",
   type: "module",
@@ -486,6 +515,8 @@ var package_default = {
     "@autter/runtime-core": "0.0.0",
     "@types/node": "^22.10.0",
     express: "^4.21.2",
+    fastify: "^5.12.5",
+    koa: "^3.2.1",
     tsup: "^8.3.5",
     typescript: "^5.7.0"
   },
@@ -508,6 +539,55 @@ var package_default = {
   ]
 };
 
+// src/shared.ts
+var SHARED_STATE_KEY = /* @__PURE__ */ Symbol.for("@autter/runtime-node");
+var SHARED_STATE_LAYOUT = 1;
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+var VERSION = package_default.version;
+function resolveShared() {
+  const fresh = { v: SHARED_STATE_LAYOUT, sdk: VERSION };
+  const host = globalThis;
+  let existing;
+  try {
+    existing = host[SHARED_STATE_KEY];
+    if (existing === void 0) {
+      Object.defineProperty(host, SHARED_STATE_KEY, {
+        value: fresh,
+        configurable: true,
+        enumerable: false,
+        writable: false
+      });
+      return fresh;
+    }
+  } catch (e) {
+    return fresh;
+  }
+  if (isObject(existing) && existing.v === SHARED_STATE_LAYOUT) return existing;
+  debugLog(
+    `another copy of @autter/runtime-node uses shared state layout ${String(isObject(existing) ? existing.v : typeof existing)}; this copy (${VERSION}, layout ${SHARED_STATE_LAYOUT}) keeps its own state`
+  );
+  return fresh;
+}
+var shared = resolveShared();
+function sharedSlot(name, init) {
+  const fresh = init();
+  try {
+    const existing = shared[name];
+    if (!isObject(existing)) {
+      shared[name] = fresh;
+      return fresh;
+    }
+    for (const [key, value] of Object.entries(fresh)) {
+      if (existing[key] === void 0) existing[key] = value;
+    }
+    return existing;
+  } catch (e2) {
+    return fresh;
+  }
+}
+
 // src/compat.ts
 var SDK_IDENTITY = {
   name: "@autter/runtime-node",
@@ -556,7 +636,7 @@ function compatRequest(method, url, options = {}) {
       if (options.unref !== false) req.on("socket", (socket) => socket.unref());
       req.on("error", () => done(null));
       req.end(options.body);
-    } catch (e) {
+    } catch (e3) {
       done(null);
     }
   });
@@ -569,7 +649,7 @@ async function fetchIngesterCompat(endpoint, options = {}) {
     let report = null;
     try {
       report = JSON.parse(res.body);
-    } catch (e2) {
+    } catch (e4) {
     }
     const info = _nullishCoalesce(ingesterInfoFromReport(report), () => ( headerInfo(res.headers)));
     return info ? { info, report } : { info: null, report, error: "unrecognised /v1/compat response" };
@@ -600,7 +680,7 @@ function envDisabled() {
   return value === "0" || value === "false" || value === "off";
 }
 var defaultWarn = (message) => console.warn(`[autter-runtime] ${message}`);
-var state = freshState(null, false);
+var compat = sharedSlot("compat", () => ({ state: freshState(null, false) }));
 function freshState(endpoint, enabled, sdk = SDK_IDENTITY, warn = defaultWarn) {
   return {
     endpoint,
@@ -615,7 +695,7 @@ function freshState(endpoint, enabled, sdk = SDK_IDENTITY, warn = defaultWarn) {
   };
 }
 function configureCompatCheck(options) {
-  state = freshState(
+  compat.state = freshState(
     options.endpoint.replace(/\/$/, ""),
     options.enabled !== false && !envDisabled(),
     _nullishCoalesce(options.sdk, () => ( SDK_IDENTITY)),
@@ -623,23 +703,23 @@ function configureCompatCheck(options) {
   );
 }
 function ensureCompatConfigured(endpoint) {
-  if (state.endpoint === null && !envDisabled()) {
-    state = freshState(endpoint.replace(/\/$/, ""), true);
+  if (compat.state.endpoint === null && !envDisabled()) {
+    compat.state = freshState(endpoint.replace(/\/$/, ""), true);
   }
 }
 function noteCompatFeature(id) {
   try {
-    if (!state.enabled || state.features.has(id) || !featureById(id)) return;
-    state.features.add(id);
-    if (state.info) {
+    if (!compat.state.enabled || compat.state.features.has(id) || !featureById(id)) return;
+    compat.state.features.add(id);
+    if (compat.state.info) {
       evaluateAndWarn();
       return;
     }
-    if (state.started) return;
-    state.started = true;
-    const current = state;
+    if (compat.state.started) return;
+    compat.state.started = true;
+    const current = compat.state;
     setTimeout(() => void runCheck(current), 0).unref();
-  } catch (e3) {
+  } catch (e5) {
   }
 }
 async function runCheck(current) {
@@ -648,7 +728,7 @@ async function runCheck(current) {
     const { info, error } = await fetchIngesterCompat(current.endpoint, {
       probeRoutes: routesFor(current.features)
     });
-    if (state !== current) return;
+    if (compat.state !== current) return;
     if (!info) {
       debugLog(`compat check skipped: ${_nullishCoalesce(error, () => ( "ingester version unknown"))}`);
       return;
@@ -672,8 +752,8 @@ function routesFor(features) {
   return routes;
 }
 function mergeInfo(next) {
-  const prev = state.info;
-  state.info = {
+  const prev = compat.state.info;
+  compat.state.info = {
     version: _nullishCoalesce(_nullishCoalesce(next.version, () => ( _optionalChain([prev, 'optionalAccess', _21 => _21.version]))), () => ( null)),
     ...next.legacy || _optionalChain([prev, 'optionalAccess', _22 => _22.legacy]) ? { legacy: true } : {},
     ..._nullishCoalesce(next.schema, () => ( _optionalChain([prev, 'optionalAccess', _23 => _23.schema]))) ? { schema: _nullishCoalesce(next.schema, () => ( _optionalChain([prev, 'optionalAccess', _24 => _24.schema]))) } : {},
@@ -681,17 +761,17 @@ function mergeInfo(next) {
   };
 }
 function evaluateAndWarn() {
-  const info = state.info;
+  const info = compat.state.info;
   if (!info) return;
-  if (info.version === null && state.endpoint) {
-    const unprobed = routesFor(state.features).filter(
-      (route) => _optionalChain([info, 'access', _26 => _26.routes, 'optionalAccess', _27 => _27[route]]) === void 0 && !state.pendingProbes.has(route)
+  if (info.version === null && compat.state.endpoint) {
+    const unprobed = routesFor(compat.state.features).filter(
+      (route) => _optionalChain([info, 'access', _26 => _26.routes, 'optionalAccess', _27 => _27[route]]) === void 0 && !compat.state.pendingProbes.has(route)
     );
     if (unprobed.length) {
-      const current = state;
+      const current = compat.state;
       for (const route of unprobed) current.pendingProbes.add(route);
       void Promise.all(unprobed.map((route) => probeRoute(current.endpoint, route, {}).then((exists) => [route, exists]))).then((results) => {
-        if (state !== current) return;
+        if (compat.state !== current) return;
         const routes = {};
         for (const [route, exists] of results) if (exists !== null) routes[route] = exists;
         mergeInfo({ version: null, legacy: true, routes });
@@ -700,56 +780,56 @@ function evaluateAndWarn() {
       });
     }
   }
-  for (const issue of evaluateCompat({ features: state.features, ingester: info })) {
+  for (const issue of evaluateCompat({ features: compat.state.features, ingester: info })) {
     warnOnce(issue);
   }
 }
 function warnOnce(issue) {
   const key = `${issue.feature}:${issue.kind}`;
-  if (state.warned.has(key)) return;
-  state.warned.add(key);
+  if (compat.state.warned.has(key)) return;
+  compat.state.warned.add(key);
   try {
-    state.warn(issue.message);
-  } catch (e4) {
+    compat.state.warn(issue.message);
+  } catch (e6) {
   }
 }
 function observeIngesterResponse(response) {
   try {
-    if (!state.enabled) return;
+    if (!compat.state.enabled) return;
     const fromHeader = headerInfo(response.headers);
     if (fromHeader) {
-      if (_optionalChain([state, 'access', _28 => _28.info, 'optionalAccess', _29 => _29.version]) !== fromHeader.version) {
+      if (_optionalChain([compat, 'access', _28 => _28.state, 'access', _29 => _29.info, 'optionalAccess', _30 => _30.version]) !== fromHeader.version) {
         mergeInfo(fromHeader);
         evaluateAndWarn();
       }
       return;
     }
-    if (response.status === 404 && response.route && !_optionalChain([state, 'access', _30 => _30.info, 'optionalAccess', _31 => _31.version])) {
+    if (response.status === 404 && response.route && !_optionalChain([compat, 'access', _31 => _31.state, 'access', _32 => _32.info, 'optionalAccess', _33 => _33.version])) {
       mergeInfo({ version: null, legacy: true, routes: { [response.route]: false } });
       evaluateAndWarn();
     }
-  } catch (e5) {
+  } catch (e7) {
   }
 }
 function noteRelayRejection(eventTypes, status, headers) {
   try {
-    if (!state.enabled || status !== 400 || headerInfo(headers)) return [];
+    if (!compat.state.enabled || status !== 400 || headerInfo(headers)) return [];
     const named = [];
     for (const id of featuresForBrowserEvents(eventTypes)) {
       const feature = featureById(id);
       const key = `${id}:relay_rejected`;
-      if (state.warned.has(key)) continue;
-      state.warned.add(key);
+      if (compat.state.warned.has(key)) continue;
+      compat.state.warned.add(key);
       named.push(id);
       try {
-        state.warn(
+        compat.state.warn(
           `The ingester rejected a browser batch containing ${feature.title.toLowerCase()} events. ${feature.title} needs ingester >= ${feature.ingester}; yours is 1.4.0 or older (it predates version reporting), so those batches are dropped. ${ingesterUpgradeHint(COMPAT_MANIFEST)}`
         );
-      } catch (e6) {
+      } catch (e8) {
       }
     }
     return named;
-  } catch (e7) {
+  } catch (e9) {
     return [];
   }
 }
@@ -776,4 +856,5 @@ function noteRelayRejection(eventTypes, status, headers) {
 
 
 
-exports.COMPAT_MANIFEST = COMPAT_MANIFEST; exports.INGESTER_VERSION_HEADER = INGESTER_VERSION_HEADER; exports.versionAtLeast = versionAtLeast; exports.featuresForBrowserEvents = featuresForBrowserEvents; exports.evaluateCompat = evaluateCompat; exports.setDebugMode = setDebugMode; exports.isDebugEnabled = isDebugEnabled; exports.debugLog = debugLog; exports.telemetryStats = telemetryStats; exports.CountingExporter = CountingExporter; exports.registerFlushTarget = registerFlushTarget; exports.unregisterFlushTargets = unregisterFlushTargets; exports.installAutterAutoFlush = installAutterAutoFlush; exports.SDK_IDENTITY = SDK_IDENTITY; exports.compatRequest = compatRequest; exports.fetchIngesterCompat = fetchIngesterCompat; exports.configureCompatCheck = configureCompatCheck; exports.ensureCompatConfigured = ensureCompatConfigured; exports.noteCompatFeature = noteCompatFeature; exports.observeIngesterResponse = observeIngesterResponse; exports.noteRelayRejection = noteRelayRejection;
+
+exports.COMPAT_MANIFEST = COMPAT_MANIFEST; exports.INGESTER_VERSION_HEADER = INGESTER_VERSION_HEADER; exports.versionAtLeast = versionAtLeast; exports.featuresForBrowserEvents = featuresForBrowserEvents; exports.evaluateCompat = evaluateCompat; exports.setDebugMode = setDebugMode; exports.isDebugEnabled = isDebugEnabled; exports.debugLog = debugLog; exports.telemetryStats = telemetryStats; exports.CountingExporter = CountingExporter; exports.registerFlushTarget = registerFlushTarget; exports.unregisterFlushTargets = unregisterFlushTargets; exports.installAutterAutoFlush = installAutterAutoFlush; exports.sharedSlot = sharedSlot; exports.SDK_IDENTITY = SDK_IDENTITY; exports.compatRequest = compatRequest; exports.fetchIngesterCompat = fetchIngesterCompat; exports.configureCompatCheck = configureCompatCheck; exports.ensureCompatConfigured = ensureCompatConfigured; exports.noteCompatFeature = noteCompatFeature; exports.observeIngesterResponse = observeIngesterResponse; exports.noteRelayRejection = noteRelayRejection;