Bugsnag Cheat Sheet

Overview

Bugsnag is an error monitoring and application stability management platform that automatically detects and reports errors in web, mobile, and backend applications. It provides intelligent error grouping, release-based tracking, and stability scores to help teams prioritize fixes based on business impact rather than raw error counts.

Bugsnag supports over 50 platforms and frameworks, offering SDKs for JavaScript, Python, Ruby, Java, Go, PHP, .NET, iOS, Android, React Native, and more. Key features include breadcrumbs for debugging context, user tracking, release health monitoring, and integrations with Jira, Slack, PagerDuty, and CI/CD tools.

Installation

# JavaScript (Browser)
npm install @bugsnag/js

# Node.js
npm install @bugsnag/node

# React
npm install @bugsnag/js @bugsnag/plugin-react

# Python
pip install bugsnag

# Ruby
gem install bugsnag

# Go
go get github.com/bugsnag/bugsnag-go/v2

# PHP
composer require bugsnag/bugsnag

# Bugsnag CLI
npm install -g @bugsnag/cli

Core Configuration

Node.js

const Bugsnag = require("@bugsnag/node");

Bugsnag.start({
  apiKey: "YOUR_API_KEY",
  appVersion: "1.2.0",
  releaseStage: process.env.NODE_ENV || "development",
  enabledReleaseStages: ["production", "staging"],
  onError: function (event) {
    event.addMetadata("account", {
      plan: "premium",
      region: "us-east-1",
    });
  },
});

React

import Bugsnag from "@bugsnag/js";
import BugsnagPluginReact from "@bugsnag/plugin-react";
import React from "react";

Bugsnag.start({
  apiKey: "YOUR_API_KEY",
  plugins: [new BugsnagPluginReact()],
  appVersion: "1.2.0",
});

const ErrorBoundary = Bugsnag.getPlugin("react").createErrorBoundary(React);

function App() {
  return (
    <ErrorBoundary>
      <MyApp />
    </ErrorBoundary>
  );
}

Python / Django

import bugsnag
from bugsnag.django import BugsnagMiddleware

bugsnag.configure(
    api_key="YOUR_API_KEY",
    project_root="/app",
    app_version="1.2.0",
    release_stage="production",
    notify_release_stages=["production", "staging"],
)

# Django settings.py
MIDDLEWARE = [
    "bugsnag.django.middleware.BugsnagMiddleware",
    # ... other middleware
]

Ruby / Rails

# config/initializers/bugsnag.rb
Bugsnag.configure do |config|
  config.api_key = "YOUR_API_KEY"
  config.app_version = "1.2.0"
  config.release_stage = Rails.env
  config.notify_release_stages = %w[production staging]
end

Manual Error Reporting

// Notify with an error object
Bugsnag.notify(new Error("Payment processing failed"));

// Notify with metadata
Bugsnag.notify(new Error("API timeout"), function (event) {
  event.severity = "warning";
  event.addMetadata("request", {
    endpoint: "/api/orders",
    timeout: 30000,
    retries: 3,
  });
  event.setUser("user-123", "user@example.com", "John Doe");
});

// Notify with callback
try {
  processOrder(orderId);
} catch (err) {
  Bugsnag.notify(err, function (event) {
    event.context = "order-processing";
    event.groupingHash = "order-failure";
    event.addMetadata("order", { orderId, amount: 99.99 });
  });
}

# Python manual notification
import bugsnag

bugsnag.notify(Exception("Something went wrong"))

bugsnag.notify(
    Exception("Payment failed"),
    severity="error",
    metadata={"payment": {"amount": 99.99, "currency": "USD"}},
    user={"id": "user-123", "email": "user@example.com"},
)

Breadcrumbs

// Leave a breadcrumb for debugging context
Bugsnag.leaveBreadcrumb("User clicked checkout", {
  cartItems: 3,
  total: 149.99,
});

// Breadcrumb types: navigation, request, process, log, user, state, error, manual
Bugsnag.leaveBreadcrumb(
  "API response received",
  { status: 200, endpoint: "/api/cart" },
  "request"
);

User Tracking

// Set current user
Bugsnag.setUser("user-123", "user@example.com", "John Doe");

// Clear user on logout
Bugsnag.setUser(null, null, null);

// Set user per-event
Bugsnag.notify(error, function (event) {
  event.setUser("user-456", "other@example.com", "Jane Doe");
});

Configuration Options

Option	Description
apiKey	Project API key (required)
appVersion	Application version string
releaseStage	Current environment (production, staging, etc.)
enabledReleaseStages	Only send events from these stages
maxBreadcrumbs	Maximum breadcrumbs to keep (default: 25)
maxEvents	Max events before rate limiting
autoDetectErrors	Auto-capture unhandled exceptions (default: true)
autoTrackSessions	Auto-track user sessions (default: true)
redactedKeys	Patterns for keys to redact from metadata
endpoints	Custom endpoints for on-premise

Advanced Usage

Custom Grouping

Bugsnag.notify(error, function (event) {
  // Group all timeout errors together
  event.groupingHash = "api-timeout-" + endpoint;
});

Filtering Sensitive Data

Bugsnag.start({
  apiKey: "YOUR_API_KEY",
  redactedKeys: [
    "password",
    "secret",
    /^cc_/,  // Regex: anything starting with cc_
    "Authorization",
  ],
});

On Error Callbacks

Bugsnag.start({
  apiKey: "YOUR_API_KEY",
  onError: function (event) {
    // Drop events from crawlers
    if (event.getMetadata("request", "userAgent")?.includes("bot")) {
      return false;
    }
    // Add global metadata
    event.addMetadata("app", { buildNumber: "456" });
  },
});

Source Maps Upload

# Upload source maps for JavaScript
bugsnag-cli upload js-sourcemaps \
  --api-key YOUR_API_KEY \
  --app-version 1.2.0 \
  --directory ./dist

# Upload dSYMs for iOS
bugsnag-cli upload dsyms \
  --api-key YOUR_API_KEY \
  ./build/MyApp.xcarchive

# Upload ProGuard mappings for Android
bugsnag-cli upload android-proguard \
  --api-key YOUR_API_KEY \
  --app-version 1.2.0 \
  ./app/build/outputs/mapping/release/mapping.txt

Build Integration

# Notify Bugsnag of a new build/release
bugsnag-cli create-build \
  --api-key YOUR_API_KEY \
  --app-version 1.2.0 \
  --release-stage production \
  --builder-name "CI/CD" \
  --source-control-provider github \
  --source-control-repository https://github.com/org/repo \
  --source-control-revision $(git rev-parse HEAD)

Troubleshooting

Issue	Solution
Events not appearing	Verify API key; check enabledReleaseStages includes current stage
Source maps not resolving	Ensure appVersion matches between SDK config and upload
Too many events	Use onError to filter noise; adjust enabledReleaseStages
Duplicate errors	Check for multiple SDK initializations; review grouping logic
Breadcrumbs missing	Increase maxBreadcrumbs; verify breadcrumb types are enabled
Sessions not tracking	Ensure autoTrackSessions: true; check release stage is enabled
Sensitive data leaking	Add patterns to redactedKeys configuration
Rate limiting triggered	Reduce error volume with onError filtering