Documentation
Auto-capture
Automatic or suggested reports when an error occurs, plus behavior signals such as rage clicks, dead clicks and Web Vitals.
By default, Wutbug only creates a report when a person submits one. Auto-capture adds two optional modes so you don't miss errors nobody reports. In addition, every report includes behavior signals that the SDK detects during the session.
Modes
| Mode | What happens when a problem is detected |
|---|---|
off (default) | Nothing. Reports are only created when a person submits them. |
ask | A discreet prompt appears: "Looks like something went wrong. Want to tell us what happened?". If the person taps Report, the form opens with the detected details prefilled. Otherwise nothing is sent. |
auto | The SDK sends a report on its own, with no interaction, including the replay, console and network from that moment. It doesn't include a screenshot. |
auto mode requires endpoint: it doesn't activate in local mode.
Triggers
| Trigger | What counts |
|---|---|
errors | Uncaught exceptions and unhandled promise rejections. |
failedRequests | Network errors and 5xx responses. 4xx responses never trigger (they are usually expected behavior), and neither do cancelled requests. |
rageClicks | 3 or more clicks within ~1 second in the same spot (30 px radius). |
Configuration
Configure it per project in the dashboard (Project → Auto-capture) or in code. Whatever you set in code wins, field by field, and the ignore rules from both sides are combined.
wutbug.init({
projectKey: 'pk_your_key',
endpoint: 'https://api.wutbug.dev',
autoCapture: {
mode: 'ask',
triggers: { errors: true, failedRequests: true, rageClicks: false },
sampleRate: 0.25,
cooldownMinutes: 10,
ignore: ['ResizeObserver loop', '/api/analytics'],
},
});| Option | Type | Default | Description |
|---|---|---|---|
mode | 'off' | 'ask' | 'auto' | 'off' | See above. |
triggers.errors | boolean | true | Exceptions and rejected promises. |
triggers.failedRequests | boolean | true | Network errors and 5xx. |
triggers.rageClicks | boolean | true | Repeated clicks. |
sampleRate | number (0 to 1) | 1 | In auto mode, the fraction of sessions that send automatic reports. 0.25 = 1 in 4 sessions. |
cooldownMinutes | number | 5 | Minimum minutes between two prompts or automatic reports in a session. Maximum 1,440. |
ignore | string[] | [] | Case-insensitive fragments of the error message, request URL or element that never trigger. Up to 50 rules of 200 characters. |
Limits that always apply
So auto-capture never floods your project or bothers your users:
- One prompt or report per problem and session. The same (normalized) error doesn't trigger twice in a browser session.
- At most 3 automatic reports and 3 prompts per session, regardless of configuration.
- A pause between triggers based on
cooldownMinutes. - Never while the form is open or a report is being sent, so it can't loop on its own work.
- State is stored in
sessionStorage, so reloading the page doesn't reset the limits. - Automatic reports also count toward the project limits.
In the dashboard, reports that the person didn't submit on their own carry an origin label: After prompt (the person accepted the prompt) or Automatic. You can filter the report list by origin.
Behavior signals
Regardless of the mode, every report includes signals detected in the 2-minute window. They help you understand what frustrated the person even when there is no console error.
| Signal | How it's detected |
|---|---|
| Rage clicks | 3 or more clicks within ~1 s inside 30 px. |
| Dead clicks | A click on something clickable (button, link, role="button"…) that doesn't change the page, navigate or fire any request within 1 s. |
| Slow requests | Requests longer than 3 seconds. |
| Long tasks | Count and total duration of tasks that blocked the main thread. |
| Web Vitals | LCP, CLS, INP (approximate: the slowest interaction), FCP and TTFB, using Google's thresholds. |
The clicked element is described briefly (tag, id, up to 2 classes and up to 40 characters of visible text or aria-label). If the element is inside a masked area, its text isn't stored; the text goes through the same redaction filters.
To turn the signals off:
wutbug.init({ projectKey: 'pk_your_key', endpoint: 'https://api.wutbug.dev', capture: { behavior: false } });The detector is lightweight: a passive click listener, a few PerformanceObservers and a MutationObserver that only exists during the second after a click. It never forces layout calculations.