From dd7ac7338cf689dd929de582ce3c2169a1613238 Mon Sep 17 00:00:00 2001 From: Ash <0Calories@users.noreply.github.com> Date: Mon, 12 Feb 2024 11:53:29 -0500 Subject: [PATCH] Add content related to React component name tracking (#9097) * Add content related to React component name tracking * Add docs for the searchable property in replay --------- Co-authored-by: Liza Mock --- .../react/features/component-tracking.mdx | 79 ++++++++++++++++++- .../searchable-properties/session-replay.mdx | 8 ++ 2 files changed, 86 insertions(+), 1 deletion(-) diff --git a/docs/platforms/javascript/guides/react/features/component-tracking.mdx b/docs/platforms/javascript/guides/react/features/component-tracking.mdx index 390d4d40da607..6a3fab0f8b93e 100644 --- a/docs/platforms/javascript/guides/react/features/component-tracking.mdx +++ b/docs/platforms/javascript/guides/react/features/component-tracking.mdx @@ -4,6 +4,83 @@ excerpt: "" description: "Learn how Sentry's React SDK allows you to monitor the rendering performance of your application and its components." --- +Sentry helps you track your React components and unlock additional insights in your application. You can set it up to track React component names as well as monitor the performance of your React components with component tracking. + +## Component Name Tracking + +You can track the names of React components in your application via a [Babel plugin](https://www.npmjs.com/package/@sentry/babel-plugin-component-annotate), which can unlock powerful workflows and decrease ambiguity. For example, you can search for replays where a specific React component was clicked on. You can also see the name of the component that was clicked on in breadcrumbs and spans on Sentry's **Performance** page. This significantly decreases the amount of ambiguity involved in figuring out which element was interacted with as compared to trying to figure it out by looking at the element's CSS selector alone (which becomes even more ambiguous after the minification process). + +We're working to release more features that will leverage component name tracking in the future and highly recommended that you configure your project to use it. + +### How to Install + + + +Please note that your Sentry browser SDK must be at version `7.91.0` or higher before you can use these features. +Only React components in `.jsx` or `.tsx` files can be tracked. + + + +There are two different ways you can set up React component name tracking in your application: + +1. By installing [Sentry's bundler plugins](https://www.npmjs.com/package/@sentry/bundler-plugin-core) +2. By directly installing [@sentry/babel-plugin-component-annotate](https://www.npmjs.com/package/@sentry/babel-plugin-component-annotate) + +We recommend that you use the first option because the Sentry bundler plugins come packed with additional useful features to enrich your Sentry workflows, including: automatic sourcemap upload, +release creation, automatic release name discovery, and release injection. + +**Set up using bundler plugins**: + +Follow the instructions in the npm page for the bundler that your project uses: +- [Rollup](https://www.npmjs.com/package/@sentry/rollup-plugin) +- [Vite](https://www.npmjs.com/package/@sentry/vite-plugin) +- [Webpack](https://www.npmjs.com/package/@sentry/webpack-plugin) + +Please note that although there is a Sentry bundler plugin for **esbuild**, React component name tracking is currently not supported. + +Once you've followed the instructions to install the bundler plugin and added it to your bundler's config, enable component name tracking by setting the flag for it to `true`: + + +```javascript +// Example specific to Vite, see documentation for other bundlers +sentryVitePlugin({ + // ... other options above + reactComponentAnnotation: { enabled: true } +}), +``` + + + +**If you're using Rollup as your bundler**, ensure that you place `sentryRollupPlugin` before any other plugins that transform your JSX. + + + +Now, you will be able to see your component names in breadcrumbs, spans, and search for replays by component names. +See [this page](/platforms/javascript/guides/react/features/component-tracking/#component-name-tracking) for more information on searching for Replays by component name. + + +### How It Works + +The Babel plugin parses your application's JSX source code at build time, and applies additional `data` attributes onto it. These attributes then appear on the DOM nodes of your application's built HTML, indicating the React component and file that each node is sourced from. + +For example, if you had a component named `MyAwesomeComponent` in the file `myAwesomeComponent.jsx`: + +```javascript +function MyAwesomeComponent() { + return
This is a really cool and awesome component!
+} +``` + +After your bundler applied the plugin and built your project, the resulting DOM node would look like this: + +```html +
This is a really cool and awesome component!
+``` + +The Sentry browser SDK will pick off the value from these `data` attributes and collect them when your components are interacted with. + +## Component Performance Monitoring + 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. @@ -52,7 +129,7 @@ In [React Strict Mode](https://reactjs.org/docs/strict-mode.html), certain compo -## Profiler Options +### Profiler Options The `withProfiler` higher-order component has a variety of options for further customization. They can be passed in as the second argument to the `withProfiler` function. diff --git a/docs/product/reference/search/searchable-properties/session-replay.mdx b/docs/product/reference/search/searchable-properties/session-replay.mdx index 4d266e18e2e95..8bd4fa21e27bd 100644 --- a/docs/product/reference/search/searchable-properties/session-replay.mdx +++ b/docs/product/reference/search/searchable-properties/session-replay.mdx @@ -42,6 +42,14 @@ The `class` of an element that was clicked. No leading `.` is necessary. For exa - **Type:** string +### `click.component_name` + +The name of the frontend component that was clicked. For example, `MyAwesomeComponent` would match the React component ``. + +Note: This property requires that your project have [React component name tracking configured](/platforms/javascript/guides/react/features/component-tracking/#component-name-tracking). + +- **Type:** string + ### `click.id` The `id` of an element that was clicked. No leading `#` is necessary. For example, `reset-password` would match the element `Reset`