[EPIC] Simplify the SDK Setup flow for errors, sourcemaps and tracing

[danielkhan]

Problem

Depending on the platform, setting up the Sentry SDK can be complicated. We identified a set of friction points that we wanted to fix. This Epic is a tracking issue for this large initiative to improve our setup UX.

A novice developer should be able to set up Sentry (at least errors, sourcemaps for JS, and tracing) in 5 minutes.

User Stories

• As a developer, I want Sentry to give me linear step-by-step instructions on instrumenting my code.
• As a developer, I want the code changes to be short and limited (Express requires 50 LOC today).
• As a developer using JavaScript, I want Sentry to present me with either a wizard or clear, unambiguous instructions on uploading sourcemaps to Sentry.
• As a developer, I want additional, complete documentation or a wizard that helps me integrate the source map upload into my CI/CD process.
• As a developer, I don't want to create an auth token to upload source maps manually.
• As a developer, I want to use a single DSN for all my projects.
• As a developer, I want to be able to find additional platform-specific documentation that is 100% consistent with the onboarding instructions.
• As a developer, I want all links in my setup flow to open in a new tab so I am not kicked out of the process.
• As Sentry, we want to fulfill these user stories in SaaS and single-tenant or self-hosted deployments.
• As Sentry, we want to create the necessary processes to meet these quality criteria for all existing and new platforms.

Definition of done

• User testing and telemetry show that the setup process is finished within 5 minutes in 90% of cases and ends with errors, tracing, and sourcemaps configured.
• The setup instructions fit on one page.
• We have validated all code snippets and ensured that we made them as simple as possible.
• It is no longer necessary to manually create an auth token to upload source maps.
• Our documentation contains instructions to automate source map upload with all major CI/CD tools.
• They open in a new tab if we have to link to additional information within the setup process.
• We no longer require a DSN per project.
• The documentation should be 100% consistent with what we present in the setup process.
• Setup flows for the first project (new users), and all additional projects are consistent and ideally the same.
• All of the above works for all deployment modes for Sentry.
• We have a checklist that ensures all criteria are met for a new SDK.

FAQ

Why must the users have source maps in CI/CD?

Sentry is a tool meant for production monitoring. It's cool if a developer is able to test the setup on his machine and this is the first step - but it's irrelevant if the setup is not working in production. A company usually uses some CI/CD setup so the process has to work end-to-end there. If it's a smaller company and things get directly deployed from the developers machine, well then it should work right away.

How short should the setup guide be?

As short as possible - the initial instructions should contain all steps required for the most common use case of the given platform. The steps must contain everything to get all the value out of Sentry - Install -> Simple Usage for Errors & Custom instrumentation -> Enable key features like Replays & Profiling if available. Following these steps, the user has to be able to understand and see how Sentry provides immediate value.

Why a new auth token?

Our current system requires the user to leave the setup page and find the spot where to create an Auth Token required for the setup. Goal should be that the user never has to leave the same page until they fully configured Sentry. We need a new system to enable that.

Why do we start with the cli wizard setup first?

The CLI Wizard takes a lot of the chores away of the user for example: Finding the Org/project -> copy pasting DSN, creating an Auth Token, putting everything in the config files/init. In the ideal case, the user when setting up Sentry in their platform, never has to read and documentation and the CLI wizard when setting up does all the steps. It will happen that the Wizard is not able to fulfill every step because the setup is so different - if that is the case the wizard should clearly guide the user to the dedicated docs or provide the snippets to manually add, directly to the user.

SDK Setup Improvements

Beta Give feedback

1. Node.js and it's frameworks should be instrumented with minimal config sentry-javascript#8378
   Type: Improvement +1
2. react-native adds wrap during setup sentry-wizard#280
   Platform: React-Native Status: Stale enhancement +3
3. RN: Guide user on How to patch App.js if file not found sentry-wizard#226
   Platform: React-Native Status: Stale +2
4. Make Web React Sentry.withProfiler more prominent sentry-docs#7240
   Platform: JavaScript Team: Web Frontend SDKs Type: Content +3
5. Make React Native Sentry.withProfiler more prominent sentry-docs#7092
   Effort: Small Impact: Medium Platform: React-Native Team: Mobile Platform Type: Content +5

Source maps (sentry in CI)

Beta Give feedback

1. Design: Include wizard one liner in JS onboarding sentry#52068
   1 of 1
   +0
   
2. Add sourcemaps wizard instructions to uploading source maps docs sentry-docs#7304
   +0
   
3. Add source maps wizard instructions to Getting Started pages sentry-docs#7306
   +0
   
4. Add telemetry to sourcemaps wizard sentry-wizard#296
   +0
   
5. Project: Org Auth Tokens team-sdks#6
   49 of 54
   Team: Web Frontend +1
   
6. https://github.com/getsentry/team-processing/issues/69
7. Rework debug id injection sentry-cli#1670
   4 of 4
   +0
   
8. [Source Maps Adoption] Track success of symbolication sentry#54015
   +0

Java

Beta Give feedback

1. [Java] Improve Onboarding sentry-java#2770
   1 of 2
   Platform: Java +1
   

Android

Beta Give feedback

1. [Android] Improve Onboarding sentry-java#2802
   4 of 4
   Platform: Android +1
   

IOS

Beta Give feedback

1. [iOS] Improve Onboarding team-mobile#142
   3 of 3
   +0