Skip to main content

Release Health and Crash Monitoring: Track Deployments

A release is a deployed version of your app. Release health monitoring tracks the error and crash rates of each release, letting you detect regressions immediately after deployment. If version 1.2.0 has a 5% crash rate while version 1.1.0 had 0.2%, something is wrong with the new release. Without release tracking, you rely on user complaints to discover these issues—potentially losing revenue before you notice.

Setting Up Release Tracking in Sentry​

To track releases, you must tag errors with a version number. Initialize Sentry with your release version:

import * as Sentry from "@sentry/react";
import packageJson from "../package.json";

Sentry.init({
  dsn: process.env.REACT_APP_SENTRY_DSN,
  release: `react-app@${packageJson.version}`, // e.g., "[email protected]"
  environment: process.env.REACT_APP_ENVIRONMENT,
  tracesSampleRate: 0.1,
});

Alternatively, inject the version at build time using environment variables:

# In your CI/CD script
export REACT_APP_VERSION=$(git rev-parse --short HEAD) # or use git tags
npm run build

Then in your React app:

Sentry.init({
  release: `react-app@${process.env.REACT_APP_VERSION}`,
  // ...
});

Now every error event includes the release version. Sentry groups errors by release, allowing you to see which versions have the most problems.

Understanding Release Health Metrics​

Release health includes four key metrics:

  1. Session count: Total user sessions in this release.
  2. Crash-free rate: Percentage of sessions with no errors (100% = no crashes).
  3. Error count: Total number of errors.
  4. Session duration: Average session length.

A typical release health dashboard shows:

Release: v1.2.3
Status: Healthy

Crash-free rate:        99.5%  (was 99.8% in v1.2.2)
Sessions:               45,000
Errors:                 225
Average session:        4m 23s

If crash-free drops below a threshold (e.g., 95%), it signals a regression. In the Sentry dashboard, go to Release & Health > Releases to see all releases and their health scores.

Tracking User Sessions for Health Metrics​

Sentry automatically creates a session for each user when the app loads. However, you can customize session tracking:

import * as Sentry from "@sentry/react";

Sentry.init({
  dsn: process.env.REACT_APP_SENTRY_DSN,
  release: `react-app@${packageJson.version}`,
  integrations: [
    new Sentry.SessionTiming(), // Track session duration
  ],
});

// Manually start a session
Sentry.startSession();

// Set user context for session grouping
Sentry.setUser({
  id: "user-123",
  username: "john_doe",
  email: "[email protected]",
});

// When user logs out, end the session
Sentry.endSession();

Sessions are aggregated per release. If v1.2.3 has 50,000 sessions and 225 errors, the crash-free rate is (50,000 - 225) / 50,000 = 99.55%.

Setting Up Health Thresholds and Alerts​

You can create alerts that fire if release health metrics fall below thresholds. In Sentry, go to Alerts > Create Alert Rule:

Alert condition:
  For the "Release" environment
  When release health crashes below 95%
  Send notification to: Slack #oncall

This alert fires if crash-free rate drops below 95%, signaling a potential regression. Set thresholds based on your app's SLA:

  • Critical: crash-free < 90% (severe regression)
  • Warning: crash-free < 95% (noticeable regression)
  • Info: new version deployed (informational)

Comparing Releases to Detect Regressions​

In the Sentry dashboard, click Release & Health > Releases and select a release to see its health score. To compare two releases:

  1. Open release v1.2.3.
  2. Scroll to Error events compared to previous release.
  3. Sentry shows a diff: "123 new errors in this release vs. 85 in v1.2.2."

This immediately highlights regressions. If a new release introduces 50% more errors, you have a problem. Click on the new errors to investigate:

New errors in v1.2.3:
  1. TypeError: Cannot read property items of undefined (2,345 occurrences)
  2. ReferenceError: refresh is not defined (1,203 occurrences)
  3. Network error: Failed to fetch /api/user (892 occurrences)

Often, one dominant error is causing the regression. Fix it and deploy a hotfix release.

Rolling Back a Bad Release​

If a release has a crash rate above 99%, roll back immediately. In your deployment system (Vercel, Netlify, AWS):

# Example: Rollback on Vercel
vercel rollback

Then in Sentry, mark the release as archived so it is no longer tracked:

sentry-cli releases delete v1.2.3

Or, in the Sentry UI, go to Release & Health > Releases, click the release, and select Archive.

Example: Detecting and Fixing a Regression​

Scenario: You deploy v1.2.3 and within 5 minutes, the crash-free rate drops from 99.8% to 95.2%.

  1. Alert fires: Slack notification warns of regression.

  2. Check release health: Open Sentry and see v1.2.3 has 2,340 errors vs. 150 in v1.2.2.

  3. Identify the dominant error: TypeError in checkout component (1,203 occurrences).

  4. Review the diff: Check GitHub for what changed in checkout.jsx:

    - const { items } = cart || [];
    + const items = cart.items; // BUG: no null check

  5. Fix the bug: Revert the change or add null checking:

    const items = cart?.items || [];

  6. Deploy v1.2.4: New release goes out.

  7. Monitor health: Within 2 minutes, crash-free climbs back to 99.7%.

  8. Mark v1.2.3 as archived: Remove it from active tracking.

Without release health monitoring, you would learn about the regression from Twitter (user complaints). With it, you detect and fix it in minutes.

Performance Metrics in Release Health​

Beyond crash rate, Sentry also tracks performance metrics per release:

  • Web Vitals: Core Web Vitals (LCP, INP, CLS) grouped by release.
  • Transaction duration: How long pages take to load.
  • Apdex score: Application Performance Index (0–1, higher is better).
Sentry.init({
  release: `react-app@${packageJson.version}`,
  integrations: [
    new Sentry.BrowserTracing({
      routingInstrumentation: Sentry.reactRouterV6Instrumentation(
        window.history
      ),
    }),
  ],
  tracesSampleRate: 0.1,
});

// Track custom performance spans
const transaction = Sentry.startTransaction({
  op: "http.request",
  name: "Fetch user data",
});

const span = transaction.startChild({
  op: "db.query",
  description: "SELECT * FROM users",
});

// ... do work ...

span.finish();
transaction.finish();

Track performance alongside error rate. A release might have low errors but high page load times, which is also a regression worth investigating.

Key Takeaways​

  • Release health monitoring tracks crash rates and errors per deployed version.
  • Tag errors with a release version in Sentry.init so Sentry can group metrics by version.
  • Set health alert thresholds (crash-free < 95%) to catch regressions within minutes of deployment.
  • Compare releases to identify which errors are new and which are regressions.
  • Combine crash rates with performance metrics (Web Vitals, page load time) for complete health visibility.

Frequently Asked Questions​

How long should I wait after deploying to assess health?​

Most regressions appear within 5–15 minutes of deployment. Set alert thresholds generously at first (95% crash-free) and tighten them over time based on your traffic and error patterns.

Can I mark a release as healthy manually?​

Yes, in the Sentry UI. Go to Release & Health > Releases, click the release, and select Mark as Resolved or Mark as Healthy. This is useful for false alarms or known issues you are tracking.

What if a new release has legitimate new features that initially increase error rates?​

You can disable alerts for the first 30 minutes after deployment with the disableAlerts flag, or set a conservative threshold that only fires for severe regressions (crash-free < 90%).

How do I track releases for mobile apps or SDKs?​

The same approach applies. Tag events with the release version and track health per version. Mobile apps can detect version updates via app store metadata.

Can I track health across multiple environments (staging, production)?​

Yes. Use the environment field to segment metrics:

Sentry.init({
  release: `react-app@${packageJson.version}`,
  environment: "production", // or "staging"
});

Then in Sentry, filter by environment to see health metrics per stage.

Further Reading​