Sentry Error Capture

Overview

Capture errors and enrich them with structured context so your team can diagnose production issues in seconds instead of hours. Covers

captureException

captureMessage

withScope

push_scope

beforeSend

@sentry/node

sentry-sdk

Prerequisites

• Sentry SDK installed and initialized (

  @sentry/node

  v8+ or

  sentry-sdk

  v2+)
• A valid DSN configured via environment variable (

  SENTRY_DSN

  )
• Understanding of try/catch (JS) or try/except (Python) error handling
• A Sentry project created at sentry.io

Instructions

Step 1 -- Capture Exceptions with Full Stack Traces

Always pass real

Error

TypeScript (

@sentry/node

import * as Sentry from '@sentry/node';

// CORRECT -- full stack trace preserved
try {
  await riskyOperation();
} catch (error) {
  Sentry.captureException(error);
}

// WRONG -- no stack trace, hard to debug
Sentry.captureException('something went wrong');

// Wrapping non-Error values into proper Error objects
Sentry.captureException(new Error(`API returned ${statusCode}: ${body}`));

// Capture with inline context (no scope needed for simple cases)
Sentry.captureException(error, {
  tags: { transaction: 'purchase' },
  extra: { orderId, amount },
});

Python (

sentry-sdk

import sentry_sdk

# CORRECT -- full traceback preserved
try:
    risky_operation()
except Exception as e:
    sentry_sdk.capture_exception(e)

# Capture current exception implicitly (inside except block)
try:
    risky_operation()
except Exception:
    sentry_sdk.capture_exception()  # captures sys.exc_info() automatically

Step 2 -- Capture Messages for Non-Exception Events

Use

captureMessage

TypeScript

// Severity levels: 'fatal' | 'error' | 'warning' | 'info' | 'debug' | 'log'
Sentry.captureMessage('Payment processed successfully', 'info');
Sentry.captureMessage('Deprecated API endpoint accessed', 'warning');
Sentry.captureMessage('Database connection pool exhausted', 'fatal');

Python

sentry_sdk.capture_message("Payment gateway timeout", level="warning")
sentry_sdk.capture_message("Daily report generated", level="info")
sentry_sdk.capture_message("Connection pool exhausted", level="fatal")

Step 3 -- Enrich Events with Scoped Context

Use

withScope

push_scope

TypeScript -- withScope

Sentry.withScope((scope) => {
  // User identity for issue assignment and impact analysis
  scope.setUser({
    id: user.id,
    email: user.email,
    subscription: user.plan,
  });

  // Tags: indexed, searchable in Sentry UI filters
  scope.setTag('payment_provider', 'stripe');
  scope.setTag('feature', 'checkout');

  // Structured context: visible in event detail sidebar
  scope.setContext('payment', {
    amount: 9999,
    currency: 'USD',
    customer_id: 'cus_abc123',
    idempotency_key: 'idem_xyz789',
  });

  // Extra data: arbitrary key-value pairs for debugging
  scope.setExtra('cart', cartItems);

  // Override severity level
  scope.setLevel('fatal');

  // Custom fingerprint to control issue grouping
  scope.setFingerprint(['checkout-failure', paymentProvider]);

  Sentry.captureException(error);
});
// Scope is automatically cleaned up -- global scope unchanged

Python -- push_scope

with sentry_sdk.push_scope() as scope:
    scope.user = {"id": user_id, "email": user_email}
    scope.set_tag("feature", "checkout")
    scope.set_extra("cart", cart_items)
    scope.level = "fatal"
    scope.fingerprint = ["checkout-failure", str(error_code)]
    sentry_sdk.capture_exception(error)
# Scope is automatically cleaned up

Breadcrumbs

Breadcrumbs create a trail of events leading up to an error. Sentry auto-captures some (console logs, HTTP requests, DOM events), but manual breadcrumbs add domain-specific context.

TypeScript

Sentry.addBreadcrumb({
  category: 'auth',
  message: `User ${userId} logged in via ${provider}`,
  level: 'info',
  data: { provider, method: 'oauth2' },
});

Sentry.addBreadcrumb({
  category: 'transaction',
  message: 'Payment initiated',
  level: 'info',
  data: { amount: 49.99, items: 3 },
});
// The next captured error includes all breadcrumbs above

Python

sentry_sdk.add_breadcrumb(
    category="auth",
    message=f"User {user_id} logged in via {provider}",
    level="info",
    data={"provider": provider, "method": "oauth2"},
)

sentry_sdk.add_breadcrumb(
    category="transaction",
    message="Payment initiated",
    level="info",
    data={"amount": 49.99, "items": 3},
)

Custom Fingerprinting

Override Sentry's default grouping to control how errors are merged into issues. Without custom fingerprints, Sentry groups by stack trace, which can split logically identical errors or merge unrelated ones.

// Group all timeout errors for /api/search into one issue
Sentry.withScope((scope) => {
  scope.setFingerprint(['api-timeout', 'search-endpoint']);
  Sentry.captureException(new Error('Search API timeout'));
});

// Group by error type + HTTP status + endpoint
Sentry.withScope((scope) => {
  scope.setFingerprint(['http-error', String(response.status), endpoint]);
  Sentry.captureException(error);
});

// Use {{ default }} to extend rather than replace default grouping
Sentry.withScope((scope) => {
  scope.setFingerprint(['{{ default }}', tenantId]);
  Sentry.captureException(error);
});

Global Filtering with beforeSend

Configure

beforeSend

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  beforeSend(event, hint) {
    const error = hint?.originalException;

    // Drop specific error types
    if (error instanceof AbortError) return null;
    if (error?.message?.match(/ResizeObserver loop/)) return null;

    // Scrub sensitive headers
    if (event.request?.headers) {
      delete event.request.headers['Authorization'];
      delete event.request.headers['Cookie'];
    }

    // Enrich database errors with subsystem tag
    if (error instanceof DatabaseError) {
      event.tags = { ...event.tags, subsystem: 'database' };
      event.level = 'fatal';
    }

    return event; // Must return event or null
  },

  // Pattern-based noise filtering
  ignoreErrors: [
    'ResizeObserver loop',
    'Non-Error promise rejection',
    /Loading chunk \d+ failed/,
    'Network request failed',
  ],
});

