JavaScript applications very commonly ship their code in an "uglified" form which makes it easier to deploy and load in users browsers around the world. This problem is something that many across the JS ecosystem have been working on for many years around the globe. This is great for loading your web content builing your websites and having them be delivered to end users faster. However, this create un-readable obfuscated code. This is what we get in stack traces from the browser which are Sentry to generate our issues. This presents a number of problems
Simply un-readable
a. users can't read it and try to immediately grok the problem
Cannot link to original/source code
a. Sentry provides the ability to point to the exact line(s) of code where the error occured
Grouping is not as effective
a. without de-obfuscated tack traces we lose orignal source context which could help group more accurately
Historically Sentry has been progressively providing more and more tools to help JS developers upload their source maps with each release, and trying to provide them ways to have this upload be a default step included in their CI/CD. As well as means to help them find out why it is NOT working. Here is where we run into the real complexity. A blank slate new projects is always the simplest, we can make a lot of assumption, but with any existing project we can't assume much of anything.
So this work aims to have a holistic approach to helping users fix their source maps upload configuration, by capturing all the correct data from issues (stack traces, stack frames), symbolication (resolution method), and project settings (uploaded files). We aim to have a one stop solution to help users who want help get the help they need.
👩💻 User Stories
There are 4 primary users situations/states we want to address (not to be confused with personas)
Uploaded source maps and everything is work perfectly fine (fine enough)
Uploaded source maps but there are issues with stack traces or even individula stack frame which are not resolved correctly
Never Uploaded source maps ever and stack trace resolution never works
Never uploaded source maps and do not have any "uglified" code ie do not need source maps
As a developer,I want Sentry to guide me on what I should do to get my uglified code resolved,
So that my stack traces are readable
and can get a reliable link to my source code
and my issue grouping is more accurate.
As a developer,I want Sentry to provide me with enough context and expertise that if there are stack frames which are not resolved I am not alerted to fix a problem which is not really relevant
So that I do not get false alerts
and spend time fixing problems which are not there
As a developer,I want Sentry to show me issues when I am modifying code locally
So that i can debug and detect issues before mering
Given that local changes may not have builds with representative source map files
and they are not uploaded
I expect sentry to inform why most likely the stack trace(frames) are not resolved
How do we think about rollout and the priority of putting this in front of users?
In this ticket our thinking on which mediums will reach the most users and how is elaborated upon. The issues details page was called out then as the biggest potential lever. It remains that way today. But with caveats.
Adding to issue details page, is the least control as could be to all users who fit our requirements, which is a lot.
least control in terms of SDK version, SDK version (<7.), that the user is actually already in their dev env with terminal etc
Invites risks that we don't have the best version of the wizard as a CTA for their first impression
would rather not have a CTA [which] later that says hey please try again we did better this round
This is potentially our biggest lever, let's collect more usage and improve before wasting our shot
The approach we are taking now is a subtle one, with the philosophy that if users have something wrong it will be possible that we provide them with the information and means to resolve. But we do not pester them or lead them to believe that something is "wrong". Adding anything will lead to more adoption, we know this. We can be gently about it and measure improvements. We do not need to drive an imperative to our users that they must do this with big alerts and banners.
When should we alert users?
Honestly, never. We provide something like a pill on individual stack frames which is un-alarming, and will lead them if clicked to get help with improving their Sentry experience.
How will we roll this out?
Feature flags 🎏 and konami codes 🎮
this functionality will be controlled by a feature flag
i. validate on sentry first
ii. identify single digit sets of orgs that fit scraping, release, and debugids turn it on for them
a. we will manually validate on these projects
iii. adding larger swaths of orgs based on the ideal SDK type and version
Konami code - a kind of cheat code for support to activate this for their admin user while in any org
i. allows support to validate the feature on any org and project
ii. and of course ideally already start helping users faster
Can we detect projects which never uploaded source maps and NEED source maps?
This comes up with regards to a seemingly simple opportunity space. For the vast majority of time of Sentry setting up source maps uploads was not a simple part of the onboarding. Now it is with the wizard. So for every project in the wild can we put a CTA, or some banner, with the wizard one liner snippet, and tell orgs to take it for a spin to set up the upload process.
The catch is that while we might be able to detect they have no source maps uploaded, we can't easily detect that they do in fact have some kind of "uglified" code without heuristics. I have no reason to believe that during processing we can develop a simple heuristic which can state, "this event does or does not need source maps". Therefor to avoid any risk for now, I would simply remove it from scope. And focus on a more holistic non-alarming solution.
If we can develop a way to solve that problem later we will. But it is not our first focus.
How do we measure success?
Source maps adoption across JS projects is a massive space. There are many many orgs, projects, and varied setups with varied interested and needs. We have some hard numbers on resolving of stack traces, generally we want this to go up, and we have some indication of % issues viewed with source maps (we want that to go up too), we also have telemetry on the source maps wizard and our bundler plugins, We want them all to naturally go up. But not by any forcing factor.
We will also add some telemetry to check the interaction with the stack frame pills and the modal, but this is not to be thought of as a funnel to uploading source maps, since tools available are not suited to the job, and not the way I would measure success.
Why do source maps matter?
Source maps matter for all the reasons stated before. But I do not want to over rotate on pushing customers down a funnel to setting them up, we will continue to improve and thoughtfully put solutions in front our users. Every click they make is a valuable one. And I want to ensure that the clicks we propose them to make we are confident will provide them with reasonable success ratio.
This is one of the largest topics for support, we lose a ton of cycles supporting users, Recent efforts with the wizard seem to be showing some improvements. But we want to make even more unlikely that Sentry users need to contact our support, and if they do that our support also has the tools needed to help the user,
Project board
See our project board to track this initiative
Description
JavaScript applications very commonly ship their code in an "uglified" form which makes it easier to deploy and load in users browsers around the world. This problem is something that many across the JS ecosystem have been working on for many years around the globe. This is great for loading your web content builing your websites and having them be delivered to end users faster. However, this create un-readable obfuscated code. This is what we get in stack traces from the browser which are Sentry to generate our issues. This presents a number of problems
Historically Sentry has been progressively providing more and more tools to help JS developers upload their source maps with each release, and trying to provide them ways to have this upload be a default step included in their CI/CD. As well as means to help them find out why it is NOT working. Here is where we run into the real complexity. A blank slate new projects is always the simplest, we can make a lot of assumption, but with any existing project we can't assume much of anything.
So this work aims to have a holistic approach to helping users fix their source maps upload configuration, by capturing all the correct data from issues (stack traces, stack frames), symbolication (resolution method), and project settings (uploaded files). We aim to have a one stop solution to help users who want help get the help they need.
👩💻 User Stories
There are 4 primary users situations/states we want to address (not to be confused with personas)
As a developer, I want Sentry to guide me on what I should do to get my uglified code resolved, So that my stack traces are readable and can get a reliable link to my source code and my issue grouping is more accurate.
As a developer, I want Sentry to provide me with enough context and expertise that if there are stack frames which are not resolved I am not alerted to fix a problem which is not really relevant So that I do not get false alerts and spend time fixing problems which are not there
As a developer, I want Sentry to show me issues when I am modifying code locally So that i can debug and detect issues before mering Given that local changes may not have builds with representative source map files and they are not uploaded I expect sentry to inform why most likely the stack trace(frames) are not resolved
RFC
N/A
https://www.notion.so/Source-Maps-Debugger-POC-a98a0906869e48079d974643e7776398
Tasklist
Steps to take for implementation:
FAQ
How do we think about rollout and the priority of putting this in front of users?
In this ticket our thinking on which mediums will reach the most users and how is elaborated upon. The issues details page was called out then as the biggest potential lever. It remains that way today. But with caveats.
The approach we are taking now is a subtle one, with the philosophy that if users have something wrong it will be possible that we provide them with the information and means to resolve. But we do not pester them or lead them to believe that something is "wrong". Adding anything will lead to more adoption, we know this. We can be gently about it and measure improvements. We do not need to drive an imperative to our users that they must do this with big alerts and banners.
When should we alert users?
Honestly, never. We provide something like a pill on individual stack frames which is un-alarming, and will lead them if clicked to get help with improving their Sentry experience.
How will we roll this out?
Feature flags 🎏 and konami codes 🎮
Can we detect projects which never uploaded source maps and NEED source maps?
This comes up with regards to a seemingly simple opportunity space. For the vast majority of time of Sentry setting up source maps uploads was not a simple part of the onboarding. Now it is with the wizard. So for every project in the wild can we put a CTA, or some banner, with the wizard one liner snippet, and tell orgs to take it for a spin to set up the upload process.
The catch is that while we might be able to detect they have no source maps uploaded, we can't easily detect that they do in fact have some kind of "uglified" code without heuristics. I have no reason to believe that during processing we can develop a simple heuristic which can state, "this event does or does not need source maps". Therefor to avoid any risk for now, I would simply remove it from scope. And focus on a more holistic non-alarming solution.
If we can develop a way to solve that problem later we will. But it is not our first focus.
How do we measure success?
Source maps adoption across JS projects is a massive space. There are many many orgs, projects, and varied setups with varied interested and needs. We have some hard numbers on resolving of stack traces, generally we want this to go up, and we have some indication of % issues viewed with source maps (we want that to go up too), we also have telemetry on the source maps wizard and our bundler plugins, We want them all to naturally go up. But not by any forcing factor.
We will also add some telemetry to check the interaction with the stack frame pills and the modal, but this is not to be thought of as a funnel to uploading source maps, since tools available are not suited to the job, and not the way I would measure success.
Why do source maps matter?
Source maps matter for all the reasons stated before. But I do not want to over rotate on pushing customers down a funnel to setting them up, we will continue to improve and thoughtfully put solutions in front our users. Every click they make is a valuable one. And I want to ensure that the clicks we propose them to make we are confident will provide them with reasonable success ratio.
This is one of the largest topics for support, we lose a ton of cycles supporting users, Recent efforts with the wizard seem to be showing some improvements. But we want to make even more unlikely that Sentry users need to contact our support, and if they do that our support also has the tools needed to help the user,