diff --git a/src/platform-includes/capture-error/javascript.angular.mdx b/src/platform-includes/capture-error/javascript.angular.mdx index 65c5e3be64ecd..b519f497da4a3 100644 --- a/src/platform-includes/capture-error/javascript.angular.mdx +++ b/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 { diff --git a/src/platform-includes/enriching-events/import/javascript.angular.mdx b/src/platform-includes/enriching-events/import/javascript.angular.mdx index 430976281b09c..8c137b8308096 100644 --- a/src/platform-includes/enriching-events/import/javascript.angular.mdx +++ b/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"; ``` diff --git a/src/platform-includes/getting-started-config/javascript.angular.mdx b/src/platform-includes/getting-started-config/javascript.angular.mdx index 7d01181f3156f..5d87429ee5f34 100644 --- a/src/platform-includes/getting-started-config/javascript.angular.mdx +++ b/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({ // ... diff --git a/src/platform-includes/getting-started-install/javascript.angular.mdx b/src/platform-includes/getting-started-install/javascript.angular.mdx index dcba832babb2e..115ac9462765d 100644 --- a/src/platform-includes/getting-started-install/javascript.angular.mdx +++ b/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 ``` - +### 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 | + + 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 (@sentry/angular@^6.x) of the SDK. + For AngularJS/1.x, use @sentry/browser@^6.x and our AngularJS integration. + Note, that these versions of the SDK are no longer maintained or tested. diff --git a/src/platform-includes/getting-started-verify/javascript.angular.mdx b/src/platform-includes/getting-started-verify/javascript.angular.mdx new file mode 100644 index 0000000000000..178d733deb656 --- /dev/null +++ b/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} + +``` + +Then, in your `app.component.ts` add: + +```javascript {filename: app.component.ts} +public throwTestError(): void { + throw new Error("Sentry Test Error"); +} +``` + + + +Errors triggered from within Browser DevTools are sandboxed and won't trigger an error handler. Place the snippet directly in your code instead. + + diff --git a/src/platform-includes/performance/configure-sample-rate/javascript.mdx b/src/platform-includes/performance/configure-sample-rate/javascript.mdx index bfa1ae701ec7a..f140ce658ede4 100644 --- a/src/platform-includes/performance/configure-sample-rate/javascript.mdx +++ b/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"; diff --git a/src/platform-includes/performance/enable-automatic-instrumentation/javascript.mdx b/src/platform-includes/performance/enable-automatic-instrumentation/javascript.mdx index ddd6d92db4c9e..cba71fba6d5da 100644 --- a/src/platform-includes/performance/enable-automatic-instrumentation/javascript.mdx +++ b/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 diff --git a/src/platforms/javascript/guides/angular/features/component-tracking.mdx b/src/platforms/javascript/guides/angular/features/component-tracking.mdx index 585ef2bd84ac2..be89f5d06738b 100644 --- a/src/platforms/javascript/guides/angular/features/component-tracking.mdx +++ b/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}
user @@ -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"; diff --git a/src/wizard/javascript/angular.md b/src/wizard/javascript/angular.md index cddf739201bfd..978f4b366864f 100644 --- a/src/wizard/javascript/angular.md +++ b/src/wizard/javascript/angular.md @@ -5,24 +5,32 @@ support_level: production type: framework --- -To use Sentry with your Angular application, you will need to use `@sentry/angular` (Sentry’s Browser Angular SDK). +To use Sentry with your Angular application, you'll need `@sentry/angular-ivy` or `@sentry/angular`, Sentry’s Browser Angular SDKs: + +- If you're using Angular 12 or newer, use `@sentry/angular-ivy` +- If you're using Angular 10 or 11, use `@sentry/angular` Add the Sentry SDK as a dependency using `yarn` or `npm`: ```bash -# Using yarn +# Using yarn (Angular 12+) +yarn add @sentry/angular-ivy @sentry/tracing +# Using yarn (Angular 10 and 11) yarn add @sentry/angular @sentry/tracing -# Using npm +# Using npm (Angular 12+) +npm install --save @sentry/angular-ivy @sentry/tracing +# Using npm (Angular 10 and 11) npm install --save @sentry/angular @sentry/tracing ``` -You should `init` the Sentry browser SDK as soon as possible during your application load up, before initializing Angular: +You should `init` the Sentry browser SDK in your `main.ts` file as soon as possible during application load up, before initializing Angular: ```javascript import { enableProdMode } from "@angular/core"; import { platformBrowserDynamic } from "@angular/platform-browser-dynamic"; -import * as Sentry from "@sentry/angular"; +// import * as Sentry from "@sentry/angular" // for Angular 10/11 instead +import * as Sentry from "@sentry/angular-ivy"; import { BrowserTracing } from "@sentry/tracing"; import { AppModule } from "./app/app.module"; @@ -51,16 +59,17 @@ platformBrowserDynamic() The above configuration captures both error and performance data. To reduce the volume of performance data captured, change `tracesSampleRate` to a value between 0 and 1. -On its own, `@sentry/angular` will report any uncaught exceptions triggered by your application. Additionally, you can configure `@sentry/angular` to catch any Angular-specific exceptions reported through the [@angular/core/ErrorHandler](https://angular.io/api/core/ErrorHandler) provider. +On its own, the Angular SDK will report any uncaught exceptions triggered by your application. Additionally, you can configure the SDK to catch any Angular-specific exceptions reported through the [@angular/core/ErrorHandler](https://angular.io/api/core/ErrorHandler) provider. ### ErrorHandler and Tracer -`@sentry/angular` exports a function to instantiate `ErrorHandler` provider that will automatically send JavaScript errors captured by the Angular's error handler. +The Sentry Angular SDK exports a function to instantiate `ErrorHandler` provider that will automatically send JavaScript errors captured by the Angular's error handler. ```javascript import { APP_INITIALIZER, ErrorHandler, NgModule } from "@angular/core"; import { Router } from "@angular/router"; -import * as Sentry from "@sentry/angular"; +// import * as Sentry from "@sentry/angular" // for Angular 10/11 instead +import * as Sentry from "@sentry/angular-ivy"; @NgModule({ // ... diff --git a/src/wizard/javascript/replay-onboarding/angular/1.install.md b/src/wizard/javascript/replay-onboarding/angular/1.install.md index 78b66f5d9a3ec..a7910a32cc2ab 100644 --- a/src/wizard/javascript/replay-onboarding/angular/1.install.md +++ b/src/wizard/javascript/replay-onboarding/angular/1.install.md @@ -7,4 +7,4 @@ type: language #### Install -You need a minimum version 7.27.0 of `@sentry/angular` in order to use Session Replay. You don't need to install any additional packages. \ No newline at end of file +In order to use Session Replay, you'll need version 7.27.0 of `@sentry/angular` or `@sentry/angular-ivy` at minimum. You won't need to install any additional packages. diff --git a/src/wizard/javascript/replay-onboarding/angular/2.configure.md b/src/wizard/javascript/replay-onboarding/angular/2.configure.md index 1b43f2b112325..bf84f67372d07 100644 --- a/src/wizard/javascript/replay-onboarding/angular/2.configure.md +++ b/src/wizard/javascript/replay-onboarding/angular/2.configure.md @@ -10,7 +10,8 @@ type: language Add the following to your SDK config. There are several privacy and sampling options available, all of which can be set using the `integrations` constructor. Learn more about configuring Session Replay by reading the [configuration docs](https://docs.sentry.io/platforms/javascript/guides/angular/session-replay/). ```javascript -import * as Sentry from "@sentry/angular"; +// import * as Sentry from "@sentry/angular" // for Angular 10/11 instead +import * as Sentry from "@sentry/angular-ivy"; Sentry.init({ dsn: "___PUBLIC_DSN___",