Output

• Errors with full stack traces and context in the Sentry Issues dashboard
• Scoped tags and structured context for filtering and search
• Breadcrumb trails showing the user journey before errors
• Custom fingerprints grouping related errors into single issues
• Clean event stream via

  beforeSend

  filtering and

  ignoreErrors

Error Handling

new Error()

scope.setFingerprint()

beforeSend

undefined

event

null

withScope()

push_scope()

ignoreErrors

beforeSend

sampleRate

setExtra

setContext('name', {...})

Examples

TypeScript -- Express Route with Context

import express from 'express';
import * as Sentry from '@sentry/node';

const app = express();
Sentry.setupExpressErrorHandler(app);

app.get('/api/users/:id', async (req, res) => {
  Sentry.setUser({ id: req.params.id });
  try {
    const user = await getUser(req.params.id);
    res.json(user);
  } catch (error) {
    Sentry.withScope((scope) => {
      scope.setContext('request', {
        params: req.params,
        query: req.query,
        method: req.method,
      });
      Sentry.captureException(error);
    });
    res.status(500).json({ error: 'Internal server error' });
  }
});

TypeScript -- Batch Processing with Promise.allSettled

async function processQueue(items: QueueItem[]) {
  const results = await Promise.allSettled(
    items.map(item => processItem(item))
  );
  results.forEach((result, index) => {
    if (result.status === 'rejected') {
      Sentry.withScope((scope) => {
        scope.setTag('queue_item_index', String(index));
        scope.setContext('item', items[index]);
        Sentry.captureException(result.reason);
      });
    }
  });
}

Python -- Background Job Error

import sentry_sdk

def process_report(report_id: str, user_id: str):
    sentry_sdk.add_breadcrumb(
        category="jobs",
        message=f"Report generation started: {report_id}",
        level="info",
    )
    try:
        data = fetch_report_data(report_id)
        return generate_pdf(data)
    except Exception as error:
        with sentry_sdk.push_scope() as scope:
            scope.user = {"id": user_id}
            scope.set_tag("job_type", "report_generation")
            scope.set_context("report", {
                "report_id": report_id,
                "stage": "pdf_generation",
            })
            scope.fingerprint = ["report-failure", report_id]
            sentry_sdk.capture_exception(error)
        raise

Resources

• Capturing Errors --

  captureException

  and

  captureMessage

  reference
• Scopes and Context --

  withScope

  ,

  setUser

  ,

  setTag

  ,

  setContext

• Breadcrumbs -- manual and auto-captured breadcrumbs
• Filtering Events --

  beforeSend

  ,

  ignoreErrors

  , sampling
• Issue Grouping -- fingerprinting and merge/unmerge
• Python SDK Usage -- Python-specific capture patterns

Next Steps

• Performance tracing: Add

  Sentry.startSpan()

  to measure operation timing (see

  sentry-performance-tracing

  )
• Release management: Tag errors with release versions for regression detection (see

  sentry-release-management

  )
• Cost tuning: Configure

  sampleRate

  and

  tracesSampleRate

  to control event volume (see

  sentry-cost-tuning

  )