Sentry Integration skill for Codex

Done well means: the SDK initialises before anything else runs, every event carries release and environment, production stack traces are readable because source maps uploaded for that exact build, sampling keeps cost predictable, and no secrets or unnecessary personal data leave the app.

Inspect first

1. Read AGENTS.md; then rg -n "@sentry/|sentry_sdk|SENTRY_" --glob '!node_modules'.
2. Note the SDK major version in the lockfile and the framework (Next.js, Vite SPA, Node server, Django/FastAPI). Mixed @sentry/* versions in one app cause runtime errors; align them.
3. Find the build output directory, how the app is versioned (git SHA, semver tag) and the CI system.
4. Confirm DSN, org slug, project slug, and that an auth token exists as a CI secret (SENTRY_AUTH_TOKEN, organization token with release and source map permissions).

The setup wizard (npx @sentry/wizard@latest -i nextjs, or -i sourcemaps) writes most of this for you but needs network and an interactive login; in a sandbox without network, write the files by hand following the sections below.

Where init goes

Runtime	File and rule
Next.js (App Router)	instrumentation-client.ts (browser), sentry.server.config.ts and sentry.edge.config.ts imported from instrumentation.ts register(); wrap next.config with withSentryConfig
Vite / SPA	First import in main.tsx, before the app renders
Node (ESM)	instrument.mjs loaded with node --import ./instrument.mjs server.mjs so auto-instrumentation patches modules before they load
Node (CJS)	require('./instrument') as the first line of the entry file
Python	sentry_sdk.init() at process start, before the framework app object is created

// instrument.mjs (Node) or the browser init file
import * as Sentry from '@sentry/node';   // @sentry/react, @sentry/nextjs, ...

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.SENTRY_ENVIRONMENT ?? 'development',
  release: process.env.SENTRY_RELEASE,      // build plugins inject this automatically
  sendDefaultPii: false,
  tracesSampleRate: 0.1,
  beforeSend(event) {
    if (event.request?.headers) delete event.request.headers['authorization'];
    return event;
  },
});

import sentry_sdk

sentry_sdk.init(
    dsn=os.environ.get("SENTRY_DSN"),
    environment=os.environ.get("SENTRY_ENVIRONMENT", "development"),
    release=os.environ.get("SENTRY_RELEASE"),
    traces_sample_rate=0.1,
    send_default_pii=False,
)

Django, Flask, FastAPI, Celery and most popular libraries are auto-detected; add integrations explicitly only to change options.

Sampling and cost

Signal	Starting point	Notes
Errors	100% (sampleRate: 1)	Drop noise with ignoreErrors / denyUrls, not by sampling
Traces	0.05-0.2, or a tracesSampler that keeps 100% of checkout/login and drops health checks	Spans are billed
Session Replay	replaysSessionSampleRate: 0-0.1, replaysOnErrorSampleRate: 1.0	Replay masks all text and inputs by default; keep it that way
Profiles	Only when actively investigating performance

Set inbound filters and spike protection in the project settings too; changing org billing or quotas is the user’s decision.

Source maps

Source maps are matched to minified files by debug ID. Upload them for every production build and do not serve them publicly.

Vite:

// vite.config.ts
import { sentryVitePlugin } from '@sentry/vite-plugin';

export default defineConfig({
  build: { sourcemap: 'hidden' },          // generate maps, no sourceMappingURL comment
  plugins: [
    react(),
    sentryVitePlugin({                     // keep last
      org: process.env.SENTRY_ORG,
      project: process.env.SENTRY_PROJECT,
      authToken: process.env.SENTRY_AUTH_TOKEN,
      sourcemaps: { filesToDeleteAfterUpload: ['./dist/**/*.map'] },
    }),
  ],
});

Next.js: withSentryConfig(nextConfig, { org, project, authToken: process.env.SENTRY_AUTH_TOKEN, widenClientFileUpload: true, silent: !process.env.CI }). Webpack and esbuild have equivalent @sentry/webpack-plugin and @sentry/esbuild-plugin.

Any other bundler, or a prebuilt dist/:

npx @sentry/cli sourcemaps inject ./dist
npx @sentry/cli sourcemaps upload --org "$SENTRY_ORG" --project "$SENTRY_PROJECT" ./dist

Deploy the files that went through inject; if the build runs again after upload, debug IDs no longer match.

Releases and deploys in CI

export SENTRY_RELEASE="$(git rev-parse HEAD)"   # same value passed to the build and to Sentry.init
npx @sentry/cli releases new "$SENTRY_RELEASE"
npx @sentry/cli releases set-commits "$SENTRY_RELEASE" --auto
# build + source map upload happen here
npx @sentry/cli releases finalize "$SENTRY_RELEASE"
npx @sentry/cli deploys new --release "$SENTRY_RELEASE" -e production

• set-commits --auto needs the repository integration configured in Sentry and full git history in CI (fetch-depth: 0 on GitHub Actions); otherwise suspect commits stay empty.
• Mark the deploy only after the production deploy succeeds. Use one release value across frontend and backend only if they deploy together.
• Releases and deploys are visible to the whole org; creating them from a local machine against the production project should be confirmed with the user.

Context that makes events actionable

• Sentry.setUser({ id: user.id }) - an internal ID, not email, unless the privacy policy allows it.
• Sentry.setTag('tenant', tenantId) for searchable dimensions; keep tag cardinality modest.
• Sentry.captureException(err, { extra: { orderId } }) where you catch and handle errors that still matter. Do not capture expected validation errors.
• Wrap background jobs and cron entries; use Cron Monitors (Sentry.withMonitor) for scheduled jobs.
• Browser apps blocked by ad blockers: route through your own domain (tunnel option, or tunnelRoute in the Next.js config).

Verification

• Trigger a test error in a production-like build (throw new Error('sentry smoke ' + Date.now()) behind a debug route or flag) and find it in Sentry within a minute.
• The event shows the expected release and environment, and the top frame is original source with file names and line numbers, not main.3f9a.js:1:20431.
• If frames are minified, open the issue’s source map troubleshooting details: usually a missing debug ID (build not injected), a map uploaded for another build, or maps deleted before upload.
• .map files return 404 from the production host.
• Authorization headers, cookies and tokens are absent from the event payload.
• Remove the smoke-test route afterwards.

Gotchas

• Initialising Sentry after importing express, pg or http silently disables their tracing.
• SENTRY_AUTH_TOKEN in a client bundle (via NEXT_PUBLIC_ or VITE_ prefix) leaks it; it belongs only in CI env. The DSN is public by design.
• tracesSampleRate: 1.0 copied from docs into production burns the span quota in hours.
• Running the build twice in CI (once for tests, once for deploy) uploads maps for the wrong artifact.
• Different release strings in frontend init and CLI upload break release health and suspect commits.

Output

Report: SDKs and versions, init file locations, release naming, source map method, sampling rates, CI steps added, scrubbing rules, and the smoke-test event link or ID.