Sentry Performance Tracing

Overview

Sentry performance monitoring captures distributed traces across your application stack, measuring latency, identifying bottlenecks, and tracking Web Vitals. The v8 SDK uses a span-based API where Sentry.startSpan() replaces the deprecated startTransaction(). Auto-instrumentation covers HTTP, database queries, and framework routes out of the box. Manual spans let you measure business-critical operations. Combined with profiling (profilesSampleRate), you get function-level flamegraphs attached to traces.

Prerequisites

• Sentry SDK v8+ installed (@sentry/node >= 8.0.0 or sentry-sdk >= 2.0.0)
• tracesSampleRate > 0 set in Sentry.init() — performance data is not collected at zero
• Performance monitoring enabled in your Sentry project settings (Settings > Performance)
• For distributed tracing: all participating services must have Sentry SDK initialized

Instructions

Step 1 — Configure Tracing and Profiling in SDK Init

Set tracesSampleRate to control what percentage of requests generate traces. Use tracesSampler for dynamic, per-endpoint sampling. Add profilesSampleRate to attach function-level flamegraphs to sampled transactions.

TypeScript (@sentry/node):

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

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: 0.2, // 20% of transactions in production

  // Profiling — profiles 10% of sampled transactions
  profilesSampleRate: 0.1,

  // Dynamic sampling overrides tracesSampleRate when defined
  tracesSampler: (samplingContext) => {
    const { name, attributes } = samplingContext;

    // Drop health checks entirely — no trace data
    if (name === 'GET /health') return 0;

    // Always trace payment flows
    if (name?.includes('/api/payment')) return 1.0;

    // Higher sampling for API routes
    if (name?.startsWith('GET /api/') || name?.startsWith('POST /api/')) return 0.2;

    // Default: 5% for everything else
    return 0.05;
  },
});

Python (sentry-sdk):

import os
import sentry_sdk

sentry_sdk.init(
    dsn=os.environ["SENTRY_DSN"],
    traces_sample_rate=0.2,       # 20% of transactions
    profiles_sample_rate=0.1,     # 10% of sampled transactions get profiled

    # Dynamic sampling via traces_sampler (overrides traces_sample_rate)
    traces_sampler=lambda ctx: (
        0.0 if ctx.get("transaction_context", {}).get("name") == "GET /health"
        else 1.0 if "/api/payment" in ctx.get("transaction_context", {}).get("name", "")
        else 

Sentry Rate Limits & Quota Optimization

Overview

Manage Sentry rate limits, sampling strategies, and quota usage to control costs without losing visibility into critical errors. Covers client-side sampling, beforeSend filtering, server-side inbound filters, per-key rate limits, spike protection, and the usage stats API.

Prerequisites

• Sentry account with a project DSN configured
• SENTRY_AUTH_TOKEN with org:read and project:write scopes (Settings > Auth Tokens)
• SENTRY_ORG and SENTRY_PROJECT slugs known
• SDK installed: @sentry/node (npm) or sentry-sdk (pip)
• Current event volume visible at sentry.io/stats/

Instructions

Step 1 — Understand Rate Limit Behavior

When your project exceeds its quota, Sentry returns 429 Too Many Requests with a Retry-After header. The SDK automatically stops sending events until the cooldown expires. Events generated during this window are permanently lost — there is no replay mechanism.

Rate limit tiers by plan:

Quota categories (billed separately):

• Errors — exceptions and log messages
• Transactions — performance monitoring spans
• Replays — session replay recordings
• Attachments — file uploads (crash dumps, minidumps)
• Profiles — continuous profiling data
• Cron monitors — scheduled job check-ins

Rate limit headers returned on 429:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-Sentry-Rate-Limit-Limit: 50
X-Sentry-Rate-Limit-Remaining: 0
X-Sentry-Rate-Limit-Reset: 1711324800

Step 2 — Configure Client-Side Sampling

Sampling is the first line of defense. Set sampleRate for errors and tracesSampleRate for performance transactions.

TypeScript / Node.js:

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

Sentry.init({
  dsn: process.env.SENTRY_DSN,

  // Error sampling: 0.0 (drop all) to 1.0 (capture all)
  sampleRate: 0.25, // Capture 25% of errors

  // Transaction sampling: 0.0 to 1.0
  tracesSampleRate: 0.1, // Capture 10% of transactions

  // Dynamic transaction

Sentry Reliability Patterns

Overview

Build Sentry integrations that never take your application down via three pillars: safe initialization with graceful degradation, a circuit breaker that stops hammering Sentry when unreachable, and an offline event queue that buffers errors during outages. Every pattern prioritizes application uptime over telemetry completeness.

Prerequisites

• @sentry/node v8+ (TypeScript) or sentry-sdk v2+ (Python)
• A valid Sentry DSN from project settings at sentry.io
• A fallback logging destination decided (console, file, or external logger)
• Understanding of your application shutdown lifecycle (signal handlers, container orchestration)

Instructions

Step 1 — Safe Initialization with Graceful Degradation

Wrap Sentry.init() in try/catch so an invalid DSN, network error, or SDK bug never crashes the app. Track initialization state with a boolean flag. Protect beforeSend callbacks with their own error boundary.

Create lib/sentry-safe.ts with initSentrySafe() and captureError(). See graceful-degradation.md for full implementation.

Key rules:

• Never let Sentry.init() crash the process — wrap in try/catch, set sentryAvailable = false on failure
• Verify client creation with Sentry.getClient() — invalid DSNs silently produce no client
• Always log errors locally as baseline before attempting Sentry capture
• Wrap user-supplied beforeSend hooks in nested try/catch — return raw event on hook failure

Step 2 — Circuit Breaker for Sentry Outages

When Sentry is unreachable, continued attempts waste resources and add latency. Track consecutive failures and trip open after a threshold. After cooldown, enter half-open state and send a single probe.

Implement SentryCircuitBreaker class with closed/open/half-open states. See circuit-breaker-pattern.md for full implementation. Expose state via health-checks.md endpoint.

Key rules:

• Default: 5 failures to trip open, 60-second cooldown before half-open probe
• In open state, skip Sentry calls entirely and log to fallback
• On half-open success, reset to closed with zero failure count
• Expose getStatus() for health check endpoints and monitoring dashboards

Step 3 — Offline Queue, Custom Transport, and Graceful Shutdown

Buffer events when network is unavailable and replay on reconnect. Use bounded file-based queue to survive restarts. Pair with signal handlers that flush via Sentry.close() before process exit.

Implement thre

Sentry SDK Patterns

Overview

Production patterns for @sentry/node (v8+) and sentry-sdk (Python 2.x+) covering scoped error context, breadcrumb strategies, event filtering with beforeSend, custom fingerprinting for issue grouping, and performance instrumentation with spans. All examples use real Sentry SDK APIs.

Prerequisites

• Sentry SDK v8+ installed (@sentry/node, @sentry/react, or sentry-sdk)
• SENTRY_DSN environment variable configured
• Familiarity with async/await (TypeScript) or context managers (Python)

Instructions

Step 1 -- Structured Error Context with Scopes

Use Sentry.withScope() (TypeScript) or sentry_sdk.new_scope() (Python) to attach context to individual events without leaking state across requests.

TypeScript -- Scoped error capture:

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

type ErrorSeverity = 'low' | 'medium' | 'high' | 'critical';

interface ErrorOptions {
  severity?: ErrorSeverity;
  tags?: Record<string, string>;
  context?: Record<string, unknown>;
  user?: { id: string; email?: string };
  fingerprint?: string[];
}

const SEVERITY_MAP: Record<ErrorSeverity, Sentry.SeverityLevel> = {
  low: 'info',
  medium: 'warning',
  high: 'error',
  critical: 'fatal',
};

export function captureError(error: Error, options: ErrorOptions = {}) {
  Sentry.withScope((scope) => {
    scope.setLevel(SEVERITY_MAP[options.severity || 'medium']);

    if (options.tags) {
      Object.entries(options.tags).forEach(([key, value]) => {
        scope.setTag(key, value);
      });
    }
    if (options.context) {
      scope.setContext('app', options.context);
    }
    if (options.user) {
      scope.setUser(options.user);
    }
    if (options.fingerprint) {
      scope.setFingerprint(options.fingerprint);
    }

    Sentry.captureException(error);
  });
}

Python -- Scoped error capture:

import sentry_sdk

def capture_error(error, severity="error", tags=None, context=None, user=None):
    """Capture exception with isolated scope context."""
    with sentry_sdk.new_scope() as scope:
        scope.set_level(severity)
        if tags:
            for key, value in tags.items():
                scope.set_tag(key, value)
        if context:
            scope.set_context("app", context)
        if user:
            scope.set_user(user)
        sentry_sdk.capture_exception(error)

Key rule: Never call Sentry.setTag() or sentry_sdk.set_tag() at the module level inside request handlers. Those mutate the glob

Sentry Security Basics

Overview

Configure Sentry's security posture: PII scrubbing with beforeSend, built-in data scrubbing, IP anonymization, browser SDK URL filtering, DSN vs auth token handling, CSP reporting, and GDPR data deletion. Covers both client-side (SDK) and server-side (dashboard) controls.

Prerequisites

• Sentry project created with Owner or Admin role
• @sentry/node >= 8.x or @sentry/browser >= 8.x installed (or sentry-sdk >= 2.x for Python)
• Compliance requirements identified (GDPR, SOC 2, HIPAA, CCPA)
• List of sensitive data patterns for your domain (PII fields, API keys, tokens)

Instructions

Step 1 — Understand DSN vs Auth Token Security

The DSN (Data Source Name) is a client-facing identifier — it tells the SDK where to send events. It is NOT a secret.

https://<public-key>@o<org-id>.ingest.us.sentry.io/<project-id>

• The DSN cannot read data, delete events, or modify settings
• It is safe to ship in client-side JavaScript bundles
• Restrict abuse via Allowed Domains (Project Settings > Client Keys > Configure)

Auth tokens ARE secrets — they grant API access to read/write/delete data:

# NEVER commit auth tokens — store in CI secrets or vault
# GitHub Actions: Settings > Secrets > SENTRY_AUTH_TOKEN
# GitLab CI: Settings > CI/CD > Variables (protected + masked)

# Generate tokens with MINIMAL scopes:
#   CI releases:   project:releases, org:read
#   Issue triage:  project:read, event:read
#   NEVER:         org:admin, member:admin in CI

# Rotate tokens quarterly — revoke unused tokens immediately
# Create separate tokens per pipeline (staging vs production)

Step 2 — Disable Default PII Collection

sendDefaultPii defaults to false — but always set it explicitly so intent is clear:

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

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  sendDefaultPii: false, // explicit: no IPs, no cookies, no user-agent
});

When sendDefaultPii: false (default):

• No IP addresses attached to events
• No cookies sent in request data
• No user-agent strings in request headers
• No request body data captured
• User context must be set manually via Sentry.setUser()

# Python equivalent
import sentry_sdk

sentry_sdk.init(
    dsn=os.environ["SENTRY_DSN"],
    send_default_pii=False,  # default, but be explicit
)

Step 3 — Client-Side PII Scrubbing with be

Sentry Upgrade Migration

Detect installed Sentry SDK versions, identify breaking API changes, apply automated codemods, and verify the upgrade succeeds with test events and traces.

Current State

!npm list 2>/dev/null | command grep @sentry || echo 'No npm Sentry packages found' !pip show sentry-sdk 2>/dev/null | command grep -E '^(Name|Version)' || echo 'No Python sentry-sdk found' !node --version 2>/dev/null || echo 'Node.js not available'

Overview

Sentry SDK upgrades require careful handling of breaking API changes. The v7 to v8 JavaScript migration is the most impactful, removing the Hub pattern, replacing Transaction/Span APIs with startSpan(), converting class-based integrations to functions, and requiring ESM-first initialization. Python SDK v1 to v2 similarly replaces configure_scope() with get_current_scope(). This skill automates version detection, runs the official @sentry/migr8 codemod, applies manual fixes for patterns the codemod misses, and validates the upgrade with test events.

Prerequisites

• Current Sentry SDK version identified (run DCI above)
• Target version changelog reviewed
• Non-production environment for testing upgrades
• All @sentry/* packages at the same major version before starting
• Node.js >= 18.19.0 or >= 20.6.0 for SDK v8 (ESM support required)

Instructions

Step 1. Identify Current SDK Version and Scan for Deprecated APIs

# JavaScript: list all Sentry packages and their versions
npm ls 2>/dev/null | command grep "@sentry/"

# Python: check installed version
pip show sentry-sdk 2>/dev/null

# Verify all @sentry/* packages are the same major version (critical!)
# Mixed versions cause runtime crashes
npm ls @sentry/core @sentry/node @sentry/browser @sentry/utils 2>/dev/null

Scan the codebase for deprecated patterns that need migration:

# Detect v7 Hub usage (removed in v8)
command grep -rn "getCurrentHub\|configureScope\|hub\.capture" src/ --include="*.ts" --include="*.js"

# Detect v7 Transaction API (replaced in v8)
command grep -rn "startTransaction\|\.startChild\|\.finish()" src/ --include="*.ts" --include="*.js"

# Detect class-based integrations (replaced in v8)
command grep -rn "new Sentry\.\|new BrowserTracing\|new Integrations\." src/ --include="*.ts" --include="*.js"

# Detect @sentry/tracing imports (package removed in v8)
command grep -rn "from '@sentry/tracing'" src/ --include="*.ts" --include="*.js"

# Python: detect v1 scope API (replaced in v2)
command grep -rn "configure_scope\|push_scope" src/ --inc