@autter/runtime-node 1.7.0 → 1.9.0

package/dist/index.js

@@ -8,6 +8,7 @@ import {
   compileIgnore,
   configureRuntimeLogger,
   consoleSink,
+  createErrorFilter,
   createRequestState,
   createRuntimeLogger,
   currentOperation,
@@ -20,10 +21,12 @@ import {
   fingerprintEventAttributes,
   fingerprintValues,
   flushRuntimeLogs,
+  isCaptured,
   isError,
   isRuntimeErrorLike,
   local,
   makeRedactor,
+  markCaptured,
   normalizeRoutePath,
   noteOperationError,
   notifyException,
@@ -41,14 +44,17 @@ import {
   runtimeLogStats,
   runtimeLogger,
   sanitizeBreadcrumbs,
+  setHandledCapture,
   shutdownRuntimeLogger,
   splitFingerprint,
+  startLoggedErrorCapture,
+  stopLoggedErrorCapture,
   toClientError,
   withRuntimeOperation
-} from "./chunk-KA4AOZX2.js";
+} from "./chunk-HHKQ3UCH.js";
 import {
   runDoctor
-} from "./chunk-QUC6OUE7.js";
+} from "./chunk-JSGGUWRD.js";
 import {
   COMPAT_MANIFEST,
   CountingExporter,
@@ -70,7 +76,7 @@ import {
   sharedSlot,
   telemetryStats,
   unregisterFlushTargets
-} from "./chunk-LG52CW3V.js";
+} from "./chunk-ZKM76SDP.js";
 
 // src/relay.ts
 var IpWindow = class {
@@ -95,6 +101,112 @@ function firstForwardedFor(value) {
   const raw = Array.isArray(value) ? value[0] : value;
   return raw ? (raw.split(",")[0] ?? "").trim() : "";
 }
+var TRUST_AUTO = { mode: "auto" };
+var warnedTrustProxy = false;
+function resolveTrustProxy(value) {
+  if (value === void 0 || value === null || value === "auto") return TRUST_AUTO;
+  if (value === true) return { mode: "all" };
+  if (value === false || value === 0) return { mode: "never" };
+  if (typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 100) {
+    return { mode: "hops", hops: value };
+  }
+  if (typeof value === "string") {
+    const v = value.trim().toLowerCase();
+    if (v === "" || v === "auto") return TRUST_AUTO;
+    if (v === "false" || v === "0" || v === "no" || v === "off") return { mode: "never" };
+    if (v === "true" || v === "yes" || v === "on") return { mode: "all" };
+    if (/^[1-9][0-9]?$/.test(v)) return { mode: "hops", hops: Number(v) };
+  }
+  if (!warnedTrustProxy) {
+    warnedTrustProxy = true;
+    console.warn(
+      `[autter-runtime] relay: trustProxy ${JSON.stringify(value)} is not recognised; using "auto".`
+    );
+  }
+  return TRUST_AUTO;
+}
+var IPV4_RE = /^(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}$/;
+function normalizeAddress(entry) {
+  if (!entry) return null;
+  let a = entry.trim();
+  if (!a || a.length > 64) return null;
+  const bracketed = /^\[([0-9A-Fa-f:.]+)\](?::\d{1,5})?$/.exec(a);
+  if (bracketed) a = bracketed[1] ?? "";
+  else if (/^[\d.]+:\d{1,5}$/.test(a)) a = a.slice(0, a.lastIndexOf(":"));
+  a = a.toLowerCase();
+  if (a.startsWith("::ffff:") && IPV4_RE.test(a.slice(7))) a = a.slice(7);
+  if (IPV4_RE.test(a)) return a;
+  if (/^[0-9a-f:]+(:(\d{1,3}\.){3}\d{1,3})?$/.test(a) && a.includes(":") && a.split(":").length <= 9) {
+    return a;
+  }
+  return null;
+}
+function isPrivateAddress(a) {
+  if (IPV4_RE.test(a)) {
+    const [x, y] = a.split(".").map(Number);
+    return x === 10 || x === 127 || x === 0 || x === 169 && y === 254 || x === 172 && y >= 16 && y <= 31 || x === 192 && y === 168 || x === 100 && y >= 64 && y <= 127;
+  }
+  return a === "::1" || a === "::" || /^f[cd]/.test(a) || /^fe[89ab]/.test(a);
+}
+function forwardedEntries(value) {
+  const raw = Array.isArray(value) ? value.join(",") : value;
+  if (!raw) return [];
+  const out = [];
+  for (const part of raw.split(",")) {
+    const a = normalizeAddress(part);
+    if (a) out.push(a);
+  }
+  return out;
+}
+function rightmostPublic(entries) {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const a = entries[i];
+    if (a && !isPrivateAddress(a)) return a;
+  }
+  return null;
+}
+function fromCustom(opts, request) {
+  if (!opts.clientIp) return null;
+  try {
+    const v = opts.clientIp(request);
+    return typeof v === "string" && v.trim() ? v.trim().slice(0, 64) : null;
+  } catch {
+    return null;
+  }
+}
+function fetchClientKey(request, opts) {
+  const custom = fromCustom(opts, request);
+  if (custom) return custom;
+  const trust = resolveTrustProxy(opts.trustProxy);
+  if (trust.mode === "never") return "shared";
+  const header = request.headers.get("x-forwarded-for");
+  if (trust.mode === "all") return firstForwardedFor(header) || "shared";
+  const entries = forwardedEntries(header);
+  if (trust.mode === "hops") {
+    return entries[Math.max(0, entries.length - trust.hops)] ?? "shared";
+  }
+  const cf = request.cf;
+  if (cf !== null && typeof cf === "object") {
+    const viaCf = normalizeAddress(request.headers.get("cf-connecting-ip"));
+    if (viaCf) return viaCf;
+  }
+  return rightmostPublic(entries) ?? entries[entries.length - 1] ?? "shared";
+}
+function nodeClientKey(req, opts) {
+  const custom = fromCustom(opts, req);
+  if (custom) return custom;
+  const trust = resolveTrustProxy(opts.trustProxy);
+  const peer = normalizeAddress(req.socket?.remoteAddress);
+  if (trust.mode === "never") return peer ?? "unknown";
+  const header = req.headers["x-forwarded-for"];
+  if (trust.mode === "all") return firstForwardedFor(header) || peer || "unknown";
+  const entries = forwardedEntries(header);
+  if (trust.mode === "hops") {
+    return entries[Math.max(0, entries.length - trust.hops)] ?? peer ?? "unknown";
+  }
+  if (peer && !isPrivateAddress(peer)) return peer;
+  return rightmostPublic(entries) ?? peer ?? entries[entries.length - 1] ?? "unknown";
+}
 var DEFAULT_ENDPOINT = "https://otlp.autter.dev";
 var DEFAULT_MAX_BODY = 64 * 1024;
 var MAX_EVENTS = 50;
@@ -328,7 +440,7 @@ function createBrowserRelayFetchHandler(opts) {
       return new Response(null, { status: 405 });
     }
     if (limiter) {
-      const ip = firstForwardedFor(request.headers.get("x-forwarded-for")) || "unknown";
+      const ip = fetchClientKey(request, opts);
       if (!limiter.allow(ip)) {
         return new Response(JSON.stringify({ error: "rate limit exceeded" }), {
           status: 429
@@ -394,7 +506,7 @@ function createBrowserRelayHandler(opts) {
       return;
     }
     if (limiter) {
-      const ip = firstForwardedFor(req.headers["x-forwarded-for"]) || req.socket?.remoteAddress || "unknown";
+      const ip = nodeClientKey(req, opts);
       if (!limiter.allow(ip)) {
         respond(res, 429, { error: "rate limit exceeded" });
         return;
@@ -745,7 +857,6 @@ import { context, trace } from "@opentelemetry/api";
 import { getRPCMetadata, RPCType } from "@opentelemetry/core";
 var REQUEST_STATE = /* @__PURE__ */ Symbol.for("autter.runtime.request");
 var BOUND = /* @__PURE__ */ Symbol.for("autter.runtime.bound");
-var CAPTURED = sharedSlot("requests", () => ({ captured: /* @__PURE__ */ new WeakSet() })).captured;
 var capturer = () => {
 };
 function setRequestExceptionCapturer(fn) {
@@ -756,8 +867,14 @@ var annotator = () => {
 function setRequestSpanAnnotator(fn) {
   annotator = fn;
 }
-function markCaptured(error) {
-  if (error && typeof error === "object") CAPTURED.add(error);
+function decide(rule, error, fallback) {
+  if (rule === void 0) return fallback;
+  if (typeof rule !== "function") return rule;
+  try {
+    return rule(error) === true;
+  } catch {
+    return false;
+  }
 }
 function expressRouteOf(req) {
   const props = req;
@@ -788,7 +905,7 @@ function captureAtBoundary(error, state, rule = void 0, attributes) {
     wanted = false;
   }
   if (!wanted) return;
-  if (error && typeof error === "object" && CAPTURED.has(error)) return;
+  if (isCaptured(error)) return;
   markCaptured(error);
   try {
     const run = () => onRequestSpan(() => capturer(error, attributes));
@@ -802,7 +919,7 @@ function requestStateOf(req) {
   return req[REQUEST_STATE];
 }
 function captureRequestError(error, attributes) {
-  if (error && typeof error === "object" && CAPTURED.has(error)) {
+  if (isCaptured(error)) {
     if (!attributes) return;
     try {
       onRequestSpan(() => annotator(attributes));
@@ -894,7 +1011,8 @@ function finishRequest(state, input) {
     ...state.error !== void 0 ? { error: state.error } : {},
     ...state.errorThrown ? { thrown: true } : {},
     status: input.status,
-    aborted: input.aborted
+    aborted: input.aborted,
+    ...state.degraded ? { degraded: true } : {}
   });
   const span = trace.getActiveSpan();
   if (span?.isRecording()) span.setAttribute("autter.operation.outcome", state.outcome);
@@ -1119,9 +1237,15 @@ function withRuntimeRequest(handler, options = {}) {
         try {
           return await handler(request, ...rest);
         } catch (error) {
-          noteOperationError(error, true, state);
-          captureAtBoundary(error, state, true);
-          throw error;
+          if (decide(options.capture, error, true)) {
+            noteOperationError(error, true, state);
+            captureAtBoundary(error, state, true);
+          }
+          if (!decide(options.errorResponse, error, false)) throw error;
+          return new Response(JSON.stringify(toClientError(error, requestId)), {
+            status: responseStatusOf(error),
+            headers: { "content-type": "application/json; charset=utf-8" }
+          });
         }
       });
       status = response.status;
@@ -1319,6 +1443,8 @@ var S = sharedSlot("server", () => ({
   alwaysOnProvider: null,
   redactor: makeRedactor(true),
   loggerOnlyCapture: null,
+  handled: null,
+  loggerOnlyHandled: null,
   hookRequests: false
 }));
 var LLM_MARKER_ATTRIBUTES = [
@@ -1718,6 +1844,7 @@ function initAutterServer(options) {
     // its span-fed per-route counts.
     "autter.metrics_routes": true
   });
+  const errorFilter = createErrorFilter({ ignoreErrors: options.ignoreErrors, sampleRate: options.sampleRate });
   const rootSampler = new TraceIdRatioBasedSampler(options.traceSampleRate ?? 0.01);
   const headSampler = new ParentBasedSampler({
     root: rootSampler,
@@ -1793,6 +1920,16 @@ function initAutterServer(options) {
   const processTracer = alwaysOnProvider.getTracer("autter-processes");
   const llmTracer = alwaysOnProvider.getTracer("autter-llm");
   function captureException2(error, attributes) {
+    const isErrValue = isError(error);
+    const reported = errorFilter({
+      type: isErrValue ? String(error.name ?? "") : "Error",
+      message: isErrValue ? String(error.message ?? "") : String(error),
+      crash: attributes?.["autter.unhandled"] === true || attributes?.["autter.unhandled_rejection"] === true
+    });
+    if (!reported) {
+      markCaptured(error);
+      return;
+    }
     errorTraceBuffer?.retainActiveTrace();
     telemetryStats.markCaptured();
     const isErr = isError(error);
@@ -1845,6 +1982,7 @@ function initAutterServer(options) {
     if (!reuseActive) span.end();
   }
   function captureMessage2(message, severity = "warning", attributes) {
+    if (!errorFilter({ type: "Message", message: String(message), severity })) return;
     if (severity === "error" || severity === "fatal") {
       errorTraceBuffer?.retainActiveTrace();
     }
@@ -1865,6 +2003,7 @@ function initAutterServer(options) {
     span.end();
   }
   function reportOutcome2(name, message, attributes) {
+    if (!errorFilter({ type: "OutcomeFailure", message: `${name}: ${message}` })) return;
     errorTraceBuffer?.retainActiveTrace();
     telemetryStats.markCaptured();
     const activeSpan = trace2.getActiveSpan();
@@ -1882,6 +2021,37 @@ function initAutterServer(options) {
     span.setStatus({ code: SpanStatusCode.ERROR, message: safeMessage });
     if (!reuseActive) span.end();
   }
+  function captureHandled(error, attributes, severity) {
+    const isErr = isError(error);
+    if (!errorFilter({
+      type: isErr ? String(error.name ?? "") : "Error",
+      message: isErr ? String(error.message ?? "") : String(error),
+      severity
+    })) return;
+    if (severity === "error") errorTraceBuffer?.retainActiveTrace();
+    telemetryStats.markCaptured();
+    const message = redactor.text(isErr ? error.message : String(error));
+    const stack = isErr && error.stack ? error.stack : new Error().stack?.split("\n").filter((line, i) => i === 0 || !/captureHandled|report(?:Degraded|LoggedError)/.test(line)).join("\n");
+    const split = splitFingerprint(attributes);
+    const fingerprint = fingerprintEventAttributes(split.fingerprint, redactor.text);
+    const redacted = redactor(split.attributes);
+    const activeSpan = trace2.getActiveSpan();
+    const reuseActive = activeSpan?.isRecording() === true;
+    const span = reuseActive ? activeSpan : errorTracer.startSpan(isErr ? error.name : "Error");
+    markCaptured(error);
+    notifyException(error, { ...redacted, ...fingerprint, "autter.severity": severity });
+    span.addEvent("exception", {
+      ...redacted,
+      "exception.type": isErr ? error.name : "Error",
+      "exception.message": message,
+      ...stack ? { "exception.stacktrace": redactor.text(stack) } : {},
+      "autter.severity": severity,
+      ...errorAttributes(error),
+      ...fingerprint,
+      ...breadcrumbEventAttributes(redactor.text, error)
+    });
+    if (!reuseActive) span.end();
+  }
   configureRuntimeLogger({
     endpoint,
     apiKey: options.apiKey,
@@ -1895,6 +2065,8 @@ function initAutterServer(options) {
     reportOutcome: reportOutcome2
   });
   S.hookRequests = options.logging?.requests === true;
+  S.handled = captureHandled;
+  startLoggedErrorCapture(options.captureLoggedErrors);
   let onCrash = null;
   let uninstallRejections = null;
   if (options.captureGlobalErrors !== false) {
@@ -1941,6 +2113,7 @@ function initAutterServer(options) {
     withLlmCall: (info, fn) => runLlmSpan(llmTracer, info, fn),
     trackLlmCall: (call) => recordLlmCall(llmTracer, call),
     shutdown: async () => {
+      if (S.active === server) stopLoggedErrorCapture();
       const logShutdown = await Promise.allSettled([shutdownRuntimeLogger()]);
       if (onCrash) process.off("uncaughtExceptionMonitor", onCrash);
       uninstallRejections?.();
@@ -1948,6 +2121,7 @@ function initAutterServer(options) {
       if (S.active === server) {
         S.active = null;
         S.alwaysOnProvider = null;
+        S.handled = null;
         S.hookRequests = false;
         S.redactor = makeRedactor(true);
       }
@@ -1983,13 +2157,39 @@ function captureException(error, attributes) {
   recordError(span, error);
   span.end();
 }
-function setLoggerOnlyCapture(fn) {
+function setLoggerOnlyCapture(fn, handled = null) {
   S.loggerOnlyCapture = fn;
+  S.loggerOnlyHandled = handled;
+}
+function captureHandledError(error, attributes, severity) {
+  if (S.active) {
+    S.handled?.(error, attributes, severity);
+    return;
+  }
+  if (S.loggerOnlyHandled) {
+    S.loggerOnlyHandled(error, attributes, severity);
+    return;
+  }
+  markCaptured(error);
+  const split = splitFingerprint(attributes);
+  notifyException(error, { ...split.attributes, "autter.severity": severity });
+  const span = trace2.getTracer("autter-errors").startSpan(isError(error) ? error.name : "Error");
+  span.addEvent("exception", {
+    ...S.redactor(split.attributes),
+    "exception.type": isError(error) ? error.name : "Error",
+    "exception.message": S.redactor.text(isError(error) ? error.message : String(error)),
+    ...isError(error) && error.stack ? { "exception.stacktrace": S.redactor.text(error.stack) } : {},
+    "autter.severity": severity,
+    ...errorAttributes(error),
+    ...fingerprintEventAttributes(split.fingerprint, S.redactor.text)
+  });
+  span.end();
 }
 function serverActive() {
   return S.active !== null;
 }
 setRequestExceptionCapturer((error, attributes) => captureException(error, attributes));
+setHandledCapture(captureHandledError);
 setRequestSpanAnnotator((attributes) => {
   const span = trace2.getActiveSpan();
   if (span?.isRecording()) span.setAttributes(S.redactor(splitFingerprint(attributes).attributes));
@@ -2418,8 +2618,16 @@ function initAutterLogging(options) {
   const redact = makeRedactor(options.redactAttributes ?? true);
   const mode = options.exceptions ?? "auto";
   debugLog(`initialising logger-only service=${options.service} endpoint=${endpoint}`);
+  const errorFilter = createErrorFilter({ ignoreErrors: options.ignoreErrors, sampleRate: options.sampleRate });
   function captureException2(error, attributes) {
     markCaptured(error);
+    const isErrValue = isError(error);
+    const reported = errorFilter({
+      type: isErrValue ? String(error.name ?? "") : "Error",
+      message: isErrValue ? String(error.message ?? "") : String(error),
+      crash: attributes?.["autter.unhandled"] === true || attributes?.["autter.unhandled_rejection"] === true
+    });
+    if (!reported) return;
     const split = splitFingerprint(attributes);
     const fingerprint = fingerprintEventAttributes(split.fingerprint, redact.text);
     const redacted = redact(split.attributes);
@@ -2452,6 +2660,33 @@ function initAutterLogging(options) {
     notifyException(error, { ...redacted, ...fingerprint });
     captureExceptionAsLog(error, { ...redacted, ...fingerprint });
   }
+  function captureHandled(error, attributes, severity) {
+    markCaptured(error);
+    const isErrValue = isError(error);
+    if (!errorFilter({
+      type: isErrValue ? String(error.name ?? "") : "Error",
+      message: isErrValue ? String(error.message ?? "") : String(error),
+      severity
+    })) return;
+    const split = splitFingerprint(attributes);
+    const fingerprint = fingerprintEventAttributes(split.fingerprint, redact.text);
+    const redacted = redact(split.attributes);
+    notifyException(error, { ...redacted, ...fingerprint, "autter.severity": severity });
+    const span = trace3.getActiveSpan();
+    if (mode === "auto" && span?.isRecording()) {
+      span.addEvent("exception", {
+        ...redacted,
+        "exception.type": isErrValue ? error.name : "Error",
+        "exception.message": redact.text(isErrValue ? error.message : String(error)),
+        ...isErrValue && error.stack ? { "exception.stacktrace": redact.text(error.stack) } : {},
+        "autter.severity": severity,
+        ...errorAttributes(error),
+        ...fingerprint
+      });
+      return;
+    }
+    captureExceptionAsLog(error, { ...redacted, ...fingerprint }, severity);
+  }
   const captured = /* @__PURE__ */ new WeakSet();
   configureRuntimeLogger({
     endpoint,
@@ -2476,7 +2711,8 @@ function initAutterLogging(options) {
       captureException2(error);
     }
   });
-  setLoggerOnlyCapture(captureException2);
+  setLoggerOnlyCapture(captureException2, captureHandled);
+  startLoggedErrorCapture(options.captureLoggedErrors);
   const onCrash = (error) => {
     if (recordedAsRejection(error)) return;
     captureException2(error, { "autter.unhandled": true });
@@ -2495,6 +2731,7 @@ function initAutterLogging(options) {
     captureException: captureException2,
     flush: flushRuntimeLogs,
     shutdown: async () => {
+      if (L.active === handle) stopLoggedErrorCapture();
       process.off("uncaughtExceptionMonitor", onCrash);
       uninstallRejections?.();
       uninstallRejections = null;

package/dist/{sinks-CPGDyfU8.d.ts → sinks-CLtQFPnn.d.cts}

@@ -166,10 +166,19 @@ declare function isRuntimeErrorLike(err: unknown): err is RuntimeErrorLike;
 interface ErrorAttributeOptions {
     /** Also emit `exception.cause.N.*` for the cause chain (default true). */
     causes?: boolean;
+    /**
+     * With `causes`, also emit what only an occurrence record needs (default
+     * true): each cause's stack (`exception.cause.N.stacktrace`, RF-06: a
+     * wrapped error groups with its root cause) and the debug ids of the
+     * bundles in the stacks (`autter.debug_ids`, RF-05: server source maps).
+     * Request and operation summaries pass false.
+     */
+    stacks?: boolean;
 }
 /**
- * Wire attributes for an error: `autter.error.code|why|fix|link|status|expected`
- * and `exception.cause.N.type|message|code` (N = 1..5). Never includes
+ * Wire attributes for an error: `autter.error.code|why|fix|link|status|expected`,
+ * `exception.cause.N.type|message|code|stacktrace` (N = 1..5) and
+ * `autter.debug_ids` (see ErrorAttributeOptions.stacks). Never includes
  * `internal` — see `errorInternal`.
  */
 declare function errorAttributes(err: unknown, options?: ErrorAttributeOptions): Record<string, string | number | boolean>;
@@ -250,6 +259,53 @@ interface BreadcrumbInput {
     at?: string | number | Date;
 }
 
+/**
+ * Handled errors (RF-01, RF-02): the building blocks every server SDK shares
+ * for errors the app caught instead of letting them crash.
+ *
+ * - Caught errors: an `Error` the app passes to `console.error`, a logger
+ *   (pino, winston, bunyan) or `runtimeLogger.error` is reported as an
+ *   occurrence at `error` severity, marked `autter.handled = true`,
+ *   `autter.handling = "caught"`, with the log line as context
+ *   (`autter.log.source`, `autter.log.message`).
+ * - Deliberate fallbacks: `runtimeContext.degraded(err, reason)` reports the
+ *   error at `warning` severity (never an incident), marked
+ *   `autter.handling = "deliberate"` with `autter.degraded.reason`.
+ *
+ * A burst limit keeps a looping error from flooding: per kind (error type
+ * and throw site) ten at once, then one every ten seconds. What it leaves
+ * out is counted, and the count rides on the next record of that kind as
+ * `autter.caught.dropped`, which the ingester adds to `runtime_ingest_drops`
+ * (reason `caught_limited`).
+ */
+type LoggedErrorSource = "console" | "pino" | "winston" | "bunyan" | "runtimeLogger";
+/**
+ * `captureLoggedErrors`: `true` (default) reports errors logged through
+ * every source the SDK supports, `false` none; an object turns single
+ * sources off, e.g. `{ console: false }`.
+ */
+type CaptureLoggedErrorsOption = boolean | Partial<Record<LoggedErrorSource, boolean>>;
+
+/**
+ * Client-side volume control shared by the server SDKs (runtime-node,
+ * runtime-edge; 1.8.0 / 1.2.0, EI-38): `ignoreErrors` and `sampleRate`.
+ * The browser has its own copy in `@autter/runtime-browser/filters`.
+ *
+ * - `ignoreErrors`: strings or RegExps. A string matches when the error's
+ *   type or message contains it (case-sensitive, like the message itself);
+ *   a RegExp is tested against the type, the message and
+ *   `"<type>: <message>"`. A match is never reported, whatever its severity.
+ * - `sampleRate`: 0..1, the share of errors reported. Errors only: warnings
+ *   and info messages are never sampled, and neither is a fatal error, a
+ *   crash (uncaught exception) or an unhandled rejection, which may be one.
+ *   Out of range or not a number: everything is reported.
+ *
+ * What is filtered here never leaves the process and is counted nowhere.
+ * To leave errors out of every SDK at once, and see how many were left out,
+ * use suppression rules in Autter (applied by the ingester, 1.9.0).
+ */
+type IgnoreErrorPattern = string | RegExp;
+
 /**
  * Where runtime records go. The logger pipeline is
  * `enrich → redact/bound → sinks[]`; each sink receives the same immutable
@@ -338,4 +394,4 @@ interface MemorySink extends RuntimeSink {
 /** Keeps every record in memory — for tests (`@autter/runtime-node/testing`). */
 declare function memorySink(): MemorySink;
 
-export { errorAttributes as A, type BreadcrumbInput as B, type CapturedException as C, fileSink as D, isRuntimeErrorLike as E, type FileSinkOptions as F, otlpSink as G, redactAttributes as H, redactText as I, toClientError as J, type MemorySink as M, type OtlpSinkOptions as O, type RuntimeEvent as R, type RuntimeOutcome as a, type RedactOptions as b, type Redactor$1 as c, type RuntimeLogLevel as d, type RuntimeOperationKind as e, type RuntimeSink as f, type RuntimeLogContext as g, type RuntimeCarrier as h, type Breadcrumb as i, type BreadcrumbLevel as j, type BreadcrumbType as k, CODE_PATTERN as l, memorySink as m, type ClientErrorBody as n, type ConsoleSinkOptions as o, RuntimeError as p, type RuntimeErrorCatalog as q, type RuntimeErrorDefinition as r, type RuntimeErrorExtras as s, type RuntimeErrorFactory as t, type RuntimeErrorLike as u, type RuntimeErrorOptions as v, type RuntimeLogContextValue as w, type RuntimeSinkContext as x, consoleSink as y, defineRuntimeErrors as z };
+export { defineRuntimeErrors as A, type BreadcrumbInput as B, type CapturedException as C, errorAttributes as D, fileSink as E, type FileSinkOptions as F, isRuntimeErrorLike as G, otlpSink as H, type IgnoreErrorPattern as I, redactAttributes as J, redactText as K, type LoggedErrorSource as L, type MemorySink as M, toClientError as N, type OtlpSinkOptions as O, type RuntimeEvent as R, type RuntimeOutcome as a, type RedactOptions as b, type Redactor$1 as c, type RuntimeLogLevel as d, type RuntimeOperationKind as e, type RuntimeSink as f, type RuntimeLogContext as g, type RuntimeCarrier as h, type CaptureLoggedErrorsOption as i, type Breadcrumb as j, type BreadcrumbLevel as k, type BreadcrumbType as l, memorySink as m, CODE_PATTERN as n, type ClientErrorBody as o, type ConsoleSinkOptions as p, RuntimeError as q, type RuntimeErrorCatalog as r, type RuntimeErrorDefinition as s, type RuntimeErrorExtras as t, type RuntimeErrorFactory as u, type RuntimeErrorLike as v, type RuntimeErrorOptions as w, type RuntimeLogContextValue as x, type RuntimeSinkContext as y, consoleSink as z };

package/dist/{sinks-CPGDyfU8.d.cts → sinks-CLtQFPnn.d.ts}

@@ -166,10 +166,19 @@ declare function isRuntimeErrorLike(err: unknown): err is RuntimeErrorLike;
 interface ErrorAttributeOptions {
     /** Also emit `exception.cause.N.*` for the cause chain (default true). */
     causes?: boolean;
+    /**
+     * With `causes`, also emit what only an occurrence record needs (default
+     * true): each cause's stack (`exception.cause.N.stacktrace`, RF-06: a
+     * wrapped error groups with its root cause) and the debug ids of the
+     * bundles in the stacks (`autter.debug_ids`, RF-05: server source maps).
+     * Request and operation summaries pass false.
+     */
+    stacks?: boolean;
 }
 /**
- * Wire attributes for an error: `autter.error.code|why|fix|link|status|expected`
- * and `exception.cause.N.type|message|code` (N = 1..5). Never includes
+ * Wire attributes for an error: `autter.error.code|why|fix|link|status|expected`,
+ * `exception.cause.N.type|message|code|stacktrace` (N = 1..5) and
+ * `autter.debug_ids` (see ErrorAttributeOptions.stacks). Never includes
  * `internal` — see `errorInternal`.
  */
 declare function errorAttributes(err: unknown, options?: ErrorAttributeOptions): Record<string, string | number | boolean>;
@@ -250,6 +259,53 @@ interface BreadcrumbInput {
     at?: string | number | Date;
 }
 
+/**
+ * Handled errors (RF-01, RF-02): the building blocks every server SDK shares
+ * for errors the app caught instead of letting them crash.
+ *
+ * - Caught errors: an `Error` the app passes to `console.error`, a logger
+ *   (pino, winston, bunyan) or `runtimeLogger.error` is reported as an
+ *   occurrence at `error` severity, marked `autter.handled = true`,
+ *   `autter.handling = "caught"`, with the log line as context
+ *   (`autter.log.source`, `autter.log.message`).
+ * - Deliberate fallbacks: `runtimeContext.degraded(err, reason)` reports the
+ *   error at `warning` severity (never an incident), marked
+ *   `autter.handling = "deliberate"` with `autter.degraded.reason`.
+ *
+ * A burst limit keeps a looping error from flooding: per kind (error type
+ * and throw site) ten at once, then one every ten seconds. What it leaves
+ * out is counted, and the count rides on the next record of that kind as
+ * `autter.caught.dropped`, which the ingester adds to `runtime_ingest_drops`
+ * (reason `caught_limited`).
+ */
+type LoggedErrorSource = "console" | "pino" | "winston" | "bunyan" | "runtimeLogger";
+/**
+ * `captureLoggedErrors`: `true` (default) reports errors logged through
+ * every source the SDK supports, `false` none; an object turns single
+ * sources off, e.g. `{ console: false }`.
+ */
+type CaptureLoggedErrorsOption = boolean | Partial<Record<LoggedErrorSource, boolean>>;
+
+/**
+ * Client-side volume control shared by the server SDKs (runtime-node,
+ * runtime-edge; 1.8.0 / 1.2.0, EI-38): `ignoreErrors` and `sampleRate`.
+ * The browser has its own copy in `@autter/runtime-browser/filters`.
+ *
+ * - `ignoreErrors`: strings or RegExps. A string matches when the error's
+ *   type or message contains it (case-sensitive, like the message itself);
+ *   a RegExp is tested against the type, the message and
+ *   `"<type>: <message>"`. A match is never reported, whatever its severity.
+ * - `sampleRate`: 0..1, the share of errors reported. Errors only: warnings
+ *   and info messages are never sampled, and neither is a fatal error, a
+ *   crash (uncaught exception) or an unhandled rejection, which may be one.
+ *   Out of range or not a number: everything is reported.
+ *
+ * What is filtered here never leaves the process and is counted nowhere.
+ * To leave errors out of every SDK at once, and see how many were left out,
+ * use suppression rules in Autter (applied by the ingester, 1.9.0).
+ */
+type IgnoreErrorPattern = string | RegExp;
+
 /**
  * Where runtime records go. The logger pipeline is
  * `enrich → redact/bound → sinks[]`; each sink receives the same immutable
@@ -338,4 +394,4 @@ interface MemorySink extends RuntimeSink {
 /** Keeps every record in memory — for tests (`@autter/runtime-node/testing`). */
 declare function memorySink(): MemorySink;
 
-export { errorAttributes as A, type BreadcrumbInput as B, type CapturedException as C, fileSink as D, isRuntimeErrorLike as E, type FileSinkOptions as F, otlpSink as G, redactAttributes as H, redactText as I, toClientError as J, type MemorySink as M, type OtlpSinkOptions as O, type RuntimeEvent as R, type RuntimeOutcome as a, type RedactOptions as b, type Redactor$1 as c, type RuntimeLogLevel as d, type RuntimeOperationKind as e, type RuntimeSink as f, type RuntimeLogContext as g, type RuntimeCarrier as h, type Breadcrumb as i, type BreadcrumbLevel as j, type BreadcrumbType as k, CODE_PATTERN as l, memorySink as m, type ClientErrorBody as n, type ConsoleSinkOptions as o, RuntimeError as p, type RuntimeErrorCatalog as q, type RuntimeErrorDefinition as r, type RuntimeErrorExtras as s, type RuntimeErrorFactory as t, type RuntimeErrorLike as u, type RuntimeErrorOptions as v, type RuntimeLogContextValue as w, type RuntimeSinkContext as x, consoleSink as y, defineRuntimeErrors as z };
+export { defineRuntimeErrors as A, type BreadcrumbInput as B, type CapturedException as C, errorAttributes as D, fileSink as E, type FileSinkOptions as F, isRuntimeErrorLike as G, otlpSink as H, type IgnoreErrorPattern as I, redactAttributes as J, redactText as K, type LoggedErrorSource as L, type MemorySink as M, toClientError as N, type OtlpSinkOptions as O, type RuntimeEvent as R, type RuntimeOutcome as a, type RedactOptions as b, type Redactor$1 as c, type RuntimeLogLevel as d, type RuntimeOperationKind as e, type RuntimeSink as f, type RuntimeLogContext as g, type RuntimeCarrier as h, type CaptureLoggedErrorsOption as i, type Breadcrumb as j, type BreadcrumbLevel as k, type BreadcrumbType as l, memorySink as m, CODE_PATTERN as n, type ClientErrorBody as o, type ConsoleSinkOptions as p, RuntimeError as q, type RuntimeErrorCatalog as r, type RuntimeErrorDefinition as s, type RuntimeErrorExtras as t, type RuntimeErrorFactory as u, type RuntimeErrorLike as v, type RuntimeErrorOptions as w, type RuntimeLogContextValue as x, type RuntimeSinkContext as y, consoleSink as z };