Skip to content

Commit

Permalink
[RUM-265] Browser SDK: add storeContextsAcrossPages option (#19731)
Browse files Browse the repository at this point in the history 
* RUM storeContextsAcrossPages

* Logs storeContextsAcrossPages

* 👌 wording

* 🐛 missing curly bracket

* 👌 update wording

* 👌 update local storage

* 👌 more local storage
  • Loading branch information
@bcaudan
bcaudan authored Sep 15, 2023
1 parent 471455c commit 5f98452
Show file tree
Hide file tree
Showing 3 changed files with 68 additions and 17 deletions.
55 changes: 39 additions & 16 deletions content/en/logs/log_collection/javascript.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -343,21 +343,22 @@ window.DD_LOGS.init({

The following parameters are available to configure the Datadog browser logs SDK to send logs to Datadog:

| Parameter | Type | Required | Default | Description |
| --------------------- | ------------------------------------------------------------------------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientToken` | String | Yes | | A [Datadog client token][2]. |
| `site` | String | Yes | `datadoghq.com` | The [Datadog site parameter of your organization][9]. |
| `service` | String | No | | The service name for your application. It should follow the [tag syntax requirements][7]. |
| `env` | String | No | | The application's environment, for example: prod, pre-prod, staging, etc. It should follow the [tag syntax requirements][7]. |
| `version` | String | No | | The application's version, for example: 1.2.3, 6c44da20, 2020.02.13, etc. It should follow the [tag syntax requirements][7]. |
| `forwardErrorsToLogs` | Boolean | No | `true` | Set to `false` to stop forwarding console.error logs, uncaught exceptions and network errors to Datadog. |
| `forwardConsoleLogs` | `"all"` or an Array of `"log"` `"debug"` `"info"` `"warn"` `"error"` | No | `[]` | Forward logs from `console.*` to Datadog. Use `"all"` to forward everything or an array of console API names to forward only a subset. |
| `forwardReports` | `"all"` or an Array of `"intervention"` `"deprecation"` `"csp_violation"` | No | `[]` | Forward reports from the [Reporting API][8] to Datadog. Use `"all"` to forward everything or an array of report types to forward only a subset. |
| `sampleRate` | Number | No | `100` | **Deprecated** - see `sessionSampleRate`. |
| `sessionSampleRate` | Number | No | `100` | The percentage of sessions to track: `100` for all, `0` for none. Only tracked sessions send logs. |
| `silentMultipleInit` | Boolean | No | | Prevent logging errors while having multiple init. |
| `proxyUrl` | String | No | | Optional proxy URL (ex: https://www.proxy.com/path), see the full [proxy setup guide][6] for more information. |
| `telemetrySampleRate` | Number | No | `20` | Telemetry data (error, debug logs) about SDK execution is sent to Datadog in order to detect and solve potential issues. Set this option to `0` to opt out from telemetry collection. |
| Parameter | Type | Required | Default | Description |
|----------------------------|---------------------------------------------------------------------------|----------|-----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `clientToken` | String | Yes | | A [Datadog client token][2]. |
| `site` | String | Yes | `datadoghq.com` | The [Datadog site parameter of your organization][9]. |
| `service` | String | No | | The service name for your application. It should follow the [tag syntax requirements][7]. |
| `env` | String | No | | The application's environment, for example: prod, pre-prod, staging, and so on. It should follow the [tag syntax requirements][7]. |
| `version` | String | No | | The application's version, for example: 1.2.3, 6c44da20, 2020.02.13, and so on. It should follow the [tag syntax requirements][7]. |
| `forwardErrorsToLogs` | Boolean | No | `true` | Set to `false` to stop forwarding console.error logs, uncaught exceptions and network errors to Datadog. |
| `forwardConsoleLogs` | `"all"` or an Array of `"log"` `"debug"` `"info"` `"warn"` `"error"` | No | `[]` | Forward logs from `console.*` to Datadog. Use `"all"` to forward everything or an array of console API names to forward only a subset. |
| `forwardReports` | `"all"` or an Array of `"intervention"` `"deprecation"` `"csp_violation"` | No | `[]` | Forward reports from the [Reporting API][8] to Datadog. Use `"all"` to forward everything or an array of report types to forward only a subset. |
| `sampleRate` | Number | No | `100` | **Deprecated** - see `sessionSampleRate`. |
| `sessionSampleRate` | Number | No | `100` | The percentage of sessions to track: `100` for all, `0` for none. Only tracked sessions send logs. |
| `silentMultipleInit` | Boolean | No | | Prevent logging errors while having multiple init. |
| `proxyUrl` | String | No | | Optional proxy URL (ex: https://www.proxy.com/path), see the full [proxy setup guide][6] for more information. |
| `telemetrySampleRate` | Number | No | `20` | Telemetry data (error, debug logs) about SDK execution is sent to Datadog in order to detect and solve potential issues. Set this option to `0` to opt out from telemetry collection. |
| `storeContextsAcrossPages` | Boolean | No | | Store global context and user context in `localStorage` to preserve them along the user navigation. See [Contexts life cycle][11] for more details and specific limitations. |

Options that must have a matching configuration when using the `RUM` SDK:

Expand Down Expand Up @@ -723,7 +724,7 @@ datadogLogs.createLogger('signupLogger', {
level: 'info',
handler: 'http',
context: { env: 'staging' }
)
})
```

It can now be used in a different part of the code with:
Expand Down Expand Up @@ -972,6 +973,26 @@ window.DD_LOGS && window.DD_LOGS.getUser() // => {}
**Note**: The `window.DD_LOGS` check prevents issues when a loading failure occurs with the SDK.
#### Contexts life cycle
By default, global context and user context are stored in the current page memory, which means they are not:
- kept after a full reload of the page
- shared across different tabs or windows of the same session
To add them to all events of the session, they must be attached to every page.
With the introduction of the `storeContextsAcrossPages` configuration option in the v4.49.0 of the browser SDK, those contexts can be stored in [`localStorage`][12], allowing the following behaviors:
- Contexts are preserved after a full reload
- Contexts are synchronized between tabs opened on the same origin
However, this feature comes with some **limitations**:
- Setting Personable Identifiable Information (PII) in those contexts is not recommended, as data stored in `localStorage` outlives the user session
- The feature is incompatible with the `trackSessionAcrossSubdomains` options because `localStorage` data is only shared among the same origin (login.site.com ≠ app.site.com)
- `localStorage` is limited to 5 MiB by origin, so the application-specific data, Datadog contexts, and other third-party data stored in `localStorage` must be within this limit to avoid any issues
#### Logger context
After a logger is created, it is possible to:
Expand Down Expand Up @@ -1158,3 +1179,5 @@ window.DD_LOGS && window.DD_LOGS.getInternalContext() // { session_id: "xxxx-xxx
[8]: https://developer.mozilla.org/en-US/docs/Web/API/Reporting_API
[9]: https://docs.datadoghq.com/getting_started/site/
[10]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error
[11]: https://docs.datadoghq.com/logs/log_collection/javascript/#contexts-life-cycle
[12]: https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage
9 changes: 8 additions & 1 deletion content/en/real_user_monitoring/browser/_index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1545,6 +1545,12 @@ A list of request origins ignored when computing the page activity. See [How pag
**Type**: String<br/>
URL pointing to the Datadog Browser SDK Worker JavaScript file. The URL can be relative or absolute, but is required to have the same origin as the web application. See [Content Security Policy guidelines][22] for more information.

`storeContextsAcrossPages`
: Optional<br/>
**Type**: String<br/>
**Default**: `false`<br/>
Store global context and user context in `localStorage` to preserve them along the user navigation. See [Contexts life cycle][24] for more details and specific limitations.

Options that must have matching configuration when you are using the Logs Browser SDK:

`trackSessionAcrossSubdomains`
Expand All @@ -1569,7 +1575,7 @@ Use a secure cross-site session cookie. This allows the RUM Browser SDK to run w
: Optional<br/>
**Type**: Boolean<br/>
**Default**: `false`<br/>
Allows the use of Local Storage when cookies cannot be set. This enables the RUM Browser SDK to run in environments that do not provide cookie support. See [Monitor Electron Applications Using the Browser SDK][23] for a typical use-case.
Allows the use of `localStorage` when cookies cannot be set. This enables the RUM Browser SDK to run in environments that do not provide cookie support. See [Monitor Electron Applications Using the Browser SDK][23] for a typical use-case.

### Tagging

Expand Down Expand Up @@ -1670,3 +1676,4 @@ window.DD_RUM && window.DD_RUM.getInternalContext() // { session_id: "xxxx", app
[21]: /real_user_monitoring/guide/sampling-browser-plans/
[22]: /integrations/content_security_policy_logs/#use-csp-with-real-user-monitoring-and-session-replay
[23]: /real_user_monitoring/guide/monitor-electron-applications-using-browser-sdk
[24]: https://docs.datadoghq.com/real_user_monitoring/browser/modifying_data_and_context#contexts-life-cycle
21 changes: 21 additions & 0 deletions content/en/real_user_monitoring/browser/modifying_data_and_context.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -927,6 +927,26 @@ const context = window.DD_RUM && window.DD_RUM.getRumGlobalContext();
{{% /tab %}}
{{< /tabs >}}

## Contexts life cycle

By default, global context and user context are stored in the current page memory, which means they are not:

- kept after a full reload of the page
- shared across different tabs or windows of the same session

To add them to all events of the session, they must be attached to every page.

With the introduction of the `storeContextsAcrossPages` configuration option in the v4.49.0 of the browser SDK, those contexts can be stored in [`localStorage`][18], allowing the following behaviors:

- Contexts are preserved after a full reload
- Contexts are synchronized between tabs opened on the same origin

However, this feature comes with some **limitations**:

- Setting Personable Identifiable Information (PII) in those contexts is not recommended, as data stored in `localStorage` outlives the user session
- The feature is incompatible with the `trackSessionAcrossSubdomains` options because `localStorage` data is only shared among the same origin (login.site.com ≠ app.site.com)
- `localStorage` is limited to 5 MiB by origin, so the application-specific data, Datadog contexts, and other third-party data stored in local storage must be within this limit to avoid any issues

## Further Reading

{{< partial name="whats-next/whats-next.html" >}}
Expand All @@ -948,3 +968,4 @@ const context = window.DD_RUM && window.DD_RUM.getRumGlobalContext();
[15]: https://github.com/DataDog/browser-sdk/blob/main/packages/rum-core/src/rumEvent.types.ts
[16]: /logs/log_configuration/attributes_naming_convention/#user-related-attributes
[17]: https://github.com/DataDog/browser-sdk/blob/main/CHANGELOG.md#v4130
[18]: https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage

0 comments on commit 5f98452

Please sign in to comment.