Docs

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.

Applies to EngineCloud At launch

View as Markdown
On this page
  1. Release
  2. What a release is used for
  3. Source maps
  4. The rules
  5. Limits
  6. Engine and Cloud
  7. Example: yesterday’s change
  8. Reference

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

UseHow
«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 changedThe 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 tabsEach occurrence shows its release, and a problem resolved with the fixing release is not reopened by failures from older ones. See Problems.
FilteringProblems, sessions and performance numbers can be read for one release.
Source mapsSource 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:

Text
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:

Text
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 ci scope, 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 upload with --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

LimitValue
Lines of a stack that are translatedThe first 30
Size of one source map64 MB. A larger one is refused, and its lines stay as built.
How long source maps are kept90 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

The Sypnia engine and Sypnia Cloud compared
Sypnia engineOpen source, self-hostedSypnia CloudPaid service, with a free tier
Releases, created by themselves or registeredYes.Yes.
Source maps and translated stacksYes. Source maps are stored in your own bucket.Yes. Source maps are stored in Sypnia Cloud, private to your project.
What changed in a releaseWhat 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, in confirmPayment(), 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.

Sections

Start hereWhat Sypnia is, how it works, what is open source and what is the paid cloud, and the two ways to get your first problem in plain words.ConceptsThe ten ideas Sypnia is made of, each defined precisely, from a project and its keys to problems, traces and alerts.SDKsHow your app sends data to Sypnia. One SDK for the browser, one for Node, one for Next.js, and the OpenTelemetry intake for every other backend.The agentHow Sypnia analyses a problem, what it writes, what it sends to a model and what it never does.MCP and skillsConnect your coding agent to Sypnia so it can ask what is failing in production, read what it needs to fix it, and set Sypnia up for you.API referenceThe Sypnia HTTP API: one API for the open-source engine and for Sypnia Cloud, with every endpoint, parameter, response and error.CLI referenceThe sypnia command: how to install it, the variables it reads, what its exit codes mean, and where each command is documented.Self-hostingWhat you run when you host the Sypnia engine yourself, what you need, what it costs, and what you do not get compared with Sypnia Cloud.How the engine is builtThe whole Sypnia engine on one page, from a click in your app to the sentence your coding agent reads, with the design rules and the code that holds them.Sypnia CloudHow the paid service works, from organizations and roles to plans, limits, billing, where your data lives, the GitHub App and support.Privacy and securityWhat Sypnia collects from your app and its users, what it never collects, how masking works, how to delete data, and how the service is protected.LicensingWhich licence covers each part of Sypnia, what you may do with it, how the name may be used, and the terms of a contribution.GuidesStep-by-step recipes for the common ways to use Sypnia, from apps made with AI builders and Next.js on Vercel to Supabase, source maps in CI, alert e-mails from your own engine, and moving from Sentry.ReferenceThe pages you look things up in, from the event schema and the glossary to what is planned, the changelog and the common questions.
↑↓ to move↵ to openEsc to close