sentry-prod-checklist

Overview

Walk through every production-critical Sentry configuration item before a deploy — SDK init options, source map uploads, alert routing, PII scrubbing, sample rate tuning, and test error verification. Covers @sentry/node (v8+) and sentry-cli workflows.

Use when:

• Preparing a first production deploy with Sentry
• Auditing an existing Sentry config after an incident
• Running a go-live readiness review
• Onboarding a new service into Sentry monitoring

Prerequisites

• @sentry/node (or framework-specific SDK like @sentry/nextjs, @sentry/react) installed
• Sentry project created with a dedicated production DSN (separate from dev/staging)
• sentry-cli installed globally or as a devDependency (npm i -D @sentry/cli)
• SENTRY_AUTH_TOKEN with scope project:releases available in CI environment
• Build pipeline that produces source maps

Instructions

Work through each section in order. Check off each item as you verify it.

Step 1 — DSN and Environment Variables

• [ ] DSN set via environment variable, not hardcoded in source code

// CORRECT — DSN from environment
Sentry.init({
  dsn: process.env.SENTRY_DSN,
});

// WRONG — hardcoded DSN leaks project ID and org info
Sentry.init({
  dsn: 'https://abc123@o456.ingest.sentry.io/789',
});

Verify with: grep -r "ingest.sentry.io" src/ --include="*.ts" --include="*.js" — should return zero results.

• [ ] SENTRY_DSN set in production environment (not just .env.local)
• [ ] SENTRY_ORG and SENTRY_PROJECT set for CLI operations

Step 2 — Environment Tag

• [ ] environment tag set to 'production'

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.NODE_ENV || 'production',
});

This enables environment-scoped alert rules and release health filtering. Without it, all events land in the default (empty) environment.

Step 3 — Release Tracking

• [ ] release set to match the deploy version

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: 'production',
  release: process.env.SENTRY_RELEASE || `myapp@${process.env.npm_package_version}`,
});

The release value must match exactly what you pass to sentry-cli releases new. Mismatches break source map resolution and release health tracking.

Step 4 — Error Sample Rate

• [ ] sampleRate tuned — not 1.0 in high-traffic production

Sentry.init({
  // For most apps: 0.1 to 0.25 captures enough to spot trends
  // without burning through your event quota
  sampleRate: 0.25, // 25% of errors captured

  // For low-traffic apps or critical services, 1.0 is fine
  // sampleRate: 1.0,
});

| Traffic level | Recommended sampleRate | |---------------|--------------------------| | < 10K errors/day | 1.0 | | 10K-100K errors/day | 0.25 | | > 100K errors/day | 0.1 |

Step 5 — Traces Sample Rate

• [ ] tracesSampleRate tuned (0.05-0.2 for production)

Sentry.init({
  tracesSampleRate: 0.1, // 10% of transactions traced

  // Or use tracesSampler for endpoint-specific rates
  tracesSampler: (samplingContext) => {
    const name = samplingContext.transactionContext?.name || '';

    // Never trace health checks
    if (name.includes('/health') || name.includes('/ready')) return 0;

    // Always trace payments
    if (name.includes('/checkout') || name.includes('/payment')) return 1.0;

    // Default: 10%
    return 0.1;
  },
});

Never ship tracesSampleRate: 1.0 in production — it generates massive event volume and will exhaust your quota within hours on any real workload.

Step 6 — Source Map Upload

• [ ] Source maps uploaded via sentry-cli releases files

#!/bin/bash
# Run in CI after build, before deploy
set -euo pipefail

VERSION="${SENTRY_RELEASE:-$(git rev-parse --short HEAD)}"

# Create the release
sentry-cli releases new "$VERSION"

# Associate commits for suspect commits feature
sentry-cli releases set-commits "$VERSION" --auto

# Upload source maps from build output
sentry-cli releases files "$VERSION" upload-sourcemaps ./dist \
  --url-prefix '~/static/js' \
  --validate

# Mark release as deployed
sentry-cli releases finalize "$VERSION"
sentry-cli releases deploys "$VERSION" new -e production

• [ ] --url-prefix matches the path where assets are served (e.g., ~/static/js or ~/assets)
• [ ] --validate flag is used to catch malformed maps at build time
• [ ] Source maps are NOT served to browsers (add to .gitignore or strip from deploy artifact)

Verify upload succeeded:

sentry-cli releases files "$VERSION" list
# Should show .js and .js.map files with correct paths

Step 7 — beforeSend Noise Filter

• [ ] beforeSend configured to drop noise

Sentry.init({
  beforeSend(event, hint) {
    const error = hint?.originalException;
    const message = typeof error === 'string' ? error : error?.message || '';

    // Drop browser noise that is never actionable
    const noise = [
      'ResizeObserver loop',
      'Non-Error promise rejection captured',
      /Loading chunk \d+ failed/,
      'Network request failed',
      'AbortError',
      'TypeError: cancelled',
      'TypeError: Failed to fetch',
    ];

    for (const pattern of noise) {
      if (pattern instanceof RegExp ? pattern.test(message) : message.includes(pattern)) {
        return null; // Drop this event
      }
    }

    // Scrub auth headers if they leak into request context
    if (event.request?.headers) {
      delete event.request.headers['Authorization'];
      delete event.request.headers['Cookie'];
      delete event.request.headers['X-API-Key'];
    }

    return event;
  },
});

Step 8 — PII Scrubbing

• [ ] PII scrubbing enabled: sendDefaultPii: false

Sentry.init({
  sendDefaultPii: false, // Do NOT send cookies, user IPs, or auth headers

  // If you need user context, set it explicitly with scrubbed data
  // Sentry.setUser({ id: user.id }); // ID only, no email/name
});

Also verify in Sentry project settings:

• Settings > Security & Privacy > Data Scrubbing is enabled
• IP Address collection is disabled if not needed
• Sensitive Fields list includes your app-specific fields (e.g., ssn, creditCard)

Step 9 — Alert Rules

• [ ] Alert rules configured for production environment

Set up these minimum alert rules in Alerts > Create Alert Rule:

| Alert | Type | Condition | Action | |-------|------|-----------|--------| | New issue in production | Issue | First seen, environment:production | Slack channel + email | | Regression detected | Issue | Regressed, environment:production | Slack channel | | Error spike | Metric | Error count > N in 5 min | PagerDuty (on-call) | | P95 latency breach | Metric | p95(transaction.duration) > threshold | Slack #performance | | Crash-free rate drop | Release health | Crash-free sessions < 99% | Email + Slack |

• [ ] Alert actions route to correct channels (not a dead channel)
• [ ] PagerDuty / OpsGenie integration tested with a test alert

Step 10 — Process Exit Flush (Serverless / CLI)

• [ ] Sentry.flush() called before process exit

For serverless functions, CLI tools, or any short-lived process, events may be lost if the process exits before the SDK flushes its queue:

// AWS Lambda / serverless
import * as Sentry from '@sentry/node';

export const handler = Sentry.wrapHandler(async (event) => {
  // Your handler logic
  return { statusCode: 200 };
});

// CLI tool / script
async function main() {
  try {
    await doWork();
  } catch (err) {
    Sentry.captureException(err);
    await Sentry.flush(2000); // 2000ms timeout — enough for network round-trip
    process.exit(1);
  }
}

For long-running servers (Express, Fastify), this is handled automatically — skip this step.

Step 11 — Test Error Verification

• [ ] Test error sent and verified in Sentry dashboard

// Send a test error after deploy
Sentry.captureException(new Error('Production deploy verification — safe to ignore'));

// Or from CLI
// node -e "
//   const Sentry = require('@sentry/node');
//   Sentry.init({ dsn: process.env.SENTRY_DSN, environment: 'production' });
//   Sentry.captureMessage('Deploy verification test');
//   Sentry.flush(2000).then(() => console.log('Test event sent')); // 2s flush timeout
// "

After sending, verify in the Sentry dashboard:

1. Event appears in Issues with correct environment:production
2. Stack trace shows original source (not minified) — confirms source maps work
3. Release tag matches your deployed version
4. No PII (cookies, IPs, auth headers) in the event payload

Step 12 — Inbound Filters

• [ ] Inbound filters enabled for known browser noise

In Sentry dashboard under Settings > Inbound Filters, enable:

• Filter out known web crawlers (Googlebot, Bingbot generate noise)
• Filter out legacy browsers (IE 10 and below)
• Filter out localhost events (stray dev events)
• Custom inbound filters for domains you don't control

These filters drop events server-side before they count against your quota, unlike beforeSend which drops client-side after the network request.

Verification Script

Run this after completing all checklist items:

#!/bin/bash
# scripts/verify-sentry-prod.sh
set -euo pipefail

echo "=== Sentry Production Verification ==="

PASS=0; FAIL=0

check() {
  if eval "$2" > /dev/null 2>&1; then
    echo "  PASS: $1"; ((PASS++))
  else
    echo "  FAIL: $1"; ((FAIL++))
  fi
}

# Environment variables
for var in SENTRY_DSN SENTRY_ORG SENTRY_PROJECT SENTRY_AUTH_TOKEN; do
  check "$var is set" "[ -n \"\${$var:-}\" ]"
done

# CLI authentication
check "sentry-cli authenticated" "sentry-cli info"

# Source maps uploaded
RELEASE="${SENTRY_RELEASE:-$(git rev-parse --short HEAD)}"
check "Source maps for $RELEASE" \
  "[ \$(sentry-cli releases files \"$RELEASE\" list 2>/dev/null | wc -l) -gt 1 ]"

# Network connectivity
check "sentry.io reachable" \
  "[ \$(curl -s -o /dev/null -w '%{http_code}' https://sentry.io/api/0/) = '200' ]"

# No hardcoded DSN in source
check "No hardcoded DSN in src/" \
  "! grep -r 'ingest.sentry.io' src/ --include='*.ts' --include='*.js' --include='*.tsx' 2>/dev/null | grep -v node_modules"

echo ""
echo "=== Results: $PASS passed, $FAIL failed ==="
[ "$FAIL" -eq 0 ] && echo "All checks passed." || exit 1

Output

After completing this checklist, you will have:

• Production-hardened Sentry.init() with tuned sample rates and PII scrubbing
• Source maps uploaded and validated via sentry-cli for the current release
• beforeSend filtering known browser noise before it burns quota
• Alert rules routing to Slack, email, and PagerDuty for the production environment
• A verified test error visible in the dashboard with readable stack traces
• Inbound filters blocking crawler and legacy browser noise server-side

Error Handling

| Error | Cause | Solution | |-------|-------|----------| | Stack traces show minified code | Source maps missing or --url-prefix wrong | Re-upload with correct prefix; run sentry-cli sourcemaps explain to diagnose | | Events not appearing in dashboard | Wrong DSN or network blocked | Verify SENTRY_DSN is the production DSN; check firewall allows *.ingest.sentry.io on HTTPS | | release mismatch warning | SDK release differs from CLI release | Ensure Sentry.init({ release }) matches sentry-cli releases new $VERSION exactly | | Events from wrong environment | environment not set in SDK init | Explicitly set environment: 'production' — do not rely on defaults | | Excessive event volume / quota exhausted | sampleRate: 1.0 on high-traffic service | Lower to 0.1-0.25; add beforeSend filters; enable server-side inbound filters | | Alerts not firing | Alert rules scoped to wrong environment | Edit alert: filter to environment:production; test with Sentry.captureMessage() | | Events lost in serverless / CLI | Process exits before flush | Call await Sentry.flush(2000) before process.exit() or use Sentry.wrapHandler() | | beforeSend dropping real errors | Overly broad noise filter | Audit filter patterns; log dropped events to a secondary sink during rollout |

Examples

Example 1: Full production init (Node.js / Express)

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

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: 'production',
  release: process.env.SENTRY_RELEASE,
  debug: false,
  sendDefaultPii: false,
  sampleRate: 0.25,
  tracesSampleRate: 0.1,
  maxBreadcrumbs: 50,
  attachStacktrace: true,

  ignoreErrors: [
    'ResizeObserver loop',
    'Non-Error promise rejection captured',
    /Loading chunk \d+ failed/,
  ],

  beforeSend(event, hint) {
    if (event.request?.headers) {
      delete event.request.headers['Authorization'];
      delete event.request.headers['Cookie'];
    }
    return event;
  },

  tracesSampler: (ctx) => {
    const name = ctx.transactionContext?.name || '';
    if (name.includes('/health')) return 0;
    if (name.includes('/payment')) return 1.0;
    return 0.1;
  },
});

Example 2: CI source map upload (GitHub Actions)

# .github/workflows/deploy.yml
- name: Upload source maps to Sentry
  env:
    SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
    SENTRY_ORG: my-org
    SENTRY_PROJECT: my-project
    VERSION: ${{ github.sha }}
  run: |
    npx sentry-cli releases new "$VERSION"
    npx sentry-cli releases set-commits "$VERSION" --auto
    npx sentry-cli releases files "$VERSION" upload-sourcemaps ./dist \
      --url-prefix '~/static/js' --validate
    npx sentry-cli releases finalize "$VERSION"
    npx sentry-cli releases deploys "$VERSION" new -e production

Example 3: Serverless flush pattern (AWS Lambda)

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

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: 'production',
  release: process.env.SENTRY_RELEASE,
  tracesSampleRate: 0.2,
});

export const handler = Sentry.wrapHandler(async (event, context) => {
  // wrapHandler automatically calls flush() on completion
  const result = await processEvent(event);
  return { statusCode: 200, body: JSON.stringify(result) };
});

Resources

• Sentry Configuration Options — full SDK init reference
• Source Maps Upload — bundler plugins and CLI upload
• sentry-cli releases — new, set-commits, finalize, deploys
• Alert Rules — issue alerts, metric alerts, uptime monitors
• Release Health — crash-free rates and session tracking
• Data Scrubbing — server-side PII removal
• Inbound Filters — server-side event filtering

Next Steps

After completing this production checklist:

1. Set up release health monitoring — track crash-free session rates across releases
2. Configure ownership rules — route issues to the right team based on file paths or error tags
3. Add custom dashboards — build a deployment dashboard showing error rates, P95 latency, and throughput per release
4. Schedule quarterly audits — re-run this checklist after major dependency upgrades or architecture changes
5. Enable Session Replay (if using @sentry/browser) — capture user sessions for faster debugging