Everything BugCatch does, and how to switch it on.

Quickstart

Three steps, about five minutes. You need an account on admin.bugcatch.app.

1. 01

   Create a project

   One project per application. Creating it returns a DSN - the URL your SDK posts to.

2. 02

   Install the SDK

   $ npm install bugcatch-sdk Copy
3. 03

   Initialise it once, as early as possible

   Before your app renders or your server starts handling requests, so errors during startup are caught too.

import BugCatch from 'bugcatch-sdk';

BugCatch.init({
  dsn: import.meta.env.VITE_BUGCATCH_DSN,
  release: import.meta.env.VITE_APP_VERSION,
  environment: import.meta.env.MODE,
});

That is the whole integration. Uncaught errors and unhandled promise rejections are now captured automatically.

The DSN

A DSN identifies the project and authenticates the SDK. It is shown on the project page in the dashboard and has this shape:

https://api.bugcatch.app/ingest/{projectId}?key={sdkKey}

Keep the DSN in an environment variable rather than committing it, so staging and production report into separate projects.

Send a test event

To confirm the wiring end to end without waiting for a real crash, throw one deliberately:

BugCatch.captureMessage('BugCatch wired up', 'info');

// or a real exception
throw new Error('Test error from setup');

Ingest replies immediately and hands the event to a background worker, so allow about a second before it appears under Issues. If nothing arrives, check the browser network tab for the /ingest request - a 401 means the SDK key is wrong or was rotated, and a 404 means the project ID is.

Fingerprinting

Every incoming event is reduced to a SHA-256 fingerprint of its error type, message, and location. That fingerprint is what makes the difference between an inbox with one message and an inbox with four thousand.

Because the message is part of the fingerprint, errors that interpolate a value - User 4821 not found - split into one issue per value. Keep dynamic values out of the message and pass them as extra context instead:

// Splits into one issue per user
throw new Error(`User ${userId} not found`);

// One issue, with the id kept as context
BugCatch.captureException(new Error('User not found'), { userId });

Issues vs events

You resolve issues, not events. Opening an issue shows its event histogram and lets you drill into any individual event for the exact state at that moment.

Levels & statuses

Levels

Severity of the event. Set it on manual captures; automatic captures are error.

Statuses

Where an issue sits in triage. You set these from the dashboard.

Issue lifecycle

resolved and ignored don't have to mean forever. PATCH /issues/:id takes the status plus an optional condition for leaving it early - useful for the two cases that make "resolved" and "ignored" too blunt on their own: a fix that's still rolling out, and noise you want to hear about again if it gets worse.

Snooze an ignored issue

Set one of these when you ignore an issue. Leave both out and it's ignored the normal way - forever, until you touch it again.

PATCH /projects/:projectId/issues/:id
{ "status": "ignored", "ignoreDurationMinutes": 1440 }  // quiet for 24h

Whichever condition you set is checked on every new event against that issue. Once it's met, the issue un-ignores and goes through the same regression notification as any other reopened issue - to whoever gets notified, a snoozed issue waking back up looks identical to a resolved one coming back.

Resolve in next release

A plain resolve reopens on the very next matching event, regardless of where it came from. That's usually right, but not while you're mid-rollout - the old build is still out there producing the exact crash you just fixed. Add resolveInNextRelease and the issue only reopens once an event actually carries a release newer than the one you resolved it on.

PATCH /projects/:projectId/issues/:id
{ "status": "resolved", "resolveInNextRelease": true }

Merge issues

For when the default grouping splits one real problem into several issues that a grouping rule can't cleanly express. Merging folds one or more issues into another: their events move over, counters combine, and the merged-away issue sticks around as an alias rather than disappearing.

PUT /projects/:projectId/issues/merge
{ "issueIds": ["secondary-1", "secondary-2"], "primaryIssueId": "primary" }

Every future event that would have matched a merged-away fingerprint redirects straight to the primary instead - including reopening it if it's resolved, exactly as any other matching event would. Affected-user counts are combined properly rather than added, so a user who hit both issues is still counted once. Merging is always exactly one hop deep: you can't merge into an issue that's itself already a merge target.

POST /projects/:projectId/issues/:id/unmerge

Reverses it for that one issue: its events move back, both issues' counters and affected-user counts are recomputed from scratch rather than reversed (undoing a union of user sets isn't possible any other way), and it returns to unresolved regardless of what it was before the merge. Unmerging one secondary never touches events from any other issue merged into the same primary.

Inbound filters

Drop noise before it ever becomes an issue, from Project → Settings. A filtered event costs nothing - it's checked before quota is charged and before it reaches the queue, so it never counts against your monthly event limit.

PATCH /projects/:id/inbound-filters
{ "filterLocalhost": true, "messagePatterns": ["ResizeObserver loop.*"] }

This is a merge, not a replace - send only the fields you want to change. A config change takes effect on the very next event; nothing is cached against the old settings.

Custom grouping rules

The default fingerprint - type::message::location - splits "User 123 not found" and "User 456 not found" into two issues, because the message differs. A grouping rule overrides one dimension of the fingerprint so variants like that collapse into one issue the way they should.

PUT /projects/:id/grouping-rules
[
  { "field": "message", "pattern": "User \\d+ not found", "groupKey": "user-not-found" }
]

field is type, message, or filename (the last in-app stack frame). When pattern matches, only that one field's contribution to the fingerprint is replaced with groupKey - the other two dimensions are untouched, so the same message at a different file and line still gets its own issue unless a second rule targets filename too.

Ownership rules

Auto-assign a brand-new issue to whoever owns that part of the codebase - src/billing/** → @marko - instead of it landing unassigned for someone to triage and hand off.

PUT /projects/:id/ownership-rules
[
  { "pattern": "src/billing/**", "userId": "..." }
]

pattern is a gitignore-style glob matched against the filename of the issue's last in-app frame - ** crosses path segments, a single * stays within one. First match wins, same replace-the-whole-list rule as grouping rules above.

Search & saved views

The issue list takes a small query language, not just the status/level dropdowns:

is:unresolved level:error release:1.2.3 user.email:*@acme.com checkout failed

Anything else, including a key:value token that isn't in the list above, is treated as literal search text against the issue title - never silently dropped. The dashboard's own status/level dropdown filters still exist independently and win over is:/level: in the query if both are set, so a saved search can still be narrowed further without editing it.

Sort with ?sort=recent|new|frequency|users (default recent) - mapped to last seen, first seen, event count, and user count.

Saved searches

POST /projects/:projectId/saved-searches stores a { name, query, sort } you can reload later. Saved searches are personal - only you see the ones you create, even though the project itself is shared with your team.

Breadcrumbs

Breadcrumbs are the trail of what happened before the crash. The browser SDK records them automatically while autoCaptureBreadcrumbs is on, keeping the most recent maxBreadcrumbs (default 100) in memory and attaching them to any event it sends.

Add your own for anything domain-specific:

BugCatch.addBreadcrumb({
  timestamp: new Date().toISOString(),
  type: 'user',
  category: 'auth',
  message: 'User logged in',
  data: { method: 'google-oauth' },
});

Releases & source maps

Set release on init and every event records which build it came from. That is what lets you tell a new regression from something that has been broken for months, and it is the key source maps are matched on.

Minified production stacks are unreadable on their own. Upload the source map for a release from Project → Source Maps and frames resolve back to the original file, line, and column.

JavaScript / TypeScript

Ships as ESM and CJS, works with any bundler, has zero runtime dependencies and is about 15 KB minified. The same package covers browser and Node.

Options

Capture

// An Error object, with extra context
try {
  await processOrder(order);
} catch (err) {
  BugCatch.captureException(err, { orderId: order.id });
}

// A plain message: (message, level?, extra?)
BugCatch.captureMessage('Quota limit reached', 'warning', { used: 95 });

User context and tags

Set the user after login so issues show who was affected. Tags are arbitrary key–value pairs you can filter and aggregate by.

BugCatch.setUser({ id: '42', email: 'jane@example.com', username: 'jane' });
BugCatch.setTag('plan', 'pro');
BugCatch.setTag('region', 'eu-west-1');

BugCatch.clearUser();  // on logout

React error boundary

React swallows render errors into error boundaries, so they never reach the global handler. Report them explicitly:

class ErrorBoundary extends React.Component {
  componentDidCatch(error: Error) {
    BugCatch.captureException(error);
  }
  render() {
    return this.props.children;
  }
}

Vue

BugCatch.init({ dsn: import.meta.env.VITE_BUGCATCH_DSN });

app.config.errorHandler = (err) => {
  BugCatch.captureException(err);
};

Hot reload and SPAs

init() is a singleton; calling it twice logs a warning and does nothing. During HMR, tear down first so listeners are not attached repeatedly:

BugCatch.destroy();  // removes listeners, resets the singleton

Node.js

Same package. Turn off breadcrumb auto-capture, since there is no DOM to observe.

import BugCatch from 'bugcatch-sdk';

BugCatch.init({
  dsn: process.env.BUGCATCH_DSN,
  release: process.env.npm_package_version,
  environment: process.env.NODE_ENV,
  autoCaptureBreadcrumbs: false,
});

// Express error middleware - register it last
app.use((err, req, res, next) => {
  BugCatch.captureException(err, { path: req.path, method: req.method });
  next(err);
});

CommonJS uses a named import:

const { BugCatch } = require('bugcatch-sdk');
BugCatch.init({ dsn: process.env.BUGCATCH_DSN });

React Native

Works with Expo Go, the Expo managed workflow, and the React Native CLI. No native modules, so no rebuild and no config plugin.

import BugCatch from 'bugcatch-react-native-sdk';

BugCatch.init({
  dsn: 'https://api.bugcatch.app/ingest/PROJECT_ID?key=SDK_KEY',
  release: '1.0.0',
  environment: 'production',
});

The capture API is identical to the web SDK. Two options are specific to mobile:

Auto-captured breadcrumbs here are console.warn/console.error calls and app state changes, rather than DOM clicks.

Java

Java 21 or newer, thread-safe, zero runtime dependencies, with full support for exception cause chains.

<dependency>
  <groupId>dev.lzrvc</groupId>
  <artifactId>bugcatch-java-sdk</artifactId>
  <version>0.1.0</version>
</dependency>

Gradle: implementation 'dev.lzrvc:bugcatch-java-sdk:0.1.0'

import dev.lzrvc.bugcatch.BugCatch;
import dev.lzrvc.bugcatch.BugCatchOptions;

BugCatch.init(new BugCatchOptions.Builder(System.getenv("BUGCATCH_DSN"))
    .release("1.0.0")
    .environment("production")
    .build());

After init() the SDK installs a Thread.setDefaultUncaughtExceptionHandler and captures uncaught exceptions automatically.

// Manual capture with context
BugCatch.captureException(e, Map.of("orderId", orderId));
BugCatch.captureMessage("Disk usage above 90%", "warning");

// User context and tags
BugCatch.setUser(new UserContext.Builder().id("u123").email("a@b.com").build());
BugCatch.setTag("service", "order-service");

Options mirror the JavaScript SDK - debug, maxBreadcrumbs, autoCaptureErrors, beforeSend - plus ignoreError(String) for literal matches and ignoreErrorPattern(String) for regular expressions.

Server metrics

BugCatchServerReporter periodically reports process memory, CPU, and event loop lag. It is framework-agnostic - start it on boot and stop it on shutdown.

import { BugCatchServerReporter } from 'bugcatch-sdk';

const reporter = new BugCatchServerReporter({
  dsn: process.env.BUGCATCH_DSN,
});

reporter.start();
// reporter.stop() on shutdown

In NestJS, wire it to the module lifecycle:

@Injectable()
export class BugCatchMetricsService implements OnModuleInit, OnModuleDestroy {
  private readonly reporter = new BugCatchServerReporter({
    dsn: process.env.BUGCATCH_DSN,
  });
  onModuleInit()    { this.reporter.start(); }
  onModuleDestroy() { this.reporter.stop();  }
}

Distributed tracing

One level below server metrics: instead of "the server was under load," tracing tells you which request, and which part of it - a slow query, a slow outbound call - was responsible. Pro and above.

A transaction is the root of one traced operation - an HTTP request, a background job. It carries zero or more spans, each a timed unit of work inside it: a DB query, an outbound call. Spans nest via SDK-generated spanId/parentSpanId, which is what lets the dashboard rebuild the waterfall view from a flat list without an extra query.

Percentiles are computed from the most recent 5,000 rows in the requested window, not a database-level aggregate - representative for a dashboard, though on a route busy enough to exceed that cap within the window, treat the tail percentiles as approximate.

Custom dashboards

A named, project-scoped grid of widgets built from the analytics you already have. Pro and above.

Every widget's source is one of your existing analytics endpoints - overview, trend, events-over-time, new-issues-over-time, issues-by-level, issues-by-status, top-issues, or server-metrics. There's no separate query engine: a dashboard just arranges charts that already exist into one view instead of tabbing between Analytics and Server.

PUT /projects/:projectId/dashboards/:id/widgets
{ "widgets": [
  { "source": "trend", "x": 0, "y": 0, "w": 2, "h": 1 },
  { "source": "top-issues", "x": 0, "y": 1, "w": 1, "h": 1 }
] }

x/y/w/h are integer grid cells, not pixels - the layout snaps to a grid rather than allowing free placement. Rearranging the grid replaces the entire widget list in one call, same as grouping and ownership rules: position is part of the saved state.

Uptime & domain monitors

Add an HTTP monitor per URL under Project → Monitors. No SDK involved - checks run from BugCatch.

The retries matter: a single dropped packet does not page anyone. A URL is only reported down after it fails the initial check and all three retries. Response times are recorded for every check, so you can see a service degrading before it fails.

SSL certificate & domain expiry

Turn on checkSsl on an https monitor and each 5-minute check also reads the certificate's expiry date - no separate schedule, no extra check to configure. You're warned once it has 30 days or less left, one email per 24 hours rather than a separate one at the 30, 14, and 7-day marks - the email states the exact day count so you're not left guessing how urgent it is.

The warning clears itself once the certificate is renewed - if the days remaining go back above 30, the next expiry is treated as a fresh event, not silenced by the old alert. A non-https URL, or a check that can't complete a TLS handshake at all, is skipped rather than reported as an error: a broken certificate check is not the same claim as a down monitor, and reachability is already covered by the regular check.

checkDomain is the same idea for the domain registration itself, and it's a separate opt-in from checkSsl on purpose - a certificate can auto-renew via Let's Encrypt while nobody notices the domain registration lapsing underneath it. Same 30-day warning window, same 24-hour cooldown that clears on renewal, separate from the SSL check's own cooldown so an expiring certificate and an expiring domain never share a timer.

Cron monitors

A heartbeat monitor, for jobs BugCatch can't reach on its own - a nightly export, a queue worker, anything on a schedule rather than behind a URL. Where an uptime monitor polls you, a cron monitor waits for your job to check in - the same "dead man's switch" pattern Healthchecks.io popularized.

POST /cron/:cronMonitorId/ping

Call this when the job finishes. GET works too, so a plain curl or wget one-liner in the crontab itself is enough - no SDK, no auth header. The URL's unguessable id is what stands in for a secret, the same pattern the ping endpoint for uptime monitors doesn't need because it's BugCatch calling out, not in.

A job that pings every hour with a 5-minute grace period is reported down if 66 minutes pass with no ping. GET /cron-monitors/:id/pings returns the ping history - every start, success, and failure, with duration where reported - for spotting a job that's technically still checking in but taking steadily longer each run.

Status pages & incidents

A public page at bugcatch.app/status/:slug - no login, no plan gate on the viewer's side - showing the uptime and cron monitors you choose to put on it, plus any incident you post. One page per project.

POST /status-page/monitors links either kind of monitor onto the page by id and type, with an optional label that overrides the monitor's internal name - so prod-health-check-v3 can read "API" in public. Mixing uptime checks and heartbeats on one page is the normal case, not an edge case.

Incidents

An incident is a title, an impact level, and a timeline of updates. Open one, then post updates as the situation develops:

// Open it
POST /projects/:projectId/incidents
{ "title": "Elevated API latency", "impact": "major" }

// Narrate it
POST /projects/:projectId/incidents/:id/updates
{ "status": "identified", "message": "Root cause found, deploying a fix." }

// Close it - same endpoint, resolved status
POST /projects/:projectId/incidents/:id/updates
{ "status": "resolved", "message": "Fix deployed, latency back to normal." }

There's no separate "close" call - posting an update with status: resolved is what closes it, and that update becomes the last line of the public timeline.

Alerting & cooldowns

Every notification sits behind a cooldown keyed to the thing that triggered it, so a crash loop firing ten thousand times still costs you one message. Each class has its own timer - a memory warning never suppresses a downed monitor.

The legacy webhook is the simplest option and stays free forever: set a URL on Project → Settings and BugCatch posts to it on new issues, regressions, and spikes. Point it at a Slack incoming webhook URL and the payload is auto-detected and formatted for Slack. For anything more specific - custom alert rules replace it with rules you define, on Starter and above.

Alert rules & notification channels

Starter and above replace "we email you when we decide" with rules you own. A rule says when to alert; a channel says where. They are separate so one Slack channel can serve every rule in the project, and changing where an alert goes never touches what triggers it.

Triggers

event_frequency and unique_users are questions about a time range rather than something noticed at the moment it happens, so they're evaluated on a one-minute cron rather than inline - expect up to a minute of lag versus the other triggers, which fire immediately.

Filters

Narrow a trigger by levels, environments, releases, tags, and titleContains. Every filter you set must match; one you leave empty is not a constraint. Level, environment, and release are read from the event, not the issue, so a rule scoped to production does not fire when the same issue shows up in staging.

{
  "name": "Prod fatals to on-call",
  "triggerType": "new_issue",
  "filters": { "levels": ["fatal"], "environments": ["production"] },
  "channelIds": ["..."],
  "cooldownMinutes": 30
}

Leave channelIds empty and the rule notifies every enabled channel in the project. Test a rule against sample data without waiting for a real trigger or burning its cooldown from Project → Alert Rules → Test.

Channels

Every channel renders from the same alert payload, so adding a Discord channel never touches the logic that decides when to fire. Secrets stored in a channel's config - webhook signing key, bot token, PagerDuty routing key - are masked on every read; the API never hands one back once it's set. Send a sample notification to any channel to confirm it's wired correctly, independent of any rule.

Structured logs

A log line is not an issue. There's no fingerprint and no grouping - logs are a stream you search and tail, batched in from your console, Pino, or Winston transport.

POST /ingest/:projectId/logs

Same fire-and-forget shape as event ingest: authenticate with the SDK key, send up to 100 lines in a batch, get an immediate response. The write happens on a worker, off the request path.

Searching and tailing

Retention piggybacks on your plan's event retention rather than a separate setting - logs age out on the same cutoff as events. The live tail can't authenticate with the browser's native EventSource API (it can't send an Authorization header), so if you're building your own client against /logs/stream, open it with fetch() and parse the SSE frames from the response body yourself.

Releases & deploy tracking

A release is a version string - 1.4.0, a git SHA - with optional commit, repo, and author metadata. It's free on every plan, Free included: it's metadata, not a volume the platform pays to store.

POST /projects/:projectId/releases/:version/deploys

Call this from CI on every deploy. If the release doesn't exist yet, this call creates it - registering a release by hand first is optional, because deploying is the common case and a separate registration step would just get skipped. A release can deploy to more than one environment; each deploy call adds a row rather than overwriting the last one.

What it gives an issue

All three come from the release you already set on init(), read off the event - not from anything you configure separately.

GET /analytics/deploy-markers returns every deploy timestamp in range across all releases, meant to render as vertical lines on your trend charts - a spike that starts right after a deploy line is not a coincidence you have to notice yourself.

Plans & limits

Every plan gets the full issue pipeline. What changes is the ceilings and the monitoring built on top. Yearly billing is ten months for twelve.

Features by plan

Releases and deploy tracking are not on this table - registering a release and seeing which one an issue first appeared in is free on every plan, Free included. It is metadata, not a volume the platform pays to store.

Paid plans begin with a 14-day Pro trial and no card. Billing runs through Paddle as merchant of record, so VAT and sales tax are calculated and remitted at checkout. Card changes, invoices, and cancellation all live in the Paddle portal, reachable from your billing settings.

Quotas & enforcement

Two different ceilings apply to ingest, and they fail differently on purpose.

You are emailed once when the project passes 80% of the monthly quota, and again if it is exceeded - one message per severity per billing period, so a runaway release cannot flood your inbox. Usage for the current period, and monthly history, are both on the billing page.

Ingest format

If no SDK covers your language, post directly. The endpoint authenticates with the SDK key in the query string and always answers immediately - processing happens on a worker queue, so a slow pipeline never becomes your latency.

POST /ingest/:projectId?key={sdkKey}

{
  "event_id": "aaaabbbb-0000-0000-0000-000000000001",
  "timestamp": "2026-01-01T12:00:00Z",
  "level": "error",
  "message": "TypeError: Cannot read property x of undefined",
  "exception": {
    "values": [{
      "type": "TypeError",
      "value": "Cannot read property x of undefined",
      "stacktrace": {
        "frames": [{
          "filename": "app.js",
          "lineno": 42,
          "in_app": true
        }]
      }
    }]
  }
}

A 200 means the event was accepted onto the queue, not that it has been processed. Expect roughly a second before it is visible.

REST API

Everything the dashboard does is available over HTTP. All endpoints below need a JWT in an Authorization: Bearer header - access tokens last 15 minutes, refresh tokens 7 days. Interactive docs live at /api.

Auth

Projects

Issues

List filters: status, level, search, since, page, limit.

Events

Source maps

Account

Scrubbing data

beforeSend runs on the client before anything leaves the process. It is the right place to remove data that should never reach a third party, because a field you strip here is never transmitted at all.

BugCatch.init({
  dsn: '...',
  beforeSend(event) {
    // Drop a noisy class of error entirely
    if (event.exception?.values?.[0]?.type === 'NetworkError') return false;

    // Remove PII before it is sent
    if (event.user) delete event.user.email;

    return event;
  },
});

Returning false discards the event. Returning the object sends the modified version. For patterns you know up front, ignoreErrors and ignoreUrls are cheaper - they never build the event in the first place.