Bugsink 1.5: Introducing Sourcemaps

Bugsink 1.5 is out, and the headline feature is one people have been asking for the most: sourcemaps support.

Sourcemaps are files that map minified code back to the original source, so your debugger – or your error tracker – can show useful information instead of gibberish.

You can now get readable stack traces from minified frontend code—no more guessing what captureException.min.js:2:143 might actually mean.

If you’re shipping compressed JavaScript to users, Bugsink can now help you understand what went wrong, using the original code you actually wrote.

How to use it

Set up a token by clicking on “tokens” in the menu bar of your Bugsink installation (it’s available for superusers).

Then, make sure you have sentry-cli and a minified build using uglifyjs or something similar, and:

uglifyjs captureException.js -o captureException.min.js   --source-map url=captureException.min.js.map,includeSources
sentry-cli sourcemaps inject .
SENTRY_AUTH_TOKEN=yourtokengoeshere sentry-cli --url https://yourbugsinkinstance/ sourcemaps --org bugsinkhasnoorgs --project=ignoredfornow upload .

That’s it. No need to configure releases. No need to tie artifacts to project metadata.

How it works

This implementation uses the “artifact bundle” upload format from sentry-cli, based on debug IDs. These are unique identifiers embedded into your minified code and sourcemaps during upload. It means mapping the two together is trivial – and it skips the entire releases setup.

In the example above, the inject subcommand of sentry-cli is used to add the debug IDs to the minified code. Here’s the background on the introduction of this format:

• Sentry’s announcement of this format
• The proposal to add debug ids to the sourcemaps standard

To be compatible with the sentry-cli, Bugsink implements three API endpoints that are used to upload the files. The --url parameter in the command line above points to your Bugsink instance, and the --project parameter is ignored:

• GET upload-chunk: tells the CLI what we support
• POST upload-chunk: receives the zipped-up files
• POST assemble: unpacks them and stores them

It may turn out that we need to add more endpoints later, but for now, this is all we need.

What’s not in 1.5

Bugsink tries to be API-compatible with Sentry, but we don’t try to match every feature one for one. This is a conscious decision to keep the codebase clean and maintainable.

Here are some things that are not in 1.5.

No release or project linkage

The 1.5 doesn’t require you to set up releases or link artifacts to specific projects, and in fact, it can’t do that.

Because we use the artifact bundle upload format, we rely on debug IDs to match files to their original source. This is expected to be a mechanism that leads to the minimal number of surprises and the most reliable results. In particular: any kinds of guessing or matching based on filenames or paths is avoided.

That makes the usual release machinery unnecessary. You don’t need to upload a release version or tie it to a deploy. Bugsink can resolve stack traces without any of that.

And, because the 1.5 release is the absolutely minimal implementation of sourcemaps, it doesn’t actually support releases or projects at all. The --project parameter is ignored, and the --release parameter is not supported.

I might still add optional release linkage later if it turns out to help with UX – e.g. to browse uploaded artifacts by release. But from a technical standpoint, it’s not needed, and it’s not planned until there’s a concrete benefit.

Bundler support: unknown

The only mechanism of uploading sourcemaps that’s been tested is the plain sentry-cli command line tool. This is a general-purpose tool that works with any JavaScript build system. It’s not tied to any specific framework or bundler.

The reason I picked this approach is that it’s the straightforward and explicit mechanism, and I’d like to work my way through this particular pile of problems from the most obvious and simple to the most complex.

And because you can fall back to it from any other tool, it means you can always use it if you need to.

This is not to say that specific bundlers or frameworks won’t work. It’s just that I haven’t tested them yet. If they happen to (just) use the API endpoints mentioned above, they’ll work just fine.

If you’re using one of these tools and it doesn’t work with the current setup, let me know. I’m happy to add support, but I’d rather do it based on working examples than guess at what might be required. Bonus points if you can tell me what endpoints your tool of choice uses, and with what kind of data.

Deeper testing

So far, I’ve only tested against uglifyjs and sentry-cli. I haven’t tested against any other minifiers or bundlers.

I’m very happy to hear from you if you have a different setup that works. I’m also happy to help you debug any issues you run into. In that case, please include

• The full CLI error message from sentry-cli
• The URL of the failing request (run sentry-cli with --loglevel=debug)
• (Optional but useful) The request payload – you can collect this by running through a local proxy or adding temporary logging

Even if it’s not fully reproducible, having that kind of information helps a lot when figuring out what’s missing or behaves differently.

• Share minimal repros or working samples via event-samples.
• Let me know which workflows or builder plugins depend on other endpoints.

Further Features & Fixes for 1.5

Sourcemaps support isn’t all that was added in 1.5. Here are some other features and fixes:

• Add EMAIL_USE_SSL to settings/templates.
• Print full stacktraces when not dogfooding (i.e. no sentry-sdk config).
• Various Dockerfile improvements (see #68).
• Allow users to join their own team’s projects (#56).
• Don’t crash on non-str tag-values (#76).
• Add user.id, user.username, user.email, and user.ip_address tags in deduce_tags.

Upgrading to Bugsink 1.5

Bugsink 1.5 is available now. Give it a try and let us know how it works for you!

See the full changelog on GitHub.

Upgrade now or install Bugsink for the first time.