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.

Sign up for GitHub

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

Browser Monitoring Edits #1563

Merged
merged 3 commits into from
May 25, 2022
Merged

Browser Monitoring Edits #1563

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a850c70
Doc Review
alai97 May 23, 2022
3cd06dd
Doc Review
alai97 May 24, 2022
b1481a6
Merge branch 'main' into alai97/browser-monitoring-doc-update
alai97 May 24, 2022
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
71 changes: 34 additions & 37 deletions packages/rum/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,28 +6,28 @@ Datadog Real User Monitoring (RUM) enables you to visualize and analyze the real

## Setup

To set up Datadog RUM browser monitoring:
The RUM Browser SDK supports all modern desktop and mobile browsers including IE11. For more information, see the [Browser Support][8] table.

1. In Datadog, navigate to the [Real User Monitoring page][1] and click the **New Application** button.
2. Enter a name for your application and click **Generate Client Token**. This generates a `clientToken` and an `applicationId` for your application.
3. Setup the Datadog RUM SDK via [npm](#npm) or via one of the hosted versions: [CDN async](#cdn-async) or [CDN sync](#cdn-sync).
4. Deploy the changes to your application. Once your deployment is live, Datadog collects events from user browsers.
5. Visualize the [data collected][2] using Datadog [dashboards][3].
To set up RUM Browser Monitoring:

**Note**: Your application shows up on the application list page as "pending" until Datadog starts receiving data.
1. In Datadog, navigate to the [**RUM Applications** page][1] and click the **New Application** button.
2. Enter a name for your application and click **Generate Client Token**. This generates a `clientToken` and an `applicationId` for your application.
3. Setup the RUM Browser SDK with [npm](#npm) or a hosted version ([CDN async](#cdn-async) or [CDN sync](#cdn-sync)).
4. Deploy the changes to your application. Once your deployment is live, Datadog collects events from your users' browsers.
5. Visualize the [data collected][2] in [dashboards][3] or create a search query in the [RUM Explorer][16].

**Supported browsers**: The RUM SDK supports all modern desktop and mobile browsers including IE11. See the [browser support][8] table.
Until Datadog starts to receive data, your application appears as "pending" on the **RUM Applications** page.

### Choose the right installation method

npm (node package manager)
: This method is recommended for modern web applications. The RUM SDK gets packaged with the rest of your front-end javascript code. It has no impact on page load performance. However, the SDK might miss errors, resources and user actions triggered before the SDK is initialized. **Note:** it is recommended to use a matching version with logs SDK if used.
: This method is recommended for modern web applications. The RUM Browser SDK is packaged with the rest of your front-end JavaScript code. It has no impact on page load performance. However, the SDK may miss errors, resources, and user actions triggered before the SDK is initialized. Datadog recommends using a matching version with the Browser Logs SDK if you are collecting logs.

CDN async
: This method is recommended for web applications with performance targets. The RUM SDK is loaded from our CDN asynchronously: this method ensures the SDK download does not impact page load performance. However, the SDK might miss errors, resources and user actions triggered before the SDK is initialized.
: This method is recommended for web applications with performance targets. The RUM Browser SDK loads from our CDN asynchronously, ensuring the SDK download does not impact page load performance. However, the SDK may miss errors, resources, and user actions triggered before the SDK is initialized.

CDN sync
: This method is recommended for collecting all RUM events. The RUM SDK is loaded from our CDN synchronously: this method ensures the SDK is loaded first and collects all errors, resources and user actions. This method might impact page load performance.
: This method is recommended for collecting all RUM events. The RUM Browser SDK loads from our CDN synchronously, ensuring the SDK loads first and collects all errors, resources, and user actions. This method may impact page load performance.

### npm

Expand All @@ -49,7 +49,7 @@ datadogRum.init({
})
```

**Note**: The `trackInteractions` parameter enables the automatic collection of user clicks in your application. **Sensitive and private data** contained on your pages may be included to identify the elements interacted with.
The `trackInteractions` parameter enables the automatic collection of user clicks in your application. **Sensitive and private data** contained on your pages may be included to identify the elements interacted with.

### CDN async

Expand Down Expand Up @@ -79,10 +79,9 @@ Add the generated code snippet to the head tag of every HTML page you want to mo
</script>
```

**Notes**:
The `trackInteractions` parameter enables the automatic collection of user clicks in your application. **Sensitive and private data** contained on your pages may be included to identify the elements interacted with.

- The `trackInteractions` parameter enables the automatic collection of user clicks in your application. **Sensitive and private data** contained on your pages may be included to identify the elements interacted with.
- Early RUM API calls must be wrapped in the `DD_RUM.onReady()` callback. This ensures the code only gets executed once the SDK is properly loaded.
Early RUM API calls must be wrapped in the `DD_RUM.onReady()` callback. This ensures the code only gets executed once the SDK is properly loaded.

### CDN sync

Expand All @@ -106,10 +105,9 @@ Add the generated code snippet to the head tag (in front of any other script tag
</script>
```

**Notes**:
The `trackInteractions` parameter enables the automatic collection of user clicks in your application. **Sensitive and private data** contained on your pages may be included to identify the elements interacted with.

- The `trackInteractions` parameter enables the automatic collection of user clicks in your application. **Sensitive and private data** contained on your pages may be included to identify the elements interacted with.
- The `window.DD_RUM` check is used to prevent issues if a loading failure occurs with the RUM SDK.
The `window.DD_RUM` check is used to prevent issues if a loading failure occurs with the RUM Browser SDK.

### TypeScript

Expand Down Expand Up @@ -146,22 +144,22 @@ A [Datadog client token][5].
: Required<br/>
**Type**: String<br/>
**Default**: `datadoghq.com`<br/>
The Datadog site of your organization, same value as [agent site configuration][14].
The Datadog site of your organization, the same value as the [Agent site configuration][14].

`service`
: Optional<br/>
**Type**: String<br/>
The service name for your application. It should follow the [tag syntax requirements][15].
The service name for your application. Follows the [tag syntax requirements][15].

`env`
: Optional<br/>
**Type**: String<br/>
The application’s environment, for example: prod, pre-prod, staging, etc. It should follow the [tag syntax requirements][15].
The application’s environment, for example: prod, pre-prod, and staging. Follows the [tag syntax requirements][15].

`version`
: Optional<br/>
**Type**: String<br/>
The application’s version, for example: 1.2.3, 6c44da20, 2020.02.13, etc. It should follow the [tag syntax requirements][15].
The application’s version, for example: 1.2.3, 6c44da20, and 2020.02.13. Follows the [tag syntax requirements][15].

`trackViewsManually`
: Optional<br/>
Expand Down Expand Up @@ -208,23 +206,23 @@ The percentage of tracked sessions with [Premium pricing][11] features: `100` fo
: Optional<br/>
**Type**: Boolean <br/>
**Default**: `false`<br/>
Initialization fails silently if Datadog's RUM is already initialized on the page.
Initialization fails silently if the RUM Browser SDK is already initialized on the page.

`proxyUrl`
: Optional<br/>
**Type**: String<br/>
Optional proxy URL (ex: https://www.proxy.com/path), see the full [proxy setup guide][7] for more information.
Optional proxy URL, for example: https://www.proxy.com/path. For more information, see the full [proxy setup guide][7].

`allowedTracingOrigins`
: Optional<br/>
**Type**: List<br/>
A list of request origins used to inject tracing headers. See [Connect RUM and Traces][12].
A list of request origins used to inject tracing headers. For more information, see [Connect RUM and Traces][12].

`tracingSampleRate`
: Optional<br/>
**Type**: Number<br/>
**Default**: `100`<br/>
The percentage of requests to trace: `100` for all, `0` for none. See [Connect RUM and Traces][12].
The percentage of requests to trace: `100` for all, `0` for none. For more information, see [Connect RUM and Traces][12].

`telemetrySampleRate`
: Optional<br/>
Expand Down Expand Up @@ -255,7 +253,7 @@ Use a secure session cookie. This disables RUM events sent on insecure (non-HTTP
: Optional<br/>
**Type**: Boolean<br/>
**Default**:`false`<br/>
Use a secure cross-site session cookie. This allows the RUM SDK to run when the site is loaded from another one (iframe). Implies `useSecureSessionCookie`.
Use a secure cross-site session cookie. This allows the RUM Browser SDK to run when the site is loaded from another one (iframe). Implies `useSecureSessionCookie`.

#### Example

Expand All @@ -281,20 +279,19 @@ init(configuration: {

### Browser RUM and RUM Premium sampling configuration

**Note**: This feature requires SDK v3.6.0+.
This feature requires the RUM Browser SDK v3.6.0+.

When new session is created, it can be either tracked as:
When a new session is created, it can be tracked as either:

- [**Browser RUM**][11]: **Only** _Sessions_, _Views_, _Actions_, and _Errors_ are collected. Calls to `startSessionReplayRecording()` are ignored.
- [**RUM Premium**][11]: Everything from Browser RUM plus _Resources_, _Long Tasks_, and _Replay_ recordings are collected. A call to `startSessionReplayRecording()` is needed to collect _Replay_ recordings.
- [**Browser RUM**][11]: Only _Sessions_, _Views_, _Actions_, and _Errors_ are collected. Calls to `startSessionReplayRecording()` are ignored.
- [**RUM Premium**][11]: Everything from Browser RUM, including _Resources_, _Long Tasks_, and _Replay_ recordings are collected. To collect _Replay_ recordings, call `startSessionReplayRecording()`.

Two initialization parameters are available to control how the session is tracked:

- `sampleRate` controls the percentage of overall sessions being tracked. It defaults to `100%`, so every sessions will be tracked by default.

- `premiumSampleRate` is applied **after** the overall sample rate, and controls the percentage of sessions tracked as RUM Premium. It defaults to `100%`, so every sessions will be tracked as RUM Premium by default.
- `sampleRate` controls the percentage of overall sessions being tracked. It defaults to `100%`, so every sessions is tracked by default.
- `premiumSampleRate` is applied **after** the overall sample rate, and controls the percentage of sessions tracked as RUM Premium. It defaults to `100%`, so every sessions is tracked as RUM Premium by default.

For example, to track 100% of your sessions as Browser RUM:
To track 100% of your sessions as Browser RUM:

```
datadogRum.init({
Expand All @@ -304,7 +301,7 @@ datadogRum.init({
});
```

For example, to track 100% of your sessions as RUM Premium:
To track 100% of your sessions as RUM Premium:

```
datadogRum.init({
Expand All @@ -314,7 +311,7 @@ datadogRum.init({
});
```

For example, to track only 50% of your overall sessions, with half tracked as Browser RUM and the other half tracked as RUM Premium, set the `sampleRate` and the `premiumSampleRate` to 50:
For example, to track only 50% of your overall sessions with half tracked as Browser RUM and the other half tracked as RUM Premium, set the `sampleRate` and the `premiumSampleRate` to 50:

```
datadogRum.init({
Expand Down