Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

📝 add rum-react documentation to the integration page #2604

Open
wants to merge 8 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/CODEOWNERS
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,6 @@
/insightfinder/ @dearmore @erinlmcmahon [email protected] @DataDog/ecosystems-review
/isdown/ @ntomas [email protected] @DataDog/ecosystems-review
/jamf_protect/ @DataDog/saas-integrations
/rum_javascript/ @DataDog/rum-app
/k6/ @ppcano [email protected]
/kameleoon/ @slava-inyu [email protected] @DataDog/ecosystems-review
/kernelcare/ @grubberr [email protected]
Expand Down Expand Up @@ -170,13 +169,14 @@
/rigor/ [email protected]
/robust_intelligence_ai_firewall/ @MayankR
/rookout/ [email protected] @DataDog/ecosystems-review
/rum_javascript/ @DataDog/rum-app @DataDog/rum-browser
/rum_android/ @DataDog/rum-app @DataDog/rum-mobile @DataDog/rum-mobile-android
/rum_angular/ @DataDog/rum-app
/rum_cypress/ @DataDog/rum-app
/rum_expo/ @DataDog/rum-app @DataDog/rum-mobile
/rum_flutter/ @DataDog/rum-app @DataDog/rum-mobile
/rum_ios/ @DataDog/rum-app @DataDog/rum-mobile @DataDog/rum-mobile-ios
/rum_react/ @DataDog/rum-app
/rum_react/ @DataDog/rum-app @DataDog/rum-browser
/rum_react_native/ @DataDog/rum-app @DataDog/rum-mobile
/rum_roku/ @DataDog/rum-app @DataDog/rum-mobile
/rundeck/ [email protected]
Expand Down
9 changes: 6 additions & 3 deletions rum_react/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,11 @@
# CHANGELOG - React

## 1.0.0
## 2.0.0

- Add documentation for the RUM React integration plugin

***Added***:
## 1.0.0

* Initial React RUM Integration Tile.
**_Added_**:

- Initial React RUM Integration Tile.
147 changes: 117 additions & 30 deletions rum_react/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,65 +2,152 @@

## Overview

With the Datadog [React integration][1], resolve performance issues quickly in React components by:
With the Datadog RUM React integration, resolve performance issues quickly in React components by:

- Debugging the root cause of performance bottlenecks, such as a slow server response time, render-blocking resource, or an error inside a component
- Automatically correlating React performance data with user journeys, AJAX calls to the server side, and logs
- Alerting your engineering teams when crucial performance metrics for React (such as Core Web Vitals) fall below a threshold that results in a poor user experience

- Automatically correlating Web performance data with user journeys, HTTP calls, and logs
- Alerting your engineering teams when crucial Web performance metrics (such as Core Web Vitals) fall below a threshold that results in a poor user experience

Monitor your React applications from end-to-end by:

- Tracking and visualizing user journeys across your entire stack
- Debugging the root cause of slow load times, which may be an issue with your React code, network performance, or underlying infrastructure
- Debugging the root cause of slow load times, which may be an issue with your React code, network performance, or underlying infrastructure
- Analyzing and contextualizing every user session with attributes such as user ID, email, name, and more
- Unifying full-stack monitoring in one platform for frontend and backend development teams

## Setup

### Collect RUM events
First, make sure to [setup Datadog RUM][1] in your application.

To start collecting Real User Monitoring events from your React application, see [React Monitoring][2].
Then, install the `@datadog/browser-rum-react` NPM package using your package manager of choice. For example:

### Collect traces
```bash
npm install @datadog/browser-rum-react
```

Your React application automatically sends traces to Datadog.
Finally, pass the `reactPlugin` to the `plugins` option of the `datadogRum.init` method:

### Collect logs
```javascript
import { datadogRum } from '@datadog/browser-rum'
import { reactPlugin } from '@datadog/browser-rum-react'

To start forwarding your React application's logs to Datadog, see [React Log Collection][3].
datadogRum.init({
...
plugins: [reactPlugin()],
})
```

## Data Collected
## Error Tracking

### Metrics
To track React component rendering errors, use one of the following:

The React integration does not include any metrics. To generate custom metrics from your RUM application, see [Generate Metrics][4].
- An `ErrorBoundary` component (see [React documentation][1]) that catches errors and reports them to Datadog.
- A function that you can use to report errors from your own `ErrorBoundary` component.

### Events
#### `ErrorBoundary` usage

For more information about events and attributes, see [RUM React Data Collected][5].
```javascript
import { ErrorBoundary } from '@datadog/browser-rum-react'

### Service Checks
function App() {
return (
<ErrorBoundary fallback={ErrorFallback}>
<MyComponent />
</ErrorBoundary>
)
}

The React integration does not include any service checks.
function ErrorFallback({ resetError, error }: { resetError: () => void; error: unknown }) {
return (
<p>
Oops, something went wrong! <strong>{String(error)}</strong> <button onClick={resetError}>Retry</button>
</p>
)
}
```

## Troubleshooting
### Reporting React errors from your own `ErrorBoundary`

```javascript
import { addReactError } from '@datadog/browser-rum-react'

class MyErrorBoundary extends React.Component {
componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
addReactError(error, errorInfo)
}

render() {
...
}
}
```

## React Router integration

`react-router` v6 allows you to declare routes using the following methods:

- Create routers with [`createMemoryRouter`][3], [`createHashRouter`][4], or [`createBrowserRouter`][5] functions.
- Use the [`useRoutes`][6] hook.
- Use the [`Routes`][7] component.

To track route changes with the Datadog RUM Browser SDK, first initialize the `reactPlugin` with the `router: true` option, then replace those functions with their equivalent from `@datadog/browser-rum-react/react-router-v6`. Example:

```javascript
import { RouterProvider } from 'react-router-dom'
import { datadogRum } from '@datadog/browser-rum'
import { reactPlugin } from '@datadog/browser-rum-react'
// Use "createBrowserRouter" from @datadog/browser-rum-react/react-router-v6 instead of react-router-dom:
import { createBrowserRouter } from '@datadog/browser-rum-react/react-router-v6'

Need help? Contact [Datadog Support][6].
datadogRum.init({
...
plugins: [reactPlugin({ router: true })],
})

## Further Reading
const router = createBrowserRouter([
{
path: '/',
element: <Root />,
...
},
])

Additional helpful documentation, links, and articles:
ReactDOM.createRoot(document.getElementById('root')).render(<RouterProvider router={router} />)
```

## Go further with Datadog React integration

### Traces

Connect your RUM and trace data to get a complete view of your application's performance. See [Connect RUM and Traces][8].

### Logs

To start forwarding your React application's logs to Datadog, see [JavaScript Logs Collection][9].

### Metrics

To generate custom metrics from your RUM application, see [Generate Metrics][10].

## Troubleshooting

- [React Monitoring][7]
Need help? Contact [Datadog Support][11].

## Further Reading

Additional helpful documentation, links, and articles:

[1]: https://app.datadoghq.com/integrations/rum-react
[2]: https://docs.datadoghq.com/real_user_monitoring/browser/
[3]: https://docs.datadoghq.com/logs/log_collection/javascript/
[4]: https://docs.datadoghq.com/real_user_monitoring/generate_metrics
[5]: https://docs.datadoghq.com/real_user_monitoring/browser/data_collected/
[6]: https://docs.datadoghq.com/help/
[7]: https://www.datadoghq.com/blog/datadog-rum-react-components/
- [React Monitoring][12]

[1]: https://docs.datadoghq.com/real_user_monitoring/browser/setup/client
[2]: https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary
[3]: https://reactrouter.com/en/main/routers/create-memory-router
[4]: https://reactrouter.com/en/main/routers/create-hash-router
[5]: https://reactrouter.com/en/main/routers/create-browser-router
[6]: https://reactrouter.com/en/main/hooks/use-routes
[7]: https://reactrouter.com/en/main/components/routes
[8]: https://docs.datadoghq.com/real_user_monitoring/platform/connect_rum_and_traces/?tab=browserrum
[9]: https://docs.datadoghq.com/logs/log_collection/javascript/
[10]: https://docs.datadoghq.com/real_user_monitoring/generate_metrics
[11]: https://docs.datadoghq.com/help/
[12]: https://www.datadoghq.com/blog/datadog-rum-react-components/
Loading