@autter/runtime-node 1.5.0 → 1.6.0

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,7 +180,7 @@ 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`) |
@@ -167,6 +205,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

package/dist/{chunk-GI47WGRR.cjs → chunk-ARN26OK6.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.0",
   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"
   },

package/dist/{chunk-3TJHUCZ6.js → chunk-FBKYOHU2.js}

@@ -1,7 +1,7 @@
 import {
   noteCompatFeature,
   observeIngesterResponse
-} from "./chunk-L7HWKMCZ.js";
+} from "./chunk-OY2HTUWY.js";
 
 // ../runtime-core/dist/index.js
 var SENSITIVE_KEY_PATTERNS = [
@@ -327,8 +327,8 @@ function priority(key) {
   if (/^(?:exception|autter\.error)\./.test(key)) return 1;
   return 0;
 }
-function boundContext(attributes = {}, redact2) {
-  const redacted = redact2 ? redact2(attributes) : redactAttributes(attributes);
+function boundContext(attributes = {}, redact3) {
+  const redacted = redact3 ? redact3(attributes) : redactAttributes(attributes);
   let budget = 512;
   let characters = 16384;
   let truncated = false;
@@ -365,14 +365,14 @@ function boundContext(attributes = {}, redact2) {
   if (truncated) result["autter.context.truncated"] = true;
   return result;
 }
-function userContext(attributes = {}, redact2) {
+function userContext(attributes = {}, redact3) {
   return Object.fromEntries(
-    Object.entries(boundContext(attributes, redact2)).filter(
+    Object.entries(boundContext(attributes, redact3)).filter(
       ([key]) => !RESERVED_KEY.test(key)
     )
   );
 }
-function mergeContext(current, next = {}, redact2) {
+function mergeContext(current, next = {}, redact3) {
   const merge2 = (left, right, depth) => {
     const result = { ...left };
     for (const [key, value] of Object.entries(right)) {
@@ -381,7 +381,7 @@ function mergeContext(current, next = {}, redact2) {
     }
     return result;
   };
-  return userContext(merge2(current, userContext(next, redact2), 0), redact2);
+  return userContext(merge2(current, userContext(next, redact3), 0), redact3);
 }
 function toSpanAttributes(context) {
   return Object.fromEntries(
@@ -473,6 +473,17 @@ function defineRuntimeErrors(namespace, catalog) {
   }
   return out;
 }
+function isError(value) {
+  if (!value || typeof value !== "object") return false;
+  try {
+    if (value instanceof Error) return true;
+    const native = Error.isError;
+    if (typeof native === "function") return native(value) === true;
+    return Object.prototype.toString.call(value) === "[object Error]";
+  } catch {
+    return false;
+  }
+}
 function isRuntimeErrorLike(err) {
   if (err instanceof RuntimeError) return true;
   if (!err || typeof err !== "object") return false;
@@ -523,15 +534,15 @@ function errorAttributes(err, options = {}) {
     for (let n = 1; n <= CAUSE_DEPTH && cause !== void 0 && cause !== null; n++) {
       if (seen.has(cause)) break;
       seen.add(cause);
-      const isError = typeof cause === "object";
-      const type = isError ? String(field(cause, "name") ?? cause.constructor?.name ?? "Error") : typeof cause;
-      const message = isError ? field(cause, "message") : cause;
+      const isError2 = typeof cause === "object";
+      const type = isError2 ? String(field(cause, "name") ?? cause.constructor?.name ?? "Error") : typeof cause;
+      const message = isError2 ? field(cause, "message") : cause;
       out[`exception.cause.${n}.type`] = type.slice(0, 200);
       out[`exception.cause.${n}.message`] = String(message ?? "").slice(0, 1e3);
       const causeCode = field(cause, "code");
       if (typeof causeCode === "string" && causeCode)
         out[`exception.cause.${n}.code`] = causeCode.slice(0, CODE_MAX_LENGTH);
-      cause = isError ? field(cause, "cause") : void 0;
+      cause = isError2 ? field(cause, "cause") : void 0;
     }
   }
   return out;
@@ -577,19 +588,19 @@ function createInlineLogState(startedAt) {
     level: "info"
   };
 }
-function appendInlineLog(state, level, message, attrs, redact2, now = Date.now()) {
+function appendInlineLog(state, level, message, attrs, redact3, now = Date.now()) {
   state.level = maxLevel(state.level, level);
   if (state.logs.length >= INLINE_LOG_LIMIT) {
     state.logsTruncated = true;
     return;
   }
-  const text = String(boundContext({ message }, redact2).message ?? "").slice(
+  const text = String(boundContext({ message }, redact3).message ?? "").slice(
     0,
     INLINE_MESSAGE_MAX
   );
   let small;
   if (attrs && Object.keys(attrs).length) {
-    small = boundContext(attrs, redact2);
+    small = boundContext(attrs, redact3);
     const encoded = JSON.stringify(small);
     if (encoded.length > 1e3) small = { "autter.context.truncated": true };
   }
@@ -806,6 +817,172 @@ function parseUserAgent(ua) {
   const device = !value ? "unknown" : bot ? "bot" : /iPad|Tablet/.test(value) || /Android/.test(value) && !/Mobile/.test(value) ? "tablet" : /Mobi|iPhone|iPod|Android/.test(value) ? "mobile" : "desktop";
   return { browser, os, device, bot };
 }
+var BREADCRUMBS_ATTRIBUTE = "autter.breadcrumbs";
+var MAX_BREADCRUMBS = 30;
+var MAX_MESSAGE = 500;
+var MAX_DATA_KEYS = 10;
+var MAX_DATA_STRING = 200;
+var BREADCRUMBS_ATTRIBUTE_MAX_CHARS = 16 * 1024;
+var MASK = "[redacted]";
+var TYPES = /* @__PURE__ */ new Set(["console", "request", "navigation", "click", "log", "custom"]);
+var LEVELS = {
+  debug: "debug",
+  trace: "debug",
+  info: "info",
+  log: "info",
+  warning: "warning",
+  warn: "warning",
+  error: "error",
+  fatal: "error"
+};
+var UNSAFE_KEY = /^(?:__proto__|constructor|prototype)$/;
+function scrubber(redact3) {
+  return (value, max) => {
+    const scrubbed = redact3({ message: value.slice(0, max + 512) }).message;
+    return stripUrlQueries(typeof scrubbed === "string" ? scrubbed : "").slice(0, max);
+  };
+}
+function cleanData(raw, redact3) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return void 0;
+  const picked = {};
+  let count = 0;
+  for (const key of Object.keys(raw).slice(0, 64)) {
+    if (count >= MAX_DATA_KEYS) break;
+    if (!key || UNSAFE_KEY.test(key)) continue;
+    const value = raw[key];
+    const name = key.slice(0, 100);
+    if (typeof value === "string") {
+      const text = /(?:url|path|route|target)$/i.test(name) ? value.split(/[?#]/)[0] : value;
+      picked[name] = text.slice(0, MAX_DATA_STRING + 512);
+    } else if (typeof value === "number") {
+      if (!Number.isFinite(value)) continue;
+      picked[name] = value;
+    } else if (typeof value === "boolean" || value === null) {
+      picked[name] = value;
+    } else {
+      continue;
+    }
+    count++;
+  }
+  if (count === 0) return void 0;
+  const redacted = redact3(picked);
+  const out = {};
+  for (const key of Object.keys(picked)) {
+    const value = key in redacted ? redacted[key] : picked[key];
+    out[key] = typeof value === "string" ? stripUrlQueries(value).slice(0, MAX_DATA_STRING) : value;
+  }
+  return out;
+}
+function timestamp(value) {
+  if (value === void 0) return (/* @__PURE__ */ new Date()).toISOString();
+  if (typeof value !== "string" && typeof value !== "number" && !(value instanceof Date)) return null;
+  const at = new Date(value);
+  return Number.isNaN(at.getTime()) ? null : at.toISOString();
+}
+function normalizeBreadcrumb(input, redact3, options = {}) {
+  try {
+    if (!input || typeof input !== "object" || Array.isArray(input)) return null;
+    const raw = input;
+    if (options.requireAt && raw.at === void 0) return null;
+    const at = timestamp(raw.at);
+    if (!at) return null;
+    const rawMessage = raw.message;
+    const message = typeof rawMessage === "string" ? rawMessage : typeof rawMessage === "number" || typeof rawMessage === "boolean" ? String(rawMessage) : "";
+    const data = cleanData(raw.data, redact3);
+    if (!message && !data) return null;
+    const type = typeof raw.type === "string" && TYPES.has(raw.type) ? raw.type : "custom";
+    const level = typeof raw.level === "string" ? LEVELS[raw.level.toLowerCase()] : void 0;
+    return {
+      type,
+      at,
+      ...level ? { level } : {},
+      message: scrubber(redact3)(message, MAX_MESSAGE),
+      ...data ? { data } : {}
+    };
+  } catch {
+    return null;
+  }
+}
+function sanitizeBreadcrumbs(raw, redact3) {
+  const out = [];
+  try {
+    if (!Array.isArray(raw)) return void 0;
+    const first = Math.max(0, raw.length - 200);
+    for (let i = raw.length - 1; i >= first && out.length < MAX_BREADCRUMBS; i--) {
+      const crumb = normalizeBreadcrumb(raw[i], redact3, { requireAt: true });
+      if (crumb) out.push(crumb);
+    }
+  } catch {
+  }
+  return out.length ? out.reverse() : void 0;
+}
+var BreadcrumbTrail = class {
+  constructor(max = MAX_BREADCRUMBS) {
+    this.max = max;
+  }
+  max;
+  items = [];
+  add(crumb) {
+    this.items.push(crumb);
+    if (this.items.length > this.max) this.items.splice(0, this.items.length - this.max);
+  }
+  /** Copies, oldest first. */
+  list() {
+    return this.items.map((crumb) => ({ ...crumb, ...crumb.data ? { data: { ...crumb.data } } : {} }));
+  }
+  get size() {
+    return this.items.length;
+  }
+  clear() {
+    this.items = [];
+  }
+};
+function breadcrumbsAttribute(list, scrub, maxChars = BREADCRUMBS_ATTRIBUTE_MAX_CHARS) {
+  const parts = [];
+  let chars = 2;
+  for (let i = list.length - 1; i >= 0 && parts.length < MAX_BREADCRUMBS; i--) {
+    const crumb = list[i];
+    let json = JSON.stringify(crumb);
+    if (scrub(json) !== json) {
+      json = JSON.stringify({ type: crumb.type, at: crumb.at, ...crumb.level ? { level: crumb.level } : {}, message: MASK });
+    }
+    if (chars + json.length + 1 > maxChars) break;
+    chars += json.length + 1;
+    parts.push(json);
+  }
+  if (parts.length === 0) return void 0;
+  const out = `[${parts.reverse().join(",")}]`;
+  return scrub(out) === out ? out : void 0;
+}
+var FINGERPRINT_ATTRIBUTE = "autter.fingerprint";
+var FINGERPRINT_MAX_VALUES = 10;
+var FINGERPRINT_MAX_LENGTH = 200;
+function fingerprintValues(value, scrub = (text) => text) {
+  const list = Array.isArray(value) ? value : [value];
+  const values = list.filter((item) => typeof item === "string" && item !== "").slice(0, FINGERPRINT_MAX_VALUES).map((item) => scrub(item.slice(0, FINGERPRINT_MAX_LENGTH + 512)).slice(0, FINGERPRINT_MAX_LENGTH)).filter((item) => item !== "");
+  return values.length > 0 ? values : void 0;
+}
+function fingerprintEventAttributes(value, scrub) {
+  const values = fingerprintValues(value, scrub);
+  return values ? { [FINGERPRINT_ATTRIBUTE]: JSON.stringify(values) } : {};
+}
+function splitFingerprint(attributes) {
+  if (!attributes || typeof attributes !== "object" || !("fingerprint" in attributes)) {
+    return { attributes: attributes ?? void 0, fingerprint: void 0 };
+  }
+  const { fingerprint, ...rest } = attributes;
+  return { attributes: rest, fingerprint };
+}
+
+// src/breadcrumbs.ts
+import { trace as trace2 } from "@opentelemetry/api";
+
+// src/logger.ts
+import { AsyncLocalStorage } from "async_hooks";
+import { randomUUID } from "crypto";
+import {
+  trace
+} from "@opentelemetry/api";
 
 // src/sinks.ts
 import {
@@ -1185,11 +1362,6 @@ function memorySink() {
 }
 
 // src/logger.ts
-import { AsyncLocalStorage } from "async_hooks";
-import { randomUUID } from "crypto";
-import {
-  trace
-} from "@opentelemetry/api";
 var local = new AsyncLocalStorage();
 var config = null;
 var sinks = [];
@@ -1237,6 +1409,7 @@ function emit(level, message, attributes, extra = {}, options = {}) {
   const state = options.state !== void 0 ? options.state ?? void 0 : local.getStore();
   if (state?.sealed) return;
   const summary = extra["autter.event.type"] === "operation";
+  if (!summary) recordLogBreadcrumb(level, message, attributes, state);
   if (!summary && LEVEL_SEVERITY[level] < LEVEL_SEVERITY[config?.options?.minLevel ?? "debug"])
     return;
   if (!summary && state && config?.options?.inline !== false) {
@@ -1303,6 +1476,9 @@ function configureRuntimeLogger(next) {
     }
   }
 }
+function loggerConfigured() {
+  return config;
+}
 function addRuntimeSink(sink) {
   extraSinks.add(sink);
   return () => extraSinks.delete(sink);
@@ -1313,8 +1489,8 @@ function notifyException(error, attributes = {}) {
   const record = {
     time: Date.now(),
     error,
-    message: error instanceof Error ? error.message : String(error),
-    type: error instanceof Error ? error.name : "Error",
+    message: isError(error) ? error.message : String(error),
+    type: isError(error) ? error.name : "Error",
     attributes: { ...attributes, ...errorAttributes(error) },
     ...state ? { operationId: state.id } : {},
     ...state?.requestId ? { requestId: state.requestId } : {}
@@ -1367,11 +1543,11 @@ function createRuntimeLogger(attributes = {}) {
     warn: (message, extra) => emit("warning", message, merge(attrs, extra)),
     error: (error, extra) => emit(
       "error",
-      error instanceof Error ? error.message : String(error),
+      isError(error) ? error.message : String(error),
       {
         ...attrs,
         ...extra,
-        ...error instanceof Error ? {
+        ...isError(error) ? {
           "exception.type": error.name,
           "exception.stacktrace": error.stack ?? ""
         } : {}
@@ -1382,16 +1558,16 @@ function createRuntimeLogger(attributes = {}) {
 }
 var runtimeLogger = createRuntimeLogger();
 function captureExceptionAsLog(error, attributes = {}) {
-  const isError = error instanceof Error;
-  const message = isError ? error.message : String(error);
-  const stack = isError && error.stack ? error.stack : new Error().stack?.split("\n").filter((line, i) => i === 0 || !/captureException/.test(line)).join("\n") ?? "";
+  const isErr = isError(error);
+  const message = isErr ? error.message : String(error);
+  const stack = isErr && error.stack ? error.stack : new Error().stack?.split("\n").filter((line, i) => i === 0 || !/captureException/.test(line)).join("\n") ?? "";
   noteOperationError(error);
   emit(
     "error",
     message,
     {
       ...attributes,
-      "exception.type": isError ? error.name : "Error",
+      "exception.type": isErr ? error.name : "Error",
       "exception.message": message,
       "exception.stacktrace": stack
     },
@@ -1486,7 +1662,7 @@ function emitSummary(state, options = {}) {
     state.message ?? `${state.name}: ${state.outcome}`,
     {
       ...operationAttributes(state),
-      ...err instanceof Error ? {
+      ...isError(err) ? {
         "exception.type": err.name,
         "exception.stacktrace": err.stack ?? ""
       } : {}
@@ -1521,6 +1697,7 @@ function startOperation(name, fn, attributes, options, internal = {}) {
       ...parent?.requestId ? { requestId: parent.requestId } : {}
     }
   );
+  if (linked && parent) state.breadcrumbs = parent.breadcrumbs ??= new BreadcrumbTrail();
   const operation = operationHandle(state);
   const run = () => local.run(state, async () => {
     let thrown;
@@ -1530,6 +1707,7 @@ function startOperation(name, fn, attributes, options, internal = {}) {
       state.outcome = "failed";
       thrown = error;
       noteOperationError(error, true, state);
+      rememberThrownBreadcrumbs(error, state);
       config?.captureThrown?.(error);
       throw error;
     } finally {
@@ -1634,6 +1812,83 @@ var runtimeContext = {
   }
 };
 
+// src/breadcrumbs.ts
+var INVALID_TRACE_ID = "00000000000000000000000000000000";
+var MAX_TRACE_TRAILS = 200;
+var byTrace = /* @__PURE__ */ new Map();
+var processTrail = new BreadcrumbTrail();
+var thrownTrails = /* @__PURE__ */ new WeakMap();
+function redact2(attributes) {
+  return loggerConfigured()?.redact(attributes) ?? redactAttributes(attributes);
+}
+function trailFor(create, state = local.getStore()) {
+  if (state) {
+    if (!state.breadcrumbs && create) state.breadcrumbs = new BreadcrumbTrail();
+    return state.breadcrumbs;
+  }
+  const traceId = trace2.getActiveSpan()?.spanContext().traceId;
+  if (traceId && traceId !== INVALID_TRACE_ID) {
+    let trail = byTrace.get(traceId);
+    if (!trail && create) {
+      trail = new BreadcrumbTrail();
+      byTrace.set(traceId, trail);
+      if (byTrace.size > MAX_TRACE_TRAILS) {
+        const oldest = byTrace.keys().next().value;
+        if (oldest !== void 0) byTrace.delete(oldest);
+      }
+    }
+    return trail;
+  }
+  return processTrail;
+}
+function addBreadcrumb(input) {
+  try {
+    const crumb = normalizeBreadcrumb(input, redact2);
+    if (!crumb) return;
+    trailFor(true)?.add(crumb);
+    noteCompatFeature("breadcrumbs");
+  } catch {
+  }
+}
+function recordLogBreadcrumb(level, message, attributes, state) {
+  try {
+    const data = {};
+    let count = 0;
+    for (const [key, value] of Object.entries(attributes)) {
+      if (count >= 10) break;
+      if (/^(?:exception|autter)\./.test(key)) continue;
+      if (value === null || ["string", "number", "boolean"].includes(typeof value)) {
+        data[key] = value;
+        count++;
+      }
+    }
+    const crumb = normalizeBreadcrumb({ type: "log", level, message, data }, redact2);
+    if (crumb) trailFor(true, state)?.add(crumb);
+  } catch {
+  }
+}
+function attributeBudget() {
+  const limit = Number(
+    process.env.OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT ?? process.env.OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT
+  );
+  return Number.isFinite(limit) && limit > 0 ? Math.min(BREADCRUMBS_ATTRIBUTE_MAX_CHARS, limit) : BREADCRUMBS_ATTRIBUTE_MAX_CHARS;
+}
+function rememberThrownBreadcrumbs(error, state) {
+  if (state.breadcrumbs && error !== null && (typeof error === "object" || typeof error === "function"))
+    thrownTrails.set(error, state.breadcrumbs);
+}
+function breadcrumbEventAttributes(scrub, error) {
+  try {
+    const thrown = error !== null && typeof error === "object" ? thrownTrails.get(error) : void 0;
+    const trail = thrown ?? trailFor(false);
+    if (!trail?.size) return {};
+    const json = breadcrumbsAttribute(trail.list(), scrub, attributeBudget());
+    return json ? { [BREADCRUMBS_ATTRIBUTE]: json } : {};
+  } catch {
+    return {};
+  }
+}
+
 export {
   redactAttributes,
   redactText,
@@ -1641,6 +1896,7 @@ export {
   CODE_PATTERN,
   RuntimeError,
   defineRuntimeErrors,
+  isError,
   isRuntimeErrorLike,
   errorCodeOf,
   errorAttributes,
@@ -1654,6 +1910,12 @@ export {
   compileIgnore,
   requestOutcome,
   parseUserAgent,
+  sanitizeBreadcrumbs,
+  fingerprintValues,
+  fingerprintEventAttributes,
+  splitFingerprint,
+  addBreadcrumb,
+  breadcrumbEventAttributes,
   otlpSink,
   consoleSink,
   fileSink,