ref: Improve JS SDK Component Tracking Documentation (#5619)

Make structural, naming and content changes to the documentation of a feature we support in four JS framework SDKs - component tracking. Previously, this documentation differed drastically between these four SDKs. Not only did the location differ, but also, how we called the feature. With this patch, we're introducing one name that describes this feature, while we still find a balance between "component tracking" and however the feature is called in the SDK's code (e.g. "trace helpers" in Angular or "Profiler" in React).

Impacted SDKs: Angular, React, Vue, Svelte

As of this patch, we make the following changes:

**All SDKs**
* Adjusted the naming and location of the documentation. In the menu on the left, it is now located under "<Framework> Features" -> "Component Tracking"
* Added a sentence in all "<framwork> Features" index pages explaining that these features are specifically built for the respective framework. For example, in React we don't only have component tracking as such a feature but also the Sentry error boundary. 
* Added a small paragraph on top of the component tracking page, explaining the feature and why it's helpful
* Mentioned the names of the spans that this feature adds to the transactions so that users are aware of what it is actually doing. The React docs were already doing this and I thought this would be valuable information for every SDK.

**Angular**:
* Rephrased some paragraphs and sentences that were previously confusing
* Added sub-headings for each utility (previously it was a list)
* Added an "Advanced" usage section, explaining that the utilities can be used together
* Adjusted the code examples and corrected some minor mistakes

**Vue**:

The Vue SDK documentation didn't have a proper page for component tracking previously. Instead it was spread across three pages. 

* Moved component tracking documentation from the "Vue Router Integration" to the new component tracking page
* Adjusted this documentation by
  * Removing unnecessary technical details
  * Better explaining each of the three options
  * Removing lifecycle hooks that weren't even supported by the SDK
* Since component tracking was mentioned in two other pages (Getting started and Performance Setup), I decided to shorten the description in the respective places to only leave the gist there. In both places, I added links to the component tracking page for more details.
* Left the part that is actually about the Vue router on the "Vue Router Integration" page.
  * I'm not too happy with this, because technically speaking we don't have a Vue router integration but an _instrumentation_ but we do the same thing in the React SDK. In both cases, the pages actually contain relevant information. So we can leave it for now as is and revisit this if it comes up.

Co-authored-by: Isabel <[email protected]>

Author: Lms24

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

@@ -24,7 +24,7 @@ Once this is done, all unhandled exceptions are automatically captured by Sentry
 
 ### Add Error Boundary
 
-If you're using React 16 or above, you can use the [Error Boundary](components/errorboundary/) component to automatically send Javascript errors from inside a component tree to Sentry, and set a fallback UI.
+If you're using React 16 or above, you can use the [Error Boundary](features/error-boundary/) component to automatically send Javascript errors from inside a component tree to Sentry, and set a fallback UI.
 
 ### Set Up React Router
 

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

@@ -107,9 +107,7 @@ The SDK accepts a few different configuration options that let you change its be
 
 - `attachProps` (defaults to `true`) - Includes all Vue components' props with the events.
 - `logErrors` (defaults to `false`) - Decides whether SDK should call Vue's original `logError` function as well.
-- `trackComponents` (defaults to `false`) - Decides whether to track components by hooking into its lifecycle methods. Can be set to either `boolean`, to enable/disable tracking for all of them, or to an array of specific component names (case-sensitive).
-- `timeout` (defaults to `2000`) - Time in milliseconds dictating how long to wait until the tracked root activity is marked as finished and sent off to Sentry.
-- `hooks` (defaults to `['activate', 'mount', 'update']`) - List of hooks to keep track of during component lifecycle `'activate' | 'create' | 'destroy' | 'mount' | 'unmount' | 'update'`.
+- `trackComponents` (defaults to `false`) - Track your app's components. Learn more about [component tracking](./features/component-tracking) and all its options.
 
 <Note>
 

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

@@ -15,7 +15,7 @@ Sentry.init({
 
   // This enables automatic instrumentation (highly recommended), but is not
   // necessary for purely manual usage
-  integrations: [new BrowserTracing],
+  integrations: [new BrowserTracing()],
 
   // To set a uniform sample rate
   tracesSampleRate: 0.2
@@ -43,11 +43,7 @@ Sentry.init({
 
 ## Configure Tracing Instrumentation
 
-If you want to track child components or use additional hooks to see more details about the rendering process, you can configure the SDK using options below. Captured data will be then stored as spans and attached to the currently active transaction on the scope:
-
-- `trackComponents` (defaults to `false`) - Decides whether to track components by hooking into its lifecycle methods. Can be set to either `boolean`, to enable/disable tracking for all of them, or to an array of specific component names (case-sensitive).
-- `timeout` (defaults to `2000`) - Time in milliseconds dictating how long to wait until the tracked root activity is marked as finished and sent off to Sentry.
-- `hooks` (defaults to `['activate', 'mount', 'update']`) - List of hooks to keep track of during component lifecycle `'activate' | 'create' | 'destroy' | 'mount' | 'unmount' | 'update'`.
+If you want to track child components, you can configure the SDK using additional options as shown below. Captured data will be then stored as spans and attached to the currently active transaction:
 
 ```javascript
 Sentry.init({
@@ -57,3 +53,5 @@ Sentry.init({
   hooks: ["create", "mount"],
 });
 ```
+
+Learn more about [Vue component tracking](../features/component-tracking).

src/platforms/common/performance/index.mdx

@@ -136,7 +136,7 @@ import * as Sentry from "@sentry/react";
 export default Sentry.withProfiler(App);
 ```
 
-Learn more about using and customizing the React Profiler in [Profiler](/platforms/javascript/guides/react/components/profiler/).
+Learn more about using and customizing the React Profiler in [React Component Tracking](/platforms/javascript/guides/react/features/component-tracking/).
 
 ## React Router
 

src/platforms/javascript/guides/angular/components/index.mdx

@@ -0,0 +1,161 @@
+---
+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 get a drilled-down view into how your components are behaving so you can do things like identify slow initializations or frequent updates, which might have an impact on your app's performance.
+
+<Alert>
+
+To set up component tracking, you need to configure performance monitoring. For details on how to do this, check out our [Performance documentation](/platforms/javascript/guides/angular/performance/).
+
+</Alert>
+
+To track your components as part of your transactions, use any (or a combination) of the following options.
+
+## Using `TraceDirective`
+
+`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 [`TraceClassDecorator`](#using-traceclassdecorator).
+
+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}
+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:
+
+```html {filename:app.component.ts}
+<app-header [trace]="'header'"></app-header>
+<articles-list [trace]="'articles-list'"></articles-list>
+<app-footer [trace]="'footer'"></app-footer>
+```
+
+<Alert level="info" title="Compatibility">
+
+If you're using version 6 of the Angular SDK, using `TraceDirective` or `TraceModule` causes a
+compiler error at application compile time of your Angular application. This is a [known issue](https://github.com/getsentry/sentry-javascript/issues/3282)
+of our Angular SDK v6 and it was [fixed](https://github.com/getsentry/sentry-javascript/issues/4644)
+in version 7. We recommend upgrading to the latest Angular SDK version.
+Otherwise, please use the other options (`TraceClassDecorator` and `TraceMethodDecorator`)
+below to track your Angular components.
+
+</Alert>
+
+## Using `TraceClassDecorator`
+
+`TraceClassDecorator` tracks the duration between the `OnInit` and `AfterViewInit` lifecycle hooks in components. It adds spans called **`ui.angular.init`** to the currently active transaction. In contrast to [`TraceDirective`](#using-tracedirective), `TraceClassDecorator` tracks all instances of the component(s) you add it to, creating spans for each component instance.
+
+Just add `TraceClassDecorator` to the components you want to track:
+
+```typescript {filename:header.component.ts}
+import { Component } from "@angular/core";
+import * as Sentry from "@sentry/angular";
+
+@Component({
+  selector: "app-header",
+  templateUrl: "./header.component.html",
+})
+@Sentry.TraceClassDecorator()
+export class HeaderComponent {
+  // ...
+}
+```
+
+## Using `TraceMethodDecorator`
+
+`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}
+import { Component, OnInit } from "@angular/core";
+import * as Sentry from "@sentry/angular";
+
+@Component({
+  selector: "app-login",
+  templateUrl: "./login.component.html",
+})
+export class LoginComponent implements OnChanges {
+  @Sentry.TraceMethodDecorator()
+  ngOnChanges(changes: SimpleChanges) {}
+}
+```
+
+## Advanced Usage
+
+You can combine our tracking utilities and track the bootstrapping duration of your app.
+
+### Combining Component Tracking Utilities
+
+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}
+import { Component, OnInit } from "@angular/core";
+import * as Sentry from "@sentry/angular";
+
+@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() {}
+}
+```
+
+User `TraceDirective` if you only want to track components in certain instances or locations:
+
+```html {user-card.component.html}
+<div>
+  <app-icon trace="user-icon">user</app-icon>
+  <label>{{ user.name }}</label>
+  <!--...-->
+  <app-button trace="save-user">Save</app-button>
+</div>
+```
+
+### Track Angular Bootstrapping
+
+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
+import { enableProdMode } from "@angular/core";
+import { platformBrowserDynamic } from "@angular/platform-browser-dynamic";
+import * as Sentry from "@sentry/angular";
+
+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();
+    }
+  });
+```
+
+Learn more about [custom instrumentation](../../performance/instrumentation/custom-instrumentation/).

src/platforms/javascript/guides/angular/components/tracehelpers.mdx

@@ -0,0 +1,9 @@
+---
+title: Angular Features
+description: "Learn how Sentry's Angular SDK exposes features for first class integration with Angular."
+excerpt: ""
+---
+
+The Sentry Angular SDK offers Angular-specific features for first class integration with the framework.
+
+<PageGrid />

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

@@ -1,12 +1,18 @@
 ---
-title: React Profiler
+title: Track React Components
 excerpt: ""
-description: "Learn how Sentry's React SDK exports a `withProfiler` higher-order component that attaches React related spans to the current active transaction on the scope."
+description: "Learn how Sentry's React SDK allows you to monitor the rendering performance of your application and its components."
 ---
 
-`@sentry/react` exports a `withProfiler` higher-order component that attaches React related spans to the current active transaction on the scope.
+Sentry's React SDK offers a feature to monitor the performance of your React components: component tracking. The SDK exports a `withProfiler` higher-order component that attaches React related spans to the current active transaction on the scope. This allows you to get a drilled-down view into how your components are behaving so you can do things like identify slow mounts or frequent updates, which might have an impact on your app's performance.
 
-In the example below, the `withProfiler` higher-order component is used to instrument an App component.
+<Alert>
+
+To set up component tracking, you need to configure performance monitoring. For details on how to do this, check out our [Performance documentation](/platforms/javascript/guides/react/performance/).
+
+</Alert>
+
+In the example below, the `withProfiler` higher-order component is used to instrument an app component.
 
 ```javascript
 import React from "react";
@@ -69,4 +75,4 @@ export default Sentry.withProfiler(App, { name: "CustomAppName" });
 ## Next Steps:
 
 - [Return to **Getting Started**](../../)
-- [Return to the main components page](../)
+- [Return to **React Features**](../)