sentry-observability

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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):
   ```ts
   // 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:
   ```ts
   // 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):
   ```yaml
   - 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**:
   ```bash
   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):
   ```ts
   await Sentry.withMonitor("nightly-billing", async () => {
     await runNightlyBilling();
   }, { schedule: { type: "crontab", value: "0 3 * * *" }, checkinMargin: 5, maxRuntime: 30 });
   ```

From SwapnilPopat/ai-assistant-skills, MIT.

More from SwapnilPopat/ai-assistant-skills