Releases and source maps

Name releases, upload source maps for readable browser stacks and record deploys.

A release is a version of your code. Telemetry joins a release through the release option of the SDK, OPENPERF_RELEASE on servers, or the service.version resource attribute in OpenTelemetry. Use the same string everywhere: the SDK, the CLI and your build, such as a version number or a commit SHA.

A release appears under Releases once it is created with the CLI. One release can span several projects of the organization.

The CLI

The openperf CLI comes with @openperf/sdk and needs Node.js 22.15 or later.

It needs an API token. Owners and admins create one under Settings → API → New token. The token is shown once, never expires and acts as the organization with full access to every project, so keep it in your CI secrets and revoke it when it’s no longer used.

Flag	Variable	Value
`--url`	`OPENPERF_URL`	The OpenPerf API, such as `https://api.example.com`.
`--token`	`OPENPERF_AUTH_TOKEN`	The API token, `opt_…`.
`--project`	`OPENPERF_PROJECT`	The project ID: the last part of the project’s settings URL.
`--release`	`OPENPERF_RELEASE`	The release version.

Every command needs all four. A flag wins over its variable.

Create a release

npx openperf releases create --ref "$GITHUB_SHA"

This creates the release, or adds the project to an existing one. Running it again is safe: the release.created webhook is sent only when the project first joins. --ref is the commit the release was built from. With the GitHub integration and a code mapping for the project (Settings → Integrations), the release lists its commits since the previous release.

Upload source maps

Browser stacks point into minified bundles. With source maps uploaded for the release, OpenPerf maps them back to your source before grouping errors.

Build with source maps on.
Upload the build output after each build:

npx openperf sourcemaps upload ./dist

The CLI uploads every .map file in the directory and its subfolders, in batches of up to 500 files. Uploading a file again for the same release replaces it.

Each map is matched to the script URL in the stack by its path inside the directory. With the default prefix ~/, dist/assets/app.js.map serves https://<any host>/assets/app.js. When the files are served from elsewhere, pass --url-prefix:

Scripts are served from	`--url-prefix`
`https://app.example.com/assets/app.js`	`~/` (default)
`https://app.example.com/static/assets/app.js`	`~/static/`
`https://cdn.example.com/assets/app.js`, only from that host	`https://cdn.example.com/`

Stacks are mapped when an error arrives, so upload before the release takes traffic. Only errors with the same release and project as the upload are mapped. Source maps apply to browser stacks only.

On a self-hosted server, uploads need object storage.

Record a deploy

A deploy says a release reached an environment. It shows on the release page and sends the release.deployed webhook. Record it with the API token after the release is created:

RELEASE_ID=$(curl -fsS -H "Authorization: Bearer $OPENPERF_AUTH_TOKEN" \
  "https://api.example.com/api/v1/releases/lookup?projectId=$OPENPERF_PROJECT&version=$OPENPERF_RELEASE" \
  | jq -r .id)

curl -fsS -X POST "https://api.example.com/api/v1/releases/$RELEASE_ID/deploys" \
  -H "Authorization: Bearer $OPENPERF_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"environment": "production"}'

Field	Description
`environment`	Required. Up to 100 characters.
`projectIds`	The projects deployed. Every project of the release when omitted.
`name`	A label, such as a pipeline run.
`url`	A link to the deploy, `http` or `https`.
`startedAt`	ISO 8601 time. Must not be after `finishedAt`.
`finishedAt`	ISO 8601 time. Now when omitted.

Copy release ID in the release’s menu gives the same ID by hand.

Release health

Each release shows its errors per 1,000 transactions, failure rate, new errors, adoption over the first 48 hours, commits and deploys, compared with the previous release. Its status:

Status	When
Pending	Fewer than 100 transactions so far.
Healthy	No new errors, and no growth below.
Degraded	New errors, or the failure rate or errors per 1,000 transactions grew to 1.2 times the previous release.
Regressed	The failure rate or errors per 1,000 transactions grew to 1.5 times the previous release.

Growth counts only when the failure rate rises by at least 0.5 percentage points, or errors by at least 1 per 1,000 transactions.

Delete release removes the release and its deploys. Its telemetry is kept.