ref(angular): Update Angular SDK docs for @sentry/angular-ivy (#6356)

To ensure first-class compatibility with Angular's "new" rendering engine, Ivy, we needed to create a new SDK package that's compiled differently than the original `@sentry/angular` package. This new SDK is compatible with Angular 12 and newer and hence we're going to make it the default SDK in the docs going forward.

This PR 
* Updates the Angular version <-> Sentry SDK compatibility description with a table
  * I added entries for Angular 1/AngularJS (this came up recently in a Slack convo) and Angular 2-9 with a message that we do not support these versions anymore in v7 of the SDKs. Happy to make changes here if reviewers think this shouldn't be promoted.
* Updates imports and code snippets with versions for Angular 12+ (ivy) and Angular 10/11
* Updates the SDK onboarding wizard docs (+ Replay onboarding)
* Adds an Angular-specific verify code snippet which was missing before
* Adds file names to all angular code snippets (this came up in #6326 and it was easiest to just do it in this PR)
* streamlines the Angular "Getting started" page and fixes a few typos/wording issues

Co-authored-by: Andrea Canciani <[email protected]>
Co-authored-by: Liza Mock <[email protected]>

Author: 3 people

src/platform-includes/capture-error/javascript.angular.mdx

@@ -1,6 +1,16 @@
 You can pass an `Error` object to `captureException()` to get it captured as event. It's also possible to pass non-`Error` objects and strings, but be aware that the resulting events in Sentry may be missing a stacktrace.
 
-```javascript
+```javascript{tabTitle: Angular 12+}
+import * as Sentry from "@sentry/angular-ivy";
+
+try {
+  aFunctionThatMightFail();
+} catch (err) {
+  Sentry.captureException(err);
+}
+```
+
+```javascript{tabTitle: Angular 10/11}
 import * as Sentry from "@sentry/angular";
 
 try {

src/platform-includes/enriching-events/import/javascript.angular.mdx

@@ -1,3 +1,7 @@
-```javascript
+```javascript {tabTitle: Angular 12+}
+import * as Sentry from "@sentry/angular-ivy";
+```
+
+```javascript {tabTitle: Angular 10/11}
 import * as Sentry from "@sentry/angular";
 ```

src/platform-includes/getting-started-config/javascript.angular.mdx

@@ -1,14 +1,14 @@
 Once this is done, Sentry's Angular SDK captures all unhandled exceptions and transactions.
 
-```javascript
+```javascript{tabTitle: Angular 12+}{filename: main.ts}
 import { enableProdMode } from "@angular/core";
 import { platformBrowserDynamic } from "@angular/platform-browser-dynamic";
-import * as Sentry from "@sentry/angular";
+import * as Sentry from "@sentry/angular-ivy";
 import { BrowserTracing } from "@sentry/tracing";
 import { AppModule } from "./app/app.module";
 
 Sentry.init({
-  dsn: "___PUBLIC_DSN___" ,
+  dsn: "___PUBLIC_DSN___",
   integrations: [
     // Registers and configures the Tracing integration,
     // which automatically instruments your application to monitor its
@@ -25,22 +25,67 @@ Sentry.init({
   tracesSampleRate: 1.0,
 });
 
-
 platformBrowserDynamic()
   .bootstrapModule(AppModule)
   .then(success => console.log(`Bootstrap success`))
   .catch(err => console.error(err));
 ```
 
-You can also configure `@sentry/angular` to catch any Angular-specific exceptions reported through the [@angular/core/ErrorHandler](https://angular.io/api/core/ErrorHandler) provider.
+```javascript{tabTitle: Angular 10/11}{filename: main.ts}
+import { enableProdMode } from "@angular/core";
+import { platformBrowserDynamic } from "@angular/platform-browser-dynamic";
+import * as Sentry from "@sentry/angular";
+import { BrowserTracing } from "@sentry/tracing";
+import { AppModule } from "./app/app.module";
+
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  integrations: [
+    // Registers and configures the Tracing integration,
+    // which automatically instruments your application to monitor its
+    // performance, including custom Angular routing instrumentation
+    new BrowserTracing({
+      tracePropagationTargets: ["localhost", "https://yourserver.io/api"],
+      routingInstrumentation: Sentry.routingInstrumentation,
+    }),
+  ],
+
+  // Set tracesSampleRate to 1.0 to capture 100%
+  // of transactions for performance monitoring.
+  // We recommend adjusting this value in production
+  tracesSampleRate: 1.0,
+});
 
-`@sentry/angular` exports a Trace Service, Directive, and Decorators that leverages the `@sentry/tracing`, Sentry's Tracing integration, to add Angular-related spans to transactions. The service itself tracks route changes and durations, where directive and decorators are tracking component initializations.
+platformBrowserDynamic()
+  .bootstrapModule(AppModule)
+  .then(success => console.log(`Bootstrap success`))
+  .catch(err => console.error(err));
+```
 
 ### Automatically Send Errors with `ErrorHandler`
 
-`@sentry/angular` exports a function to instantiate an `ErrorHandler` provider that will automatically send JavaScript errors captured by the Angular's error handler.
+The Angular SDK exports a function to instantiate an `ErrorHandler` provider that will automatically send JavaScript errors captured by Angular's error handler.
+
+```javascript{tabTitle: Angular 12+}{filename: app.module.ts}
+import { NgModule, ErrorHandler } from "@angular/core";
+import * as Sentry from "@sentry/angular-ivy";
+
+@NgModule({
+  // ...
+  providers: [
+    {
+      provide: ErrorHandler,
+      useValue: Sentry.createErrorHandler({
+        showDialog: true,
+      }),
+    },
+  ],
+  // ...
+})
+export class AppModule {}
+```
 
-```javascript
+```javascript{tabTitle: Angular 10/11}{filename: app.module.ts}
 import { NgModule, ErrorHandler } from "@angular/core";
 import * as Sentry from "@sentry/angular";
 
@@ -63,9 +108,27 @@ You can configure the behavior of `createErrorHandler`. For more details see the
 
 ### Register `TraceService`
 
-In Angular's DI system, register `TraceService` as a provider with a `Router` as its dependency:
+For performance monitoring, register `TraceService` as a provider with a `Router` as its dependency:
+
+```javascript{tabTitle: Angular 12+}{filename: app.module.ts}
+import { NgModule } from "@angular/core";
+import { Router } from "@angular/router";
+import * as Sentry from "@sentry/angular-ivy";
+
+@NgModule({
+  // ...
+  providers: [
+    {
+      provide: Sentry.TraceService,
+      deps: [Router],
+    },
+  ],
+  // ...
+})
+export class AppModule {}
+```
 
-```javascript
+```javascript{tabTitle: Angular 10/11}{filename: app.module.ts}
 import { NgModule } from "@angular/core";
 import { Router } from "@angular/router";
 import * as Sentry from "@sentry/angular";
@@ -82,8 +145,10 @@ import * as Sentry from "@sentry/angular";
 })
 export class AppModule {}
 ```
+
 Then, either require the `TraceService` from inside `AppModule` or use `APP_INITIALIZER` to force instantiate Tracing.
-```javascript
+
+```javascript {filename: app.module.ts}
 @NgModule({
   // ...
 })
@@ -94,7 +159,7 @@ export class AppModule {
 
 or
 
-```javascript
+```javascript {filename: app.module.ts}
 import { APP_INITIALIZER } from "@angular/core";
 @NgModule({
   // ...

src/platform-includes/getting-started-install/javascript.angular.mdx

@@ -1,18 +1,32 @@
 ```bash {tabTitle:npm}
+# Angular 12 and newer:
+npm install --save @sentry/angular-ivy @sentry/tracing
+
+# Angular 10 and 11:
 npm install --save @sentry/angular @sentry/tracing
 ```
 
 ```bash {tabTitle:Yarn}
+# Angular 12 and newer:
+yarn add @sentry/angular-ivy @sentry/tracing
+
+# Angular 10 and 11:
 yarn add @sentry/angular @sentry/tracing
 ```
 
-<Alert level="info" title="Angular Version Compatibility" >
+### Angular Version Compatibility
+
+Because of the way Angular libraries are compiled, you need to use a specific version of the Sentry SDK for each corresponding version of Angular as shown below:
 
-The latest version of the Sentry Angular SDK officially supports Angular 10 and newer.
-If you need to use Angular 9 or older and you experience problems with the latest version of the Sentry SDK,
-try downgrading the SDK to version 6 (`@sentry/angular@^6.x`). If you are using Sentry Tracing,
-be sure to also downgrade it to the same version (`@sentry/tracing@^6.x`).
-Version 6 of the Sentry SDK was compiled differently and might work with older versions of Angular.
-Please note that this combination of packages is not being maintained or tested.
+| Angular version | Recommended Sentry SDK |
+| --------------- | ---------------------- |
+| 12 and newer    | `@sentry/angular-ivy`  |
+| 10, 11          | `@sentry/angular`      |
+| Older versions  | See note below         |
 
+<Alert level="warning">
+  Support for any Angular version below 10 was discontinued in version 7 of the SDK.
+  If you need to use Angular 9 or older, try version 6 (<code>@sentry/angular@^6.x</code>) of the SDK.
+  For AngularJS/1.x, use <code>@sentry/browser@^6.x</code> and our <a href="./angular1">AngularJS integration</a>.
+  Note, that these versions of the SDK are no longer maintained or tested.
 </Alert>

src/platform-includes/getting-started-verify/javascript.angular.mdx

@@ -0,0 +1,19 @@
+Trigger a test error somewhere in your Angular app, for example in your main app component:
+
+```html {filename: app.component.html}
+<button (click)="throwTestError()">Test Sentry Error</button>
+```
+
+Then, in your `app.component.ts` add:
+
+```javascript {filename: app.component.ts}
+public throwTestError(): void {
+  throw new Error("Sentry Test Error");
+}
+```
+
+<Note>
+
+Errors triggered from within Browser DevTools are sandboxed and won't trigger an error handler. Place the snippet directly in your code instead.
+
+</Note>

src/platform-includes/performance/configure-sample-rate/javascript.mdx

@@ -1,5 +1,5 @@
 ```javascript {tabTitle: ESM}
-// If you're using one of our integration packages, like `@sentry/angular`,
+// If you're using one of our framework SDK packages, like `@sentry/angular`,
 // substitute its name for `@sentry/browser` here
 import * as Sentry from "@sentry/browser";
 

src/platform-includes/performance/enable-automatic-instrumentation/javascript.mdx

@@ -3,7 +3,7 @@ To enable tracing, include the `BrowserTracing` integration in your SDK configur
 After configuration, you will see both `pageload` and `navigation` transactions in the Sentry UI.
 
 ```javascript {tabTitle: ESM}
-// If you're using one of our integration packages, like `@sentry/angular`,
+// If you're using one of our framework SDK packages, like `@sentry/angular`,
 // substitute its name for `@sentry/browser` here
 import * as Sentry from "@sentry/browser";
 import { BrowserTracing } from "@sentry/tracing"; // Must import second

src/platforms/javascript/guides/angular/features/component-tracking.mdx

@@ -20,7 +20,18 @@ To track your components as part of your transactions, use any (or a combination
 Import `TraceModule` either globally in your application's `app.module.ts` file or in the module(s) in which
 you want to track your components:
 
-```typescript {filename:app.module.ts}
+```typescript {filename:app.module.ts} {tabTitle:Angular 12+}
+import * as Sentry from "@sentry/angular-ivy";
+
+@NgModule({
+  // ...
+  imports: [Sentry.TraceModule],
+  // ...
+})
+export class AppModule {}
+```
+
+```typescript {filename:app.module.ts} {tabTitle:Angular 10/11}
 import * as Sentry from "@sentry/angular";
 
 @NgModule({
@@ -56,7 +67,21 @@ below to track your Angular components.
 
 Just add `TraceClassDecorator` to the components you want to track:
 
-```typescript {filename:header.component.ts}
+```javascript {filename:header.component.ts} {tabTitle: Angular 12+}
+import { Component } from "@angular/core";
+import * as Sentry from "@sentry/angular-ivy";
+
+@Component({
+  selector: "app-header",
+  templateUrl: "./header.component.html",
+})
+@Sentry.TraceClassDecorator()
+export class HeaderComponent {
+  // ...
+}
+```
+
+```javascript {filename:header.component.ts} {tabTitle: Angular 10/11}
 import { Component } from "@angular/core";
 import * as Sentry from "@sentry/angular";
 
@@ -74,7 +99,21 @@ export class HeaderComponent {
 
 `TraceMethodDecorator` tracks specific component lifecycle hooks as point-in-time spans. The added spans are called **`ui.angular.[methodname]`** (like, `ui.angular.ngOnChanges`). For example, you can use this decorator to track how often component changes are detected during an ongoing transaction:
 
-```typescript {filename:login.component.ts}
+```javascript {filename:login.component.ts} {tabTitle: Angular 12+}
+import { Component, OnInit } from "@angular/core";
+import * as Sentry from "@sentry/angular-ivy";
+
+@Component({
+  selector: "app-login",
+  templateUrl: "./login.component.html",
+})
+export class LoginComponent implements OnChanges {
+  @Sentry.TraceMethodDecorator()
+  ngOnChanges(changes: SimpleChanges) {}
+}
+```
+
+```javascript {filename:login.component.ts} {tabTitle: Angular 10/11}
 import { Component, OnInit } from "@angular/core";
 import * as Sentry from "@sentry/angular";
 
@@ -96,7 +135,25 @@ You can combine our tracking utilities and track the bootstrapping duration of y
 
 To get the best insights into your components' performance, you can combine `TraceDirective`, `TraceClassDecorator`, and `TraceMethodDecorator`. This allows you to track component initialization durations as well as arbitrary lifecycle events, such as change and destroy events:
 
-```typescript {filename:user-card.component.ts}
+```javascript {filename:user-card.component.ts} {tabTitle: Angular 12+}
+import { Component, OnInit } from "@angular/core";
+import * as Sentry from "@sentry/angular-ivy";
+
+@Component({
+  selector: "app-user-card",
+  templateUrl: "./user-card.component.html",
+})
+@Sentry.TraceClassDecorator()
+export class UserCardComponent implements OnChanges, OnDestroy {
+  @Sentry.TraceMethodDecorator()
+  ngOnChanges(changes: SimpleChanges) {}
+
+  @Sentry.TraceMethodDecorator()
+  ngOnDestroy() {}
+}
+```
+
+```javascript {filename:user-card.component.ts} {tabTitle: Angular 10/11}
 import { Component, OnInit } from "@angular/core";
 import * as Sentry from "@sentry/angular";
 
@@ -116,7 +173,7 @@ export class UserCardComponent implements OnChanges, OnDestroy {
 
 User `TraceDirective` if you only want to track components in certain instances or locations:
 
-```html {user-card.component.html}
+```html {filename: user-card.component.html}
 <div>
   <app-icon trace="user-icon">user</app-icon>
   <label>{{ user.name }}</label>
@@ -130,7 +187,35 @@ User `TraceDirective` if you only want to track components in certain instances
 You can add your own custom spans by attaching them to the currently active transaction using the `getActiveTransaction`
 helper. For example, you can track the duration of the Angular bootstrapping process to find out how long your app takes to bootstrap on your users' devices:
 
-```javascript
+```javascript {tabTitle: Angular 12+} {filename:main.ts}
+import { enableProdMode } from "@angular/core";
+import { platformBrowserDynamic } from "@angular/platform-browser-dynamic";
+import * as Sentry from "@sentry/angular-ivy";
+
+import { AppModule } from "./app/app.module";
+
+// ...
+
+const activeTransaction = Sentry.getActiveTransaction();
+const bootstrapSpan =
+  activeTransaction &&
+  activeTransaction.startChild({
+    description: "platform-browser-dynamic",
+    op: "ui.angular.bootstrap",
+  });
+
+platformBrowserDynamic()
+  .bootstrapModule(AppModule)
+  .then(() => console.log(`Bootstrap success`))
+  .catch(err => console.error(err))
+  .finally(() => {
+    if (bootstrapSpan) {
+      bootstrapSpan.finish();
+    }
+  });
+```
+
+```javascript {tabTitle: Angular 10/11} {filename:main.ts}
 import { enableProdMode } from "@angular/core";
 import { platformBrowserDynamic } from "@angular/platform-browser-dynamic";
 import * as Sentry from "@sentry/angular";