Using Sentry Breadcrumbs to Reconstruct User Journeys Before Errors

The Problem: Missing Context

When an error lands in Sentry you often see the stack trace but not the series of user actions that led to it. Without that timeline you spend extra time reproducing the issue or guessing which feature flag was active.

How Breadcrumbs Work

Breadcrumbs are lightweight log entries that each Sentry SDK attaches to an event. They capture a time‑ordered sequence of navigation changes, network requests, UI clicks, and any custom data you add. The SDK stores them in a ring buffer limited by maxBreadcrumbs (default 100) and sends the buffer with every error event.

Adding Custom Breadcrumbs

You can inject domain‑specific context such as a feature‑flag value, a request‑ID, or a user‑role. In a browser SDK the call looks like this:

// Run in your front‑end code where the action occurs
Sentry.addBreadcrumb({
  category: "feature-flag",
  message: "checkout‑v2 enabled",
  level: "info",
  data: { flag: "checkout-v2", value: true }
});

Place the call right after the condition you want to record. The breadcrumb will appear in the event timeline alongside automatic entries like navigation and xhr.

Controlling Volume and Noise

High breadcrumb volume inflates event payloads and can cause events to be dropped if they exceed your organization’s size limits. Two practical levers:

• maxBreadcrumbs – set a lower ceiling in Sentry.init({ maxBreadcrumbs: 50 }) if you only need recent actions.
• beforeBreadcrumb hook – filter out noisy categories, e.g., drop all console breadcrumbs:

  Sentry.init({
    beforeBreadcrumb: (crumb) => crumb.category !== "console" ? crumb : null
  });

Both settings keep the payload small while preserving high‑value context.

Verifying Your Setup

1. Enable SDK debug mode: Sentry.init({ debug: true }). Open the browser console and trigger an error; you’ll see the full breadcrumb array logged.
2. In the Sentry UI, open the event and check the “Breadcrumbs” tab. Count the entries and compare with your maxBreadcrumbs setting to confirm truncation behavior.
3. Write a unit test that calls Sentry.clearBreadcrumbs() before each case, then assert that only the expected custom breadcrumbs remain.

If the UI shows fewer breadcrumbs than you added, review the beforeBreadcrumb filter or the global limit.

Trade‑off

Reducing maxBreadcrumbs or aggressive filtering shrinks payloads but may discard the exact action that caused the bug. Start with the default 100, monitor event size in the Sentry dashboard, and tighten only when you hit the organization’s payload ceiling.

Actionable Closing

Add a single custom breadcrumb for the most critical user flow in your app today. Deploy with debug: true, fire a test error, and confirm the breadcrumb appears in the event timeline. Then adjust maxBreadcrumbs or the beforeBreadcrumb hook based on the observed payload size. This gives you a reproducible, low‑effort way to reconstruct user journeys for every future error.