sentry-observability

name

sentry-observability

description

Operate Sentry end-to-end — error monitoring, performance tracing, session replay, profiling, release health, source-map upload, ownership routing, alert tuning, issue triage, and CI integration via sentry-cli — across web, mobile, and backend stacks. Use when instrumenting an app, wiring releases into deploy pipelines, or running incident-grade triage. Requires SENTRY_AUTH_TOKEN (org-scoped, `project:releases project:write`), project DSN, and (for source maps) `org` + `project` slugs.

Sentry Observability

Wire Sentry into apps and pipelines for actionable signals: linked errors-to-replays-to-traces, clean release health, low-noise alerts, and unambiguous ownership.

Stack Baseline (2026)

Concern	Choice	Notes
SDKs	@sentry/{browser,node,nextjs,react,vue,angular,sveltekit,astro,remix} ≥ 9.x; sentry-python ≥ 2.x; sentry-java ≥ 8.x; sentry-cocoa ≥ 8.x; sentry-android ≥ 8.x	OpenTelemetry-native; auto-instrumentation by default
Tracing	tracesSampleRate (or tracesSampler for path-based)	Start at 0.1; raise per-route as needed
Replay	@sentry/replay integration; replaysSessionSampleRate low (0.01), replaysOnErrorSampleRate high (1.0)	Mask PII by default
Profiling	@sentry/profiling-node, browser profiling beta	Sampled on top of traces
Cron monitors	Sentry.cron(...) / monitor slug check-ins	Replaces dead-man-switch tooling
Source maps	sentry-cli sourcemaps upload (or framework wizard / Vite/webpack/rspack plugin)	Inject Debug ID for reliable resolution
Releases	Release name = git SHA or semver; finalize after deploy	Required for regression detection
Environments	Stable taxonomy: dev, ci, staging, production	Tag every event
Alerts	Issue alerts (regression, frequency, new-issue) + Metric alerts (SLO/throughput)	Route via Teams/Slack/PagerDuty
Ownership	.sentry/codeowners + path/url rules in project settings	Auto-assign + auto-route
Data retention / scrub	beforeSend, server-side data scrubbers, sendDefaultPii: false	GDPR/CCPA discipline
CI tool	getsentry/action-release@v3 (GitHub Actions) or raw sentry-cli

When to Use

• Greenfield app instrumentation (browser, Node, Python, mobile).
• Adding releases + source maps to a CI/CD pipeline.
• Tuning alerts that are too noisy or too quiet.
• Setting up cron/scheduled-job health monitoring.
• Diagnosing an incident with replay + trace + profile correlation.

Prerequisites

• Sentry org and project created; DSN copied.
• SENTRY_AUTH_TOKEN (org-level internal integration token) exported in CI.
• SENTRY_ORG and SENTRY_PROJECT slugs exported.
• Build emits source maps (hidden, not served publicly).
• Release naming convention agreed (recommend ${SERVICE}@${GIT_SHA}).

Instructions

1. Initialize the SDK as early as possible. Browser (Vite/React example):

   // src/instrument.ts (imported FIRST in main.ts)
   import * as Sentry from "@sentry/react";
   
   Sentry.init({
     dsn: import.meta.env.VITE_SENTRY_DSN,
     environment: import.meta.env.MODE,
     release: import.meta.env.VITE_RELEASE,        // ${SERVICE}@${GIT_SHA}
     integrations: [
       Sentry.browserTracingIntegration(),
       Sentry.replayIntegration({ maskAllText: true, blockAllMedia: true }),
     ],
     tracesSampleRate: 0.1,
     replaysSessionSampleRate: 0.01,
     replaysOnErrorSampleRate: 1.0,
     sendDefaultPii: false,
     beforeSend(event) {
       if (event.request?.cookies) delete event.request.cookies;
       return event;
     },
   });
   

2. Backend (Node) — must be the very first import:

   // instrument.ts (preloaded via `node --import ./instrument.js`)
   import * as Sentry from "@sentry/node";
   import { nodeProfilingIntegration } from "@sentry/profiling-node";
   
   Sentry.init({
     dsn: process.env.SENTRY_DSN,
     environment: process.env.NODE_ENV,
     release: process.env.RELEASE,
     integrations: [nodeProfilingIntegration()],
     tracesSampleRate: 0.1,
     profilesSampleRate: 1.0,   // sampled on top of traces
   });
   

3. Wire releases into CI (GitHub Actions):

   - uses: getsentry/action-release@v3
     env:
       SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
       SENTRY_ORG: my-org
       SENTRY_PROJECT: web
     with:
       environment: production
       version: web@${{ github.sha }}
       sourcemaps: ./dist
       set_commits: auto
       finalize: true
   

4. Or, raw sentry-cli in any pipeline:

   RELEASE="web@$(git rev-parse HEAD)"
   sentry-cli releases new "$RELEASE"
   sentry-cli sourcemaps inject ./dist
   sentry-cli sourcemaps upload --release "$RELEASE" ./dist
   sentry-cli releases set-commits "$RELEASE" --auto
   sentry-cli releases finalize "$RELEASE"
   sentry-cli deploys new -r "$RELEASE" -e production
   

5. Verify symbolication: trigger a known throw on the deployed app; confirm the event in Sentry shows original file/line and that Debug ID matches.
6. Configure ownership via .sentry/codeowners (Sentry-format):

   # path-based
   path:apps/web/checkout/**   #payments-team
   path:apps/api/billing/**    #payments-team @alice
   url:https://example.com/admin/* #platform-team
   

7. Tune alerts with intent. Use Issue Alerts for new/regressed events, Metric Alerts for rates:
   • Issue Alert: "A new issue is created in production AND event count > 10 in 1h" → Slack #payments-oncall.
   • Metric Alert: "failure_rate() of transaction.op:http.server > 2% over 5 min" → PagerDuty.
   • Always set resolution thresholds so alerts auto-close.
8. Cron monitoring (replace dead-man switches):

   await Sentry.withMonitor("nightly-billing", async () => {
     await runNightlyBilling();
   }, { schedule: { type: "crontab", value: "0 3 * * *" }, checkinMargin: 5, maxRuntime: 30 });
   

9. Triage hygiene weekly:
   • Resolve, ignore-until-N-events, or merge duplicate issues.
   • Adjust fingerprinting only with a documented reason.
   • Convert recurring user-impact issues into engineering tickets with the Sentry issue link.
10. Privacy guardrails: keep sendDefaultPii: false, configure server-side data scrubbers for credit-card / token / email patterns, mask DOM in Replay, and document data flow for GDPR/CCPA review.

Common Pitfalls

Pitfall	Impact	Fix
Missing release on events	Regression detection broken; "new issue" badge unreliable	Set release in SDK init; finalize via CLI
Source maps uploaded but not matched	Stack traces stay minified	Use sentry-cli sourcemaps inject for Debug IDs
tracesSampleRate: 1.0 in production	Quota exhaustion, $$$ surprise	0.05–0.2; use tracesSampler for hot routes
Replay capturing PII	Privacy incident	maskAllText: true, blockAllMedia: true, custom block selectors
SDK init not the first import (Node)	OpenTelemetry instrumentations miss core modules	Use --import ./instrument.js
Issue alerts on every error	Alert fatigue; on-call ignores	Threshold by frequency + new/regression only
One production environment for all services	Cross-service noise; ownership unclear	Per-project Sentry projects + consistent env names
No cron monitor for scheduled jobs	Silent failures	Sentry.withMonitor with schedule + maxRuntime
SENTRY_AUTH_TOKEN with full org admin	High blast radius if leaked	Internal integration with project:releases + project:write only
Ignoring issues to silence noise	Real regressions hidden	Resolve with reason; create ticket; tune fingerprint instead
Releases not linked to commits	"Suspect commits" empty in UI	releases set-commits --auto requires repo integration

Output Format

Report to caller:

1. SDK initialization snippet(s) and where they were added.
2. Release identifier created, source-map upload result, finalize status.
3. Alert rules configured (name, scope, threshold, routing, resolution).
4. Ownership rules added (paths/URLs → teams).
5. Privacy controls in place (sendDefaultPii, scrubbers, replay masking).
6. Verification: a sample event link in Sentry showing symbolicated trace + replay + profile.

Authoritative References

• Sentry platform docs: https://docs.sentry.io/
• JavaScript SDK: https://docs.sentry.io/platforms/javascript/
• Source maps: https://docs.sentry.io/platforms/javascript/sourcemaps/
• Releases & health: https://docs.sentry.io/product/releases/
• Cron monitoring: https://docs.sentry.io/product/crons/
• Session Replay: https://docs.sentry.io/product/explore/session-replay/
• Issue ownership / codeowners: https://docs.sentry.io/product/issues/ownership-rules/
• Alerts: https://docs.sentry.io/product/alerts/
• sentry-cli: https://docs.sentry.io/cli/
• GitHub Action: https://github.com/getsentry/action-release