From 40d437eb651a17f1d66d54e8d422d6cddcfb15f6 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Tue, 17 Sep 2024 09:00:00 +0200 Subject: [PATCH] ref(angular): Add code snippets for `app.config.ts`-based Angular apps (#11356) --------- Co-authored-by: Liza Mock --- .../angular/features/component-tracking.mdx | 28 ++++-- .../javascript.angular.mdx | 90 +++++++++++++++++-- 2 files changed, 103 insertions(+), 15 deletions(-) diff --git a/docs/platforms/javascript/guides/angular/features/component-tracking.mdx b/docs/platforms/javascript/guides/angular/features/component-tracking.mdx index 482d10f80d440..fa5ed2f9a4cde 100644 --- a/docs/platforms/javascript/guides/angular/features/component-tracking.mdx +++ b/docs/platforms/javascript/guides/angular/features/component-tracking.mdx @@ -3,7 +3,7 @@ title: Track Angular Components description: "Learn how Sentry's Angular SDK allows you to monitor the rendering performance of your application and its components." --- -Sentry's Angular SDK offers a feature to monitor the performance of your Angular components: Component Tracking. Enabling this feature provides you with spans in your transactions that show the initialization and update cycles of your Angular components. This allows you to drill down into how your components are behaving so you can identify slow initializations or frequent updates, which might have an impact on your app's performance. +Sentry's Angular SDK offers a component-tracking feature to monitor the performance of your Angular components. Enabling this feature starts spans that show the initialization and update cycles of your Angular components. This allows you to drill down into how your components are behaving so you can identify slow initializations or frequent updates, which may be impacting your app's performance. @@ -13,25 +13,37 @@ To set up component tracking, you need to configure tracing. For details on how To track your components as part of your transactions, use any (or a combination) of the following options. -## Using the `trace` directive +## Using the `trace` Directive -Our `TraceDirective` tracks a duration between the `OnInit` and `AfterViewInit` lifecycle hooks in your component template. It adds spans called **`ui.angular.init`** to the currently active transaction that allows you to track specific individual instances of your components. If you want to track all instances instead, use [`TraceClass`](#using-traceclass). +Our `TraceDirective` tracks the duration between the `OnInit` and `AfterViewInit` lifecycle hooks in your component template. It adds spans called `ui.angular.init` to the currently active transaction that allows you to track specific individual instances of your components. To track all instances, use [`TraceClass`](#using-traceclass). -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: +For both standalone components and NGModule-based app configs, register the `TraceModule` in the `imports` array of the standalone component or module that you want to use it in: -```typescript {filename:app.module.ts} {1,5} +```typescript {tabTitle:Standalone Component} {filename:app.component.ts} {3,8} +import { Component } from "@angular/core"; +import { RouterOutlet } from "@angular/router"; import * as Sentry from "@sentry/angular"; -@NgModule({ +@Component({ + selector: "app-root", + standalone: true, + imports: [Sentry.TraceModule], // ... +}) +export class AppComponent {} +``` + +```typescript {tabTitle:NGModule Config} {filename:app.module.ts} {1,4} +import * as Sentry from "@sentry/angular"; + +@NgModule({ imports: [Sentry.TraceModule], // ... }) export class AppModule {} ``` -Then, in your component's template, add the directive to all components you want to track. Remember to give the `trace` attribute a name, which will be shown in the span's description: +Then, in your component's template, add the `trace` directive to all components you want to track. Remember to give the `trace` attribute a name, which will be shown in the span's description: ```html {filename:app.component.(ts|html)} diff --git a/platform-includes/getting-started-config/javascript.angular.mdx b/platform-includes/getting-started-config/javascript.angular.mdx index 4b27bff6e3584..e964dce497875 100644 --- a/platform-includes/getting-started-config/javascript.angular.mdx +++ b/platform-includes/getting-started-config/javascript.angular.mdx @@ -1,12 +1,49 @@ Once this is done, Sentry's Angular SDK captures all unhandled exceptions and transactions. +```typescript {tabTitle: App Config} {filename: main.ts} {5-31} {"onboardingOptions": {"performance": "10-13, 18-25", "session-replay": "14-16, 26-30"}} +import { bootstrapApplication } from "@angular/platform-browser"; +import { appConfig } from "./app/app.config"; +import { AppComponent } from "./app/app.component"; -```typescript {filename: main.ts} {3, 6-30} {"onboardingOptions": {"performance": "9-12, 17-24", "session-replay": "13-15, 25-29"}} -import { enableProdMode } from "@angular/core"; -import { platformBrowserDynamic } from "@angular/platform-browser-dynamic"; import * as Sentry from "@sentry/angular"; + +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 + Sentry.browserTracingIntegration(), + // Registers the Replay integration, + // which automatically captures Session Replays + Sentry.replayIntegration(), + ], + + // Set tracesSampleRate to 1.0 to capture 100% + // of transactions for tracing. + // We recommend adjusting this value in production + tracesSampleRate: 1.0, + + // Set `tracePropagationTargets` to control for which URLs trace propagation should be enabled + tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/], + + // Capture Replay for 10% of all sessions, + // plus for 100% of sessions with an error + replaysSessionSampleRate: 0.1, + replaysOnErrorSampleRate: 1.0, +}); + +bootstrapApplication(AppComponent, appConfig).catch((err) => + console.error(err) +); +``` + +```typescript {tabTitle: NGModule Config} {filename: main.ts} {4-30} {"onboardingOptions": {"performance": "9-12, 17-24", "session-replay": "13-15, 25-29"}} +import { platformBrowserDynamic } from "@angular/platform-browser-dynamic"; import { AppModule } from "./app/app.module"; +import * as Sentry from "@sentry/angular"; + Sentry.init({ dsn: "___PUBLIC_DSN___", integrations: [ @@ -40,9 +77,40 @@ platformBrowserDynamic() ### Register Sentry Providers -The Sentry Angular SDK exports a couple of Angular providers that are necessary to fully instrument your application. We recommend registering them in your main `AppModule`: +The Sentry Angular SDK exports a couple of Angular providers that are necessary to fully instrument your application. We recommend registering them in your `app.config.ts` or main `app.module.ts`: + +```typescript {tabTitle: App Config} {filename: app.config.ts} {8, 13-26} {"onboardingOptions": {"performance": "17-26"}} +import { + APP_INITIALIZER, + ApplicationConfig, + ErrorHandler, +} from "@angular/core"; +import { Router } from "@angular/router"; + +import * as Sentry from "@sentry/angular"; + +export const appConfig: ApplicationConfig = { + providers: [ + // ... + { + provide: ErrorHandler, + useValue: Sentry.createErrorHandler(), + }, + { + provide: Sentry.TraceService, + deps: [Router], + }, + { + provide: APP_INITIALIZER, + useFactory: () => () => {}, + deps: [Sentry.TraceService], + multi: true, + }, + ], +}; +``` -```typescript {filename: app.module.ts} {4, 9-22} {"onboardingOptions": {"performance": "13-22"}} +```typescript {tabTitle: NGModule Config} {filename: app.module.ts} {4, 9-22} {"onboardingOptions": {"performance": "13-22"}} import { APP_INITIALIZER, ErrorHandler, NgModule } from "@angular/core"; import { Router } from "@angular/router"; @@ -73,10 +141,17 @@ export class AppModule {} The `Sentry.createErrorHandler` function initializes a Sentry-specific `ErrorHandler` that automatically sends errors caught by Angular to Sentry. You can also customize the behavior by setting a couple of handler [options](https://github.com/getsentry/sentry-javascript/blob/master/packages/angular/src/errorhandler.ts). + + +If your angular app is configured for SSR, make sure that the Sentry providers are not accidentally passed to the SSR config (`app.config.server.ts`). The Sentry Angular SDK can only be used in the browser. + + + -The `Sentry.TraceService` listens to the Angular router for tracing. To inject `TraceService`, register the `APP_INITIALIZER` provider as shown above. Alternatively, you can also require the `TraceService` from inside your `AppModule` constructor: -```javascript {filename: app.module.ts} {5} +If you're using an NGModule-based application (`app.module.ts`), you can also dependency-inject the `TraceService` from inside your `AppModule` constructor, instead of providing `APP_INITIALIZER`: + +```javascript {tabTitle: NGModule Config} {filename: app.module.ts} {5} @NgModule({ // ... }) @@ -84,4 +159,5 @@ export class AppModule { constructor(trace: Sentry.TraceService) {} } ``` +