Releases and source maps
How Sypnia knows which version of your app a failure came from, how it says «since yesterday's change», and how source maps turn built code back into yours.
This page is for whoever deploys the app. Releases and source maps are part of the open-source engine and work the same on Sypnia Cloud. One part differs: on the Cloud, the Sypnia GitHub App can read what changed between two releases from your repository.
Two things make a problem useful instead of puzzling: knowing which change it started with, and seeing your own code in its stack instead of the built file. Releases give the first, source maps the second. Both are optional, and both take a few lines in your build.
Release
A release is one version of your app that you shipped. It is identified by a version string that your app sends with every event. Use the short git commit, such as 4f2a91c: it is unique, and it points at the code.
How a release comes to exist:
- By itself. The first time an event carries a version Sypnia has not seen in that project, the release is created. Its start is the time of that first event.
- From your build. Your build can register the release when it deploys, and add what the engine cannot know: when it went live, the commit, the version that came before, and what changed since then (the commits and the files they touched). A registered release starts at the time you give, or at the time you registered it, which is the time of the deploy.
Releases belong to a project and an environment, and are ordered by their start. Your frontend and your backend can send different versions; each event keeps its own.
What a release is used for
| Use | How |
|---|---|
| «Since yesterday’s change» | A problem remembers the release of its first occurrence. If the problem was never seen in the releases before it, that release is where it started. |
| What changed | The agent reads what you registered for the release: the commit messages and the names of the changed files, and their diffs only if your build chose to send them. On Sypnia Cloud with the GitHub App installed, what changed can also be read from GitHub. |
| Old tabs | Each occurrence shows its release, and a problem resolved with the fixing release is not reopened by failures from older ones. See Problems. |
| Filtering | Problems, sessions and performance numbers can be read for one release. |
| Source maps | Source maps are stored for a release. |
A backend that reports through OpenTelemetry sets its release with the standard service.version resource attribute. See OpenTelemetry.
If your app sends no version, everything still works. Problems then say when they started, and not which change started them.
Source maps
A build turns your code into something smaller. An error in production then points at the built file:
TypeError: Cannot read properties of undefined (reading 'toFixed')
at o (https://yourapp.com/assets/checkout-3f9c.js:1:48211)A source map is the file your build tool writes to translate that back. With the release’s source maps, Sypnia shows:
TypeError: Cannot read properties of undefined (reading 'toFixed')
at confirmPayment (src/checkout/checkout.tsx:142:18)The rules
- Upload them in your build, for a release. Source maps are stored with the project and the release’s version. The upload needs an API token with the
ciscope, which can register releases and upload source maps and nothing else. Keep it in your CI’s secrets. - Then remove them from what you publish. Source maps contain your source code. Sypnia never serves them to anyone: it only uses them to translate stacks. The CLI does both steps, and registers the release, in one command:
sypnia sourcemaps uploadwith--delete-after. See the CLI reference and the guide Source maps in CI. - Translation does not change grouping. A failure’s fingerprint is computed in the SDK from the built code, with build hashes removed, so a problem is the same problem before and after you upload source maps. Source maps change what you read, not what is grouped.
- Uploading late is fine. When the source maps of a release arrive after a failure, the problems of that release are translated then. If the agent already analysed the problem without them, ask for a new analysis: with source lines it has more to read.
- A line with no map stays as it is. Translation never fails a problem. It translates what it can.
Limits
| Limit | Value |
|---|---|
| Lines of a stack that are translated | The first 30 |
| Size of one source map | 64 MB. A larger one is refused, and its lines stay as built. |
| How long source maps are kept | 90 days after the release was last seen |
These come from the system Sypnia is extracted from, where one deploy uploads about a thousand source maps.
Engine and Cloud
| Sypnia engineOpen source, self-hosted | Sypnia CloudPaid service, with a free tier | |
|---|---|---|
| Releases, created by themselves or registered | Yes. | Yes. |
| Source maps and translated stacks | Yes. Source maps are stored in your own bucket. | Yes. Source maps are stored in Sypnia Cloud, private to your project. |
| What changed in a release | What your build registered. The agent cannot read your repository. | What your build registered, or what Sypnia reads from GitHub when the Sypnia GitHub App is installed. |
Example: yesterday’s change
The shop’s build runs on every deploy. After building, it registers the release and uploads its source maps. Yesterday at 18:40 it deployed commit 4f2a91c, registered as coming after 9c1e7b2, with the description «Rename cart.total to cart.totalCents».
This morning the first payment failed. The problem’s first occurrence carries release 4f2a91c, and the failure was never seen in 9c1e7b2 or before. So Sypnia can say more than «3 people could not pay»:
- Since when: yesterday’s change, deployed at 18:40. It worked before.
- Where:
src/checkout/checkout.tsx:142, inconfirmPayment(), thanks to the source maps. - Why: the release renamed
cart.total, and line 142 still reads it.
Without a release, the same problem would say «since today, 09:12». Without source maps, it would point at checkout-3f9c.js:1:48211.
Reference
Registering a release and uploading source maps: the API reference and the CLI reference. Setting the version in your app: Browser, Node and Next.js.