sentry-cost-tuning

What this skill does

# Sentry Cost Tuning

Reduce Sentry spend by 60-95% through SDK-level sampling, server-side inbound filters, `beforeSend` event dropping, and quota management — without losing visibility into production errors that matter.

## Prerequisites

- Active Sentry account with `org:read` and `project:read` scopes on an auth token
- Access to the project's `Sentry.init()` configuration (typically `sentry.client.config.ts` or `instrument.ts`)
- Current plan tier identified: Developer (free, 5K errors/mo), Team ($26/mo, 50K errors + 100K transactions), or Business ($80/mo, 100K errors + 500K transactions)
- `SENTRY_AUTH_TOKEN` and `SENTRY_ORG` environment variables set for API calls
- `@sentry/node` >= 8.0 or `@sentry/browser` >= 8.0 installed

## Instructions

### Step 1 — Audit Current Usage via the Stats API

Query the Sentry Usage Stats API to understand where volume comes from before making changes. This endpoint returns event counts grouped by category over any time period.

```bash
# Pull 30-day usage breakdown by category
curl -s -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/organizations/$SENTRY_ORG/stats/usage/?statsPeriod=30d&groupBy=category&field=sum(quantity)&interval=1d" \
  | python3 -c "
import json, sys
data = json.load(sys.stdin)
print('=== 30-Day Usage by Category ===')
for group in data.get('groups', []):
    cat = group['by']['category']
    total = sum(interval[1] for interval in group.get('series', {}).get('sum(quantity)', []))
    print(f'  {cat}: {total:,} events')
"
```

```bash
# Identify top error-producing projects
curl -s -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/organizations/$SENTRY_ORG/stats/usage/?statsPeriod=30d&groupBy=project&category=error&field=sum(quantity)" \
  | python3 -c "
import json, sys
data = json.load(sys.stdin)
projects = []
for group in data.get('groups', []):
    proj = group['by']['project']
    total = sum(interval[1] for interval in group.get('series', {}).get('sum(quantity)', []))
    projects.append((proj, total))
projects.sort(key=lambda x: -x[1])
print('=== Top Error-Producing Projects ===')
for name, count in projects[:10]:
    print(f'  {name}: {count:,}')
"
```

Record the baseline numbers. You need these to measure savings after optimization.

### Step 2 — Configure Error Sampling with `sampleRate`

The `sampleRate` option in `Sentry.init()` controls the percentage of error events sent to Sentry. Setting it to `0.1` means only 10% of errors are sent, yielding a 90% cost reduction on the error category.

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

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

  // 10% of errors sent = 90% cost reduction
  // Sentry extrapolates counts in the Issues dashboard
  sampleRate: 0.1,
});
```

**Trade-off:** Low-frequency errors (< 10 occurrences/day) may be missed entirely. Mitigate this by using `beforeSend` to always send errors with specific severity or tags rather than relying on blanket sampling.

### Step 3 — Configure Performance Sampling with `tracesSampleRate` and `tracesSampler`

Performance monitoring (transactions/spans) is typically the largest cost driver. A `tracesSampleRate` of `0.05` sends only 5% of traces, cutting performance costs by 95%.

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

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

  // Static: 5% of all traces (95% cost reduction)
  tracesSampleRate: 0.05,

  // Dynamic: per-endpoint sampling for fine-grained control
  // When tracesSampler is defined, it overrides tracesSampleRate
  tracesSampler: (samplingContext) => {
    const { name, attributes } = samplingContext;

    // Never trace health checks, readiness probes, static assets
    if (name?.match(/\/(health|healthz|ready|livez|ping|robots\.txt|favicon)/)) {
      return 0;
    }
    if (name?.match(/\.(js|css|png|jpg|svg|woff2?|ico)$/)) {
      return 0;
    }

    // High-value: payment and auth flows get 50% sampling
    if (name?.includes('/checkout') || name?.includes('/payment')) {
      return 0.5;
    }
    if (name?.includes('/auth') || name?.includes('/login')) {
      return 0.25;
    }

    // API routes: 5%
    if (name?.includes('/api/')) {
      return 0.05;
    }

    // Everything else: 1%
    return 0.01;
  },
});
```

The `tracesSampler` function receives a `samplingContext` with the transaction `name` (usually the route) and `attributes`. Return a number between `0` (drop) and `1` (always send), or `true`/`false`.

### Step 4 — Drop Noisy Events with `beforeSend`

The `beforeSend` hook fires for every error event before it is sent to Sentry. Returning `null` drops the event entirely — it never counts against quota.

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

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

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

    // Drop ResizeObserver noise (Chrome fires this constantly, never actionable)
    if (message.includes('ResizeObserver loop')) return null;

    // Drop network errors from flaky client connections
    if (/^(Failed to fetch|NetworkError|Load failed|AbortError)$/i.test(message)) {
      return null;
    }

    // Drop cancelled navigation (user clicked away)
    if (message.includes('cancelled') || message.includes('AbortError')) {
      return null;
    }

    // Drop browser extension errors by checking stack frames
    const frames = event.exception?.values?.[0]?.stacktrace?.frames || [];
    if (frames.some(f => f.filename?.match(/extensions?\//i) || f.filename?.match(/^(chrome|moz)-extension:\/\//))) {
      return null;
    }

    // Always send critical errors regardless of sampleRate
    // Re-enable any that were sampled out
    if (event.level === 'fatal' || event.tags?.critical === 'true') {
      return event;
    }

    return event;
  },

  // Complementary: block errors from known noisy patterns
  ignoreErrors: [
    'ResizeObserver loop completed with undelivered notifications',
    'ResizeObserver loop limit exceeded',
    'Non-Error promise rejection captured',
    /Loading chunk \d+ failed/,
    /Unexpected token '<'/,       // HTML returned instead of JS (CDN issue)
    /^Script error\.?$/,          // Cross-origin script with no details
  ],

  // Block events from third-party scripts
  denyUrls: [
    /extensions\//i,
    /^chrome:\/\//i,
    /^chrome-extension:\/\//i,
    /^moz-extension:\/\//i,
    /hotjar\.com/,
    /intercom\.io/,
    /google-analytics\.com/,
    /googletagmanager\.com/,
    /cdn\.segment\.com/,
  ],
});
```

### Step 5 — Enable Server-Side Inbound Data Filters (Free)

Inbound data filters drop events at Sentry's edge before they are ingested and counted against quota. They cost nothing to enable.

Navigate to **Project Settings > Inbound Filters** (or use the API) and enable:

| Filter | What it drops | Impact |
|--------|--------------|--------|
| Browser Extensions | Errors from Chrome/Firefox extensions | 5-15% of frontend errors |
| Legacy Browsers | IE 11, old Safari/Chrome versions | 2-10% depending on audience |
| Localhost Events | Errors from `localhost` and `127.0.0.1` | Dev noise (variable) |
| Web Crawlers | Bot-triggered errors (Googlebot, Bingbot) | 1-5% of frontend errors |
| Filtered Transactions | Health checks, static asset requests | 10-40% of transactions |

```bash
# Enable inbound filters via API
for filter in browser-extensions legacy-browsers localhost-events web-crawlers; do
  curl -s -X PUT \
    -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"active": true}' \
    "https://sentry.io/api/0/projects/$SENTRY_ORG/$SENTRY_PROJECT/filters/$filter/"
  echo " -> Enabled: $filter"
done
```

Add custom error message filters for project-specific noise:

```bash
# Add custom inbound filter for error messages
curl -s -X PUT \
  -H "Authorization: Bearer $SENTRY_AUTH_TOKEN"