Releases

The Releases tab lets you see what version of your application introduced a specific error. This is crucial for understanding when bugs were introduced and for quickly identifying the impact of new deployments.

How a release gets created

• Every event your SDK sends carries its release version. When Better Stack sees a version it doesn't know yet, it creates the release automatically. This needs no setup, though the release only appears once the first error from that version arrives.
• You can also report a release from your build. It then appears as soon as it ships rather than waiting for an error, and it can record the environment it was deployed to.
• Releases are identified by a version number or reference (e.g., "v1.2.3").
• Each release tracks when it was first and last seen.
• Errors are automatically associated with the release in which they occurred.

Report a release during your build

Better Stack accepts release reports through its Releases API, the Sentry CLI, and the Sentry bundler plugins.

curl --request POST \
  --url https://errors.betterstack.com/api/v1/releases \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data "{\"version\": \"$VERSION\", \"applications\": [\"$APPLICATION_ID\"], \"environment\": \"production\"}"

sentry-cli releases new "$VERSION"
sentry-cli releases deploys "$VERSION" new --env production

sentryVitePlugin({
  org: $SENTRY_ORG,
  project: $SENTRY_PROJECT,
  url: $SENTRY_URL,
  authToken: process.env.BETTER_STACK_API_TOKEN,
  release: {
    name: process.env.GIT_COMMIT_SHA,
    deploy: { env: 'production' },
  },
})

For the Sentry CLI and the bundler plugins, set these from Errors -> Applications -> your application -> Advanced settings, the same values you use for source maps:

• SENTRY_ORG - a Better Stack ID representing your team.
• SENTRY_PROJECT - the Better Stack ID for your application.
• SENTRY_URL - the Better Stack endpoint, for example https://us-east-9-sourcemaps.betterstackdata.com.
• SENTRY_AUTH_TOKEN - a Telemetry API token.

The cURL request authenticates with a Telemetry API token and names the application the release belongs to. When applications is omitted, the request only attaches the environment to applications already reporting that version, so a new release needs it. A release registered by mistake can be removed via the API.

Exploring releases

• View a paginated list of all releases in Errors -> Releases.
• Filter releases by date range for historical analysis.
• Click a release to see its detail page, which includes:
  • An error frequency histogram for that specific release.
  • A list of all exceptions that occurred in that release.
  • Environment information showing where that release ran.
• Navigate back to the main errors list, filtered for a specific release.
• See breadcrumbs showing the release context within error details.

Release markers on dashboards

When a dashboard chart is built from a source that an Errors application is correlated with, that application's releases appear as vertical dashed lines on the chart. Use them to see whether a change in your metrics lines up with a deployment.

• Markers show on line and bar timeseries charts, both on dashboards and on the single-chart view.
• They appear automatically once the correlation exists, with nothing to configure.
• Hover a marker to see a card with the release reference, application, and time. When the marker is a single release, its label links to the release detail page.
• When several releases fall close together, their labels group into a single label such as "3 releases" and split apart as you zoom in.
• Markers are visible only to members with access to Errors, and never appear on shared or public dashboards.