diff --git a/.vscode/markdoc.code-snippets b/.vscode/markdoc.code-snippets index 83ddc3e8d83..2832b0add2a 100644 --- a/.vscode/markdoc.code-snippets +++ b/.vscode/markdoc.code-snippets @@ -70,6 +70,19 @@ "description": "Markdoc if tag with equals condition" }, + "Version": { + "scope": "markdoc", + "prefix": ";;version", + "body": [ + "", + "{% if semverIsAtLeast($${2:semver_trait_id}, \"${1:version}\") %}", + "${3:Content shown if version is met}", + "{% /if %}", + "" + ], + "description": "Show content that meets a semantic version" + }, + "Image": { "scope": "markdoc", "prefix": ";;image", @@ -81,7 +94,7 @@ "Video": { "scope": "markdoc", - "prefix": ";;;video", + "prefix": ";;video", "body": ["{% img src=\"${1:path/to/video.mp4}\" alt=\"${2:Descriptive video alt text}\" video=\"true\" /%}"], "description": "Markdoc video tag using img with video attribute" }, diff --git a/content/.gitignore b/content/.gitignore index 3b0ac6221bf..6eaf8607e67 100644 --- a/content/.gitignore +++ b/content/.gitignore @@ -6,6 +6,7 @@ # This file lists compiled Cdocs files to keep them out of version control. For more information, see the internal Cdocs documentation: https://datadoghq.atlassian.net/wiki/spaces/docs4docs/pages/4898063037/Cdocs+Build /en/opentelemetry/instrument/dd_sdks/api_support.md +/en/real_user_monitoring/application_monitoring/browser/advanced_configuration.md /en/real_user_monitoring/correlate_with_other_telemetry/profiling/_index.md /en/real_user_monitoring/guide/proxy-mobile-rum-data.md /en/real_user_monitoring/guide/proxy-rum-data.md diff --git a/content/en/real_user_monitoring/application_monitoring/browser/advanced_configuration.md b/content/en/real_user_monitoring/application_monitoring/browser/advanced_configuration.mdoc.md similarity index 67% rename from content/en/real_user_monitoring/application_monitoring/browser/advanced_configuration.md rename to content/en/real_user_monitoring/application_monitoring/browser/advanced_configuration.mdoc.md index de22fc875cc..4b1b9ef0d33 100644 --- a/content/en/real_user_monitoring/application_monitoring/browser/advanced_configuration.md +++ b/content/en/real_user_monitoring/application_monitoring/browser/advanced_configuration.mdoc.md @@ -5,6 +5,12 @@ aliases: - /real_user_monitoring/installation/advanced_configuration/ - /real_user_monitoring/browser/modifying_data_and_context/ - /real_user_monitoring/browser/advanced_configuration/ +content_filters: + - trait_id: lib_src + option_group_id: rum_browser_sdk_source_options + - trait_id: rum_browser_sdk_version + option_group_id: rum_browser_sdk_version_for_advanced_config_options + further_reading: - link: "/real_user_monitoring/application_monitoring/browser/tracking_user_actions" tag: Documentation @@ -35,127 +41,118 @@ There are various ways you can modify the [data and context collected][1] by RUM - Reducing how much RUM data you're collecting, through sampling the data. - Providing more context than what the default attributes provide about where the data is coming from. + +{% if semverIsAtLeast($rum_browser_sdk_version, "2.17.0") %} + ## Override default RUM view names +Starting with [version 2.17.0][3], you can add view names and assign them to a dedicated service owned by a team by tracking view events manually with the `trackViewsManually` option. + The RUM Browser SDK automatically generates a [view event][2] for each new page visited by your users, or when the page URL is changed (for single-page applications). A view name is computed from the current page URL, where variable IDs are removed automatically. A path segment that contains at least one number is considered a variable ID. For example, `/dashboard/1234` and `/dashboard/9a` become `/dashboard/?`. -Starting with [version 2.17.0][3], you can add view names and assign them to a dedicated service owned by a team by tracking view events manually with the `trackViewsManually` option: +To override default RUM view names: 1. Set `trackViewsManually` to true when initializing the RUM Browser SDK. - {{< tabs >}} - {{% tab "NPM" %}} - + + {% if equals($lib_src, "npm") %} ```javascript import { datadogRum } from '@datadog/browser-rum'; datadogRum.init({ - ..., - trackViewsManually: true, - ... + ..., + trackViewsManually: true, + ... }); ``` + {% /if %} + - {{% /tab %}} - {{% tab "CDN async" %}} - - + + {% if equals($lib_src, "cdn_async") %} ```javascript window.DD_RUM.onReady(function() { - window.DD_RUM.init({ - ..., - trackViewsManually: true, - ... - }) + window.DD_RUM.init({ + ..., + trackViewsManually: true, + ... + }) }) ``` + {% /if %} + - {{% /tab %}} - {{% tab "CDN sync" %}} - - + + {% if equals($lib_src, "cdn_sync") %} ```javascript window.DD_RUM && - window.DD_RUM.init({ - ..., - trackViewsManually: true, - ... - }); + window.DD_RUM.init({ + ..., + trackViewsManually: true, + ... + }); ``` + {% /if %} + +2. You must start views for each new page or route change (for single-page applications). RUM data is collected when the view starts. +{% /if %} + - {{% /tab %}} - {{< /tabs >}} -2. You must start views for each new page or route change (for single-page applications). RUM data is collected when the view starts. Starting with [version 4.13.0][16], you can also optionally define the associated service name and version. + +{% if semverIsAtLeast($rum_browser_sdk_version, "4.13.0") %} - - View Name: Defaults to the page URL path. - - Service: Defaults to the default service specified when creating your RUM application. - - Version: Defaults to the default version specified when creating your RUM application. - - Context: Starting with [version 5.28.0][19], you can add context to views and the child events of views. +### Define service name and version - For more information, see [Setup Browser Monitoring][4]. +Starting with [version 4.13.0][16], you can also optionally define the associated service name and version. -
- Latest version - The following example manually tracks the pageviews on the checkout page in a RUM application. Use checkout for the view name and associate the purchase service with version 1.2.3. +- **View Name**: Defaults to the page URL path. +- **Service**: Defaults to the default service specified when creating your RUM application. +- **Version**: Defaults to the default version specified when creating your RUM application. +{% /if %} + - {{< tabs >}} - {{% tab "NPM" %}} + - ```javascript - datadogRum.startView({ - name: 'checkout', - service: 'purchase', - version: '1.2.3', - context: { - payment: 'Done' - }, - }) - ``` + +{% if or(equals($rum_browser_sdk_version, "lt_2_13_0"), equals($rum_browser_sdk_version, "gte_2_13_0"), equals($rum_browser_sdk_version, "gte_2_17_0")) %} - {{% /tab %}} - {{% tab "CDN async" %}} +## Manually track pageviews +The following example manually tracks the pageviews on the `checkout` page in a RUM application. No service or version can be specified. - ```javascript - window.DD_RUM.onReady(function() { - window.DD_RUM.startView({ - name: 'checkout', - service: 'purchase', - version: '1.2.3', - context: { - payment: 'Done' - }, - }) - }) - ``` - - {{% /tab %}} - {{% tab "CDN sync" %}} - + +{% if equals($lib_src, "npm") %} +```javascript +datadogRum.startView('checkout') +``` +{% /if %} - ```javascript - window.DD_RUM && window.DD_RUM.startView({ - name: 'checkout', - service: 'purchase', - version: '1.2.3', - context: { - payment: 'Done' - }, - }) - ``` + +{% if equals($lib_src, "cdn_async") %} +```javascript +window.DD_RUM.onReady(function() { + window.DD_RUM.startView('checkout') +}) +``` +{% /if %} - {{% /tab %}} - {{< /tabs >}} + +{% if equals($lib_src, "cdn_sync") %} +```javascript +window.DD_RUM && window.DD_RUM.startView('checkout') +``` +{% /if %} +{% /if %} + -
-
-before v5.28.0 -The following example manually tracks the pageviews on the checkout page in a RUM application. It uses checkout for the view name and associates the purchase service with version 1.2.3. + +{% if or(equals($rum_browser_sdk_version, "gte_4_13_0"), equals($rum_browser_sdk_version, "gte_4_49_0"), equals($rum_browser_sdk_version, "gte_5_22_0")) %} -{{< tabs >}} -{{% tab "NPM" %}} +The following example manually tracks the pageviews on the `checkout` page in a RUM application. It uses `checkout` for the view name and associates the `purchase` service with version `1.2.3`. + +{% if equals($lib_src, "npm") %} ```javascript datadogRum.startView({ name: 'checkout', @@ -163,11 +160,10 @@ datadogRum.startView({ version: '1.2.3' }) ``` +{% /if %} -{{% /tab %}} -{{% tab "CDN async" %}} - - + +{% if equals($lib_src, "cdn_async") %} ```javascript window.DD_RUM.onReady(function() { window.DD_RUM.startView({ @@ -177,10 +173,10 @@ window.DD_RUM.onReady(function() { }) }) ``` +{% /if %} -{{% /tab %}} -{{% tab "CDN sync" %}} - + +{% if equals($lib_src, "cdn_sync") %} ```javascript window.DD_RUM && window.DD_RUM.startView({ @@ -189,49 +185,74 @@ window.DD_RUM && window.DD_RUM.startView({ version: '1.2.3' }) ``` +{% /if %} +{% /if %} + + -{{% /tab %}} -{{< /tabs >}} -
+ +{% if semverIsAtLeast($rum_browser_sdk_version, "5.28.0") %} -
- before v4.13.0 - The following example manually tracks the pageviews on the checkout page in a RUM application. No service or version can be specified. +- **Context**: Starting with [version 5.28.0][19], you can add context to views and the child events of views. - {{< tabs >}} - {{% tab "NPM" %}} +The following example manually tracks the pageviews on the `checkout` page in a RUM application. Use `checkout` for the view name and associate the `purchase` service with version `1.2.3`. + + {% if equals($lib_src, "npm") %} ```javascript - datadogRum.startView('checkout') + datadogRum.startView({ + name: 'checkout', + service: 'purchase', + version: '1.2.3', + context: { + payment: 'Done' + }, + }) ``` + {% /if %} + - {{% /tab %}} - {{% tab "CDN async" %}} - - + + {% if equals($lib_src, "cdn_async") %} ```javascript window.DD_RUM.onReady(function() { - window.DD_RUM.startView('checkout') + window.DD_RUM.startView({ + name: 'checkout', + service: 'purchase', + version: '1.2.3', + context: { + payment: 'Done' + }, + }) }) ``` + {% /if %} + - {{% /tab %}} - {{% tab "CDN sync" %}} - - + + {% if equals($lib_src, "cdn_sync") %} ```javascript - window.DD_RUM && window.DD_RUM.startView('checkout') + window.DD_RUM && window.DD_RUM.startView({ + name: 'checkout', + service: 'purchase', + version: '1.2.3', + context: { + payment: 'Done' + }, + }) ``` + {% /if %} + +{% /if %} + - {{% /tab %}} - {{< /tabs >}} + +{% if semverIsAtLeast($rum_browser_sdk_version, "2.17.0") %} -
+### React router instrumentation If you are using React, Angular, Vue, or any other frontend framework, Datadog recommends implementing the `startView` logic at the framework router level. -### React router instrumentation - To override default RUM view names so that they are aligned with how you've defined them in your React application, you need to follow the below steps. **Note**: These instructions are specific to the **React Router v6** library. @@ -239,200 +260,197 @@ To override default RUM view names so that they are aligned with how you've defi 1. Set `trackViewsManually` to `true` when initializing the RUM browser SDK as described [above](#override-default-rum-view-names). 2. Start views for each route change. - - {{< tabs >}} - {{% tab "NPM" %}} - + + {% if equals($lib_src, "npm") %} ```javascript - import { matchRoutes, useLocation } from 'react-router-dom'; - import { routes } from 'path/to/routes'; - import { datadogRum } from "@datadog/browser-rum"; - - export default function App() { - // Track every route change with useLocation API - let location = useLocation(); - - useEffect(() => { - const routeMatches = matchRoutes(routes, location.pathname); - const viewName = routeMatches && computeViewName(routeMatches); - if (viewName) { - datadogRum.startView({name: viewName}); - } - }, [location.pathname]); - - ... + import { matchRoutes, useLocation } from 'react-router-dom'; + import { routes } from 'path/to/routes'; + import { datadogRum } from "@datadog/browser-rum"; + + export default function App() { + // Track every route change with useLocation API + let location = useLocation(); + + useEffect(() => { + const routeMatches = matchRoutes(routes, location.pathname); + const viewName = routeMatches && computeViewName(routeMatches); + if (viewName) { + datadogRum.startView({name: viewName}); } - - // Compute view name out of routeMatches - function computeViewName(routeMatches) { - let viewName = ""; - for (let index = 0; index < routeMatches.length; index++) { - const routeMatch = routeMatches[index]; - const path = routeMatch.route.path; - // Skip pathless routes - if (!path) { - continue; - } - - if (path.startsWith("/")) { - // Handle absolute child route paths - viewName = path; - } else { - // Handle route paths ending with "/" - viewName += viewName.endsWith("/") ? path : `/${path}`; - } - } - - return viewName || '/'; + }, [location.pathname]); + + ... + } + + // Compute view name out of routeMatches + function computeViewName(routeMatches) { + let viewName = ""; + for (let index = 0; index < routeMatches.length; index++) { + const routeMatch = routeMatches[index]; + const path = routeMatch.route.path; + // Skip pathless routes + if (!path) { + continue; } - ``` - {{% /tab %}} - {{% tab "CDN async" %}} + if (path.startsWith("/")) { + // Handle absolute child route paths + viewName = path; + } else { + // Handle route paths ending with "/" + viewName += viewName.endsWith("/") ? path : `/${path}`; + } + } + return viewName || '/'; + } + ``` + {% /if %} + + {% if equals($lib_src, "cdn_async") %} ```javascript - import { matchRoutes, useLocation } from 'react-router-dom'; - import { routes } from 'path/to/routes'; - - export default function App() { - // Track every route change with useLocation API - let location = useLocation(); - - useEffect(() => { - const routeMatches = matchRoutes(routes, location.pathname); - const viewName = routeMatches && computeViewName(routeMatches); - if (viewName) { - DD_RUM.onReady(function() { - DD_RUM.startView({name: viewName}); - }); - } - }, [location.pathname]); - - ... + import { matchRoutes, useLocation } from 'react-router-dom'; + import { routes } from 'path/to/routes'; + + export default function App() { + // Track every route change with useLocation API + let location = useLocation(); + + useEffect(() => { + const routeMatches = matchRoutes(routes, location.pathname); + const viewName = routeMatches && computeViewName(routeMatches); + if (viewName) { + DD_RUM.onReady(function() { + DD_RUM.startView({name: viewName}); + }); } - - // Compute view name out of routeMatches - function computeViewName(routeMatches) { - let viewName = ""; - for (let index = 0; index < routeMatches.length; index++) { - const routeMatch = routeMatches[index]; - const path = routeMatch.route.path; - // Skip pathless routes - if (!path) { - continue; - } - - if (path.startsWith("/")) { - // Handle absolute child route paths - viewName = path; - } else { - // Handle route paths ending with "/" - viewName += viewName.endsWith("/") ? path : `/${path}`; - } - } - - return viewName || '/'; + }, [location.pathname]); + + ... + } + + // Compute view name out of routeMatches + function computeViewName(routeMatches) { + let viewName = ""; + for (let index = 0; index < routeMatches.length; index++) { + const routeMatch = routeMatches[index]; + const path = routeMatch.route.path; + // Skip pathless routes + if (!path) { + continue; } - ``` - {{% /tab %}} - {{% tab "CDN sync" %}} + if (path.startsWith("/")) { + // Handle absolute child route paths + viewName = path; + } else { + // Handle route paths ending with "/" + viewName += viewName.endsWith("/") ? path : `/${path}`; + } + } + return viewName || '/'; + } + ``` + {% /if %} + + {% if equals($lib_src, "cdn_sync") %} ```javascript - import { matchRoutes, useLocation } from 'react-router-dom'; - import { routes } from 'path/to/routes'; - - export default function App() { - // Track every route change with useLocation API - let location = useLocation(); - - useEffect(() => { - const routeMatches = matchRoutes(routes, location.pathname); - const viewName = routeMatches && computeViewName(routeMatches); - if (viewName) { - window.DD_RUM && - window.DD_RUM.startView({name: viewName}); - } - }, [location.pathname]); - - ... + import { matchRoutes, useLocation } from 'react-router-dom'; + import { routes } from 'path/to/routes'; + + export default function App() { + // Track every route change with useLocation API + let location = useLocation(); + + useEffect(() => { + const routeMatches = matchRoutes(routes, location.pathname); + const viewName = routeMatches && computeViewName(routeMatches); + if (viewName) { + window.DD_RUM && + window.DD_RUM.startView({name: viewName}); + } + }, [location.pathname]); + + ... + } + + // Compute view name out of routeMatches + function computeViewName(routeMatches) { + let viewName = ""; + for (let index = 0; index < routeMatches.length; index++) { + const routeMatch = routeMatches[index]; + const path = routeMatch.route.path; + // Skip pathless routes + if (!path) { + continue; } - // Compute view name out of routeMatches - function computeViewName(routeMatches) { - let viewName = ""; - for (let index = 0; index < routeMatches.length; index++) { - const routeMatch = routeMatches[index]; - const path = routeMatch.route.path; - // Skip pathless routes - if (!path) { - continue; - } - - if (path.startsWith("/")) { - // Handle absolute child route paths - viewName = path; - } else { - // Handle route paths ending with "/" - viewName += viewName.endsWith("/") ? path : `/${path}`; - } - } - - return viewName || '/'; + if (path.startsWith("/")) { + // Handle absolute child route paths + viewName = path; + } else { + // Handle route paths ending with "/" + viewName += viewName.endsWith("/") ? path : `/${path}`; + } } - ``` - {{% /tab %}} - {{< /tabs >}} + return viewName || '/'; + } + ``` + {% /if %} +{% /if %} + + +{% if semverIsAtLeast($rum_browser_sdk_version, "2.17.0") %} ### Set view name Use `setViewName(name: string)` to update the name of the current view. This allows you to change the view name during the view without starting a new one. + + {% if equals($lib_src, "npm") %} + ```javascript + import { datadogRum } from '@datadog/browser-rum'; -{{< tabs >}} -{{% tab "NPM" %}} - -```javascript -import { datadogRum } from '@datadog/browser-rum'; - -datadogRum.setViewName(''); - -// Code example -datadogRum.setViewName('Checkout'); -``` - -{{% /tab %}} - {{% tab "CDN async" %}} - + datadogRum.setViewName(''); -```javascript -window.DD_RUM.onReady(function() { - window.DD_RUM.setViewName(''); -}) + // Code example + datadogRum.setViewName('Checkout'); + ``` + {% /if %} -// Code example -window.DD_RUM.onReady(function() { - window.DD_RUM.setViewName('Checkout'); -}) -``` + + {% if equals($lib_src, "cdn_async") %} + ```javascript + window.DD_RUM.onReady(function() { + window.DD_RUM.setViewName(''); + }) -{{% /tab %}} - {{% tab "CDN sync" %}} + // Code example + window.DD_RUM.onReady(function() { + window.DD_RUM.setViewName('Checkout'); + }) + ``` + {% /if %} + + {% if equals($lib_src, "cdn_sync") %} + ```javascript + window.DD_RUM && window.DD_RUM.setViewName(''); -```javascript -window.DD_RUM && window.DD_RUM.setViewName(''); + // Code example + window.DD_RUM && window.DD_RUM.setViewName('Checkout'); + ``` + {% /if %} -// Code example -window.DD_RUM && window.DD_RUM.setViewName('Checkout'); -``` +**Note**: Changing the view name affects the view and its child events from the time the method is called. +{% /if %} + -{{% /tab %}} -{{< /tabs >}} +For more information, see [Setup Browser Monitoring][4]. -**Note**: Changing the view name affects the view and its child events from the time the method is called. ## Enrich and control RUM data @@ -444,6 +462,8 @@ Intercepting the RUM events allows you to: - Modify your RUM events to alter their content or redact sensitive sequences (see [list of editable properties](#modify-the-content-of-a-rum-event)) - Discard selected RUM events + +{% if semverIsAtLeast($rum_browser_sdk_version, "2.13.0") %} Starting with [version 2.13.0][5], `beforeSend` takes two arguments: the `event` generated by the RUM Browser SDK, and the `context` that triggered the creation of the RUM event. ```javascript @@ -463,71 +483,67 @@ The potential `context` values are: | Long Task | [PerformanceLongTaskTiming][13] | For more information, see the [Enrich and control RUM data guide][14]. +{% /if %} + ### Enrich RUM events Along with attributes added with the [Global Context API](#global-context) or the [Feature Flag data collection](#enrich-rum-events-with-feature-flags), you can add additional context attributes to the event. For example, tag your RUM resource events with data extracted from a fetch response object: + + {% if equals($lib_src, "npm") %} + ```javascript + import { datadogRum } from '@datadog/browser-rum'; -{{< tabs >}} -{{% tab "NPM" %}} - -```javascript -import { datadogRum } from '@datadog/browser-rum'; - -datadogRum.init({ - ..., - beforeSend: (event, context) => { - // collect a RUM resource's response headers - if (event.type === 'resource' && event.resource.type === 'fetch') { - event.context.responseHeaders = Object.fromEntries(context.response.headers) - } - return true - }, - ... -}); -``` - -{{% /tab %}} - {{% tab "CDN async" %}} - - -```javascript -window.DD_RUM.onReady(function() { - window.DD_RUM.init({ - ..., - beforeSend: (event, context) => { - // collect a RUM resource's response headers - if (event.type === 'resource' && event.resource.type === 'fetch') { - event.context.responseHeaders = Object.fromEntries(context.response.headers) - } - return true - }, - ... - }) -}) -``` - -{{% /tab %}} - {{% tab "CDN sync" %}} - + datadogRum.init({ + ..., + beforeSend: (event, context) => { + // collect a RUM resource's response headers + if (event.type === 'resource' && event.resource.type === 'fetch') { + event.context.responseHeaders = Object.fromEntries(context.response.headers) + } + return true + }, + ... + }); + ``` + {% /if %} -```javascript -window.DD_RUM && - window.DD_RUM.init({ - ..., - beforeSend: (event, context) => { - // collect a RUM resource's response headers - if (event.type === 'resource' && event.resource.type === 'fetch') { - event.context.responseHeaders = Object.fromEntries(context.response.headers) - } - return true - }, - ... - }); -``` + + {% if equals($lib_src, "cdn_async") %} + ```javascript + window.DD_RUM.onReady(function() { + window.DD_RUM.init({ + ..., + beforeSend: (event, context) => { + // collect a RUM resource's response headers + if (event.type === 'resource' && event.resource.type === 'fetch') { + event.context.responseHeaders = Object.fromEntries(context.response.headers) + } + return true + }, + ... + }) + }) + ``` + {% /if %} -{{% /tab %}} -{{< /tabs >}} + + {% if equals($lib_src, "cdn_sync") %} + ```javascript + window.DD_RUM && + window.DD_RUM.init({ + ..., + beforeSend: (event, context) => { + // collect a RUM resource's response headers + if (event.type === 'resource' && event.resource.type === 'fetch') { + event.context.responseHeaders = Object.fromEntries(context.response.headers) + } + return true + }, + ... + }); + ``` + {% /if %} If a user belongs to multiple teams, add additional key-value pairs in your calls to the Global Context API. @@ -540,58 +556,52 @@ You can [enrich your RUM event data with feature flags][14] to get additional co ### Modify the content of a RUM event For example, to redact email addresses from your web application URLs: + + {% if equals($lib_src, "npm") %} + ```javascript + import { datadogRum } from '@datadog/browser-rum'; -{{< tabs >}} -{{% tab "NPM" %}} - -```javascript -import { datadogRum } from '@datadog/browser-rum'; - -datadogRum.init({ - ..., - beforeSend: (event) => { - // remove email from view url - event.view.url = event.view.url.replace(/email=[^&]*/, "email=REDACTED") - }, - ... -}); -``` - -{{% /tab %}} - {{% tab "CDN async" %}} - - -```javascript -window.DD_RUM.onReady(function() { - window.DD_RUM.init({ - ..., - beforeSend: (event) => { - // remove email from view url - event.view.url = event.view.url.replace(/email=[^&]*/, "email=REDACTED") - }, - ... - }) -}) -``` - -{{% /tab %}} - {{% tab "CDN sync" %}} - + datadogRum.init({ + ..., + beforeSend: (event) => { + // remove email from view url + event.view.url = event.view.url.replace(/email=[^&]*/, "email=REDACTED") + }, + ... + }); + ``` + {% /if %} -```javascript -window.DD_RUM && - window.DD_RUM.init({ - ..., - beforeSend: (event) => { - // remove email from view url - event.view.url = event.view.url.replace(/email=[^&]*/, "email=REDACTED") - }, - ... - }); -``` + + {% if equals($lib_src, "cdn_async") %} + ```javascript + window.DD_RUM.onReady(function() { + window.DD_RUM.init({ + ..., + beforeSend: (event) => { + // remove email from view url + event.view.url = event.view.url.replace(/email=[^&]*/, "email=REDACTED") + }, + ... + }) + }) + ``` + {% /if %} -{{% /tab %}} -{{< /tabs >}} + + {% if equals($lib_src, "cdn_sync") %} + ```javascript + window.DD_RUM && + window.DD_RUM.init({ + ..., + beforeSend: (event) => { + // remove email from view url + event.view.url = event.view.url.replace(/email=[^&]*/, "email=REDACTED") + }, + ... + }); + ``` + {% /if %} You can update the following event properties: @@ -629,29 +639,26 @@ beforeSend: (event) => { ### Discard a RUM event With the `beforeSend` API, discard a RUM event by returning `false`: - -{{< tabs >}} -{{% tab "NPM" %}} - + +{% if equals($lib_src, "npm") %} ```javascript import { datadogRum } from '@datadog/browser-rum'; datadogRum.init({ - ..., - beforeSend: (event) => { - if (shouldDiscard(event)) { - return false - } - ... - }, - ... + ..., + beforeSend: (event) => { + if (shouldDiscard(event)) { + return false + } + ... + }, + ... }); ``` +{% /if %} -{{% /tab %}} - {{% tab "CDN async" %}} - - + +{% if equals($lib_src, "cdn_async") %} ```javascript window.DD_RUM.onReady(function() { window.DD_RUM.init({ @@ -666,11 +673,10 @@ window.DD_RUM.onReady(function() { }) }) ``` +{% /if %} -{{% /tab %}} - {{% tab "CDN sync" %}} - - + +{% if equals($lib_src, "cdn_sync") %} ```javascript window.DD_RUM && window.DD_RUM.init({ @@ -684,9 +690,7 @@ window.DD_RUM && ... }); ``` - -{{% /tab %}} -{{< /tabs >}} +{% /if %} **Note**: View events cannot be discarded. @@ -698,23 +702,23 @@ Adding user information to your RUM sessions helps you: - Know which users are the most impacted by errors - Monitor performance for your most important users -{{< img src="real_user_monitoring/browser/advanced_configuration/user-api.png" alt="User API in RUM UI" >}} - -{{< tabs >}} -{{% tab "v6.4.0 and above" %}} +{% img src="real_user_monitoring/browser/advanced_configuration/user-api.png" alt="User API in RUM UI" /%} -The following attributes are available: + +{% if semverIsAtLeast($rum_browser_sdk_version, "6.4.0") %} +In versions 6.4.0 and above, the following attributes are available: | Attribute | Type | Required | Description | |------------|------|------|----------------------------------------------------------------------------------------------------| | `usr.id` | String | Yes | Unique user identifier. | | `usr.name` | String | No | User friendly name, displayed by default in the RUM UI. | | `usr.email` | String | No | User email, displayed in the RUM UI if the user name is not present. It is also used to fetch Gravatars. | +{% /if %} + -{{% /tab %}} -{{% tab "Below v6.4.0" %}} - -The below attributes are optional but Datadog strongly recommends providing at least one of them. For example, you should set the user ID on your sessions to see relevant data on some default RUM dashboards, which rely on `usr.id` as part of the query. + +{% if not(semverIsAtLeast($rum_browser_sdk_version, "6.4.0")) %} +The below attributes are optional in versions before 6.4.0, but Datadog strongly recommends providing at least one of them. For example, you should set the user ID on your sessions to see relevant data on some default RUM dashboards, which rely on `usr.id` as part of the query. | Attribute | Type | Description | |------------|------|----------------------------------------------------------------------------------------------------| @@ -722,9 +726,6 @@ The below attributes are optional but Datadog strongly recommends providing at l | `usr.name` | String | User friendly name, displayed by default in the RUM UI. | | `usr.email` | String | User email, displayed in the RUM UI if the user name is not present. It is also used to fetch Gravatars. | -{{% /tab %}} -{{< /tabs >}} - **Note**: 'Public User' is displayed in the RUM UI when `usr.name` is not set, even if `usr.email` and `usr.id` are defined. Increase your filtering capabilities by adding extra attributes on top of the recommended ones. For instance, add information about the user plan, or which user group they belong to. @@ -732,14 +733,14 @@ Increase your filtering capabilities by adding extra attributes on top of the re When making changes to the user session object, all RUM events collected after the change contain the updated information. **Note**: Deleting the user session information, as in a logout, retains the user information on the last view before the logout, but not on later views or the session level as the session data uses the last view's values. +{% /if %} + ### Identify user session `datadogRum.setUser()` - -{{< tabs >}} -{{% tab "NPM" %}} - + +{% if equals($lib_src, "npm") %} ```javascript datadogRum.setUser({ id: '1234', @@ -749,11 +750,10 @@ datadogRum.setUser({ ... }) ``` +{% /if %} -{{% /tab %}} - {{% tab "CDN async" %}} - - + +{% if equals($lib_src, "cdn_async") %} ```javascript window.DD_RUM.onReady(function() { window.DD_RUM.setUser({ @@ -765,11 +765,10 @@ window.DD_RUM.onReady(function() { }) }) ``` +{% /if %} -{{% /tab %}} - {{% tab "CDN sync" %}} - - + +{% if equals($lib_src, "cdn_sync") %} ```javascript window.DD_RUM && window.DD_RUM.setUser({ id: '1234', @@ -779,137 +778,111 @@ window.DD_RUM && window.DD_RUM.setUser({ ... }) ``` - -{{% /tab %}} -{{< /tabs >}} +{% /if %} ### Access user session `datadogRum.getUser()` - -{{< tabs >}} -{{% tab "NPM" %}} - + +{% if equals($lib_src, "npm") %} ```javascript datadogRum.getUser() ``` +{% /if %} -{{% /tab %}} - {{% tab "CDN async" %}} - - + +{% if equals($lib_src, "cdn_async") %} ```javascript window.DD_RUM.onReady(function() { window.DD_RUM.getUser() }) ``` +{% /if %} -{{% /tab %}} - {{% tab "CDN sync" %}} - - + +{% if equals($lib_src, "cdn_sync") %} ```javascript window.DD_RUM && window.DD_RUM.getUser() ``` - -{{% /tab %}} -{{< /tabs >}} +{% /if %} ### Add/Override user session property `datadogRum.setUserProperty('', )` - -{{< tabs >}} -{{% tab "NPM" %}} - + +{% if equals($lib_src, "npm") %} ```javascript datadogRum.setUserProperty('name', 'John Doe') ``` +{% /if %} -{{% /tab %}} - {{% tab "CDN async" %}} - - + +{% if equals($lib_src, "cdn_async") %} ```javascript window.DD_RUM.onReady(function() { window.DD_RUM.setUserProperty('name', 'John Doe') }) ``` +{% /if %} -{{% /tab %}} - {{% tab "CDN sync" %}} - - + +{% if equals($lib_src, "cdn_sync") %} ```javascript window.DD_RUM && window.DD_RUM.setUserProperty('name', 'John Doe') ``` - -{{% /tab %}} -{{< /tabs >}} +{% /if %} ### Remove user session property `datadogRum.removeUserProperty('')` - -{{< tabs >}} -{{% tab "NPM" %}} - + +{% if equals($lib_src, "npm") %} ```javascript datadogRum.removeUserProperty('name') ``` +{% /if %} -{{% /tab %}} - {{% tab "CDN async" %}} - - + +{% if equals($lib_src, "cdn_async") %} ```javascript window.DD_RUM.onReady(function() { window.DD_RUM.removeUserProperty('name') }) ``` +{% /if %} -{{% /tab %}} - {{% tab "CDN sync" %}} - - + +{% if equals($lib_src, "cdn_sync") %} ```javascript window.DD_RUM && window.DD_RUM.removeUserProperty('name') ``` - -{{% /tab %}} -{{< /tabs >}} +{% /if %} ### Clear user session property `datadogRum.clearUser()` - -{{< tabs >}} -{{% tab "NPM" %}} - + +{% if equals($lib_src, "npm") %} ```javascript datadogRum.clearUser() ``` +{% /if %} -{{% /tab %}} - {{% tab "CDN async" %}} - - + +{% if equals($lib_src, "cdn_async") %} ```javascript window.DD_RUM.onReady(function() { window.DD_RUM.clearUser() }) ``` +{% /if %} -{{% /tab %}} - {{% tab "CDN sync" %}} - - + +{% if equals($lib_src, "cdn_sync") %} ```javascript window.DD_RUM && window.DD_RUM.clearUser() ``` - -{{% /tab %}} -{{< /tabs >}} +{% /if %} ## Account @@ -925,10 +898,8 @@ The following attributes are available: ### Identify account `datadogRum.setAccount()` - -{{< tabs >}} -{{% tab "NPM" %}} - + +{% if equals($lib_src, "npm") %} ```javascript datadogRum.setAccount({ id: '1234', @@ -936,11 +907,10 @@ datadogRum.setAccount({ ... }) ``` +{% /if %} -{{% /tab %}} - {{% tab "CDN async" %}} - - + +{% if equals($lib_src, "cdn_async") %} ```javascript window.DD_RUM.onReady(function() { window.DD_RUM.setAccount({ @@ -950,11 +920,10 @@ window.DD_RUM.onReady(function() { }) }) ``` +{% /if %} -{{% /tab %}} - {{% tab "CDN sync" %}} - - + +{% if equals($lib_src, "cdn_sync") %} ```javascript window.DD_RUM && window.DD_RUM.setAccount({ id: '1234', @@ -962,147 +931,119 @@ window.DD_RUM && window.DD_RUM.setAccount({ ... }) ``` - -{{% /tab %}} -{{< /tabs >}} +{% /if %} ### Access account `datadogRum.getAccount()` - -{{< tabs >}} -{{% tab "NPM" %}} - + +{% if equals($lib_src, "npm") %} ```javascript datadogRum.getAccount() ``` +{% /if %} -{{% /tab %}} - {{% tab "CDN async" %}} - - + +{% if equals($lib_src, "cdn_async") %} ```javascript window.DD_RUM.onReady(function() { window.DD_RUM.getAccount() }) ``` +{% /if %} -{{% /tab %}} - {{% tab "CDN sync" %}} - - + +{% if equals($lib_src, "cdn_sync") %} ```javascript window.DD_RUM && window.DD_RUM.getAccount() ``` - -{{% /tab %}} -{{< /tabs >}} +{% /if %} ### Add/Override account property `datadogRum.setAccountProperty('', )` - -{{< tabs >}} -{{% tab "NPM" %}} - + +{% if equals($lib_src, "npm") %} ```javascript datadogRum.setAccountProperty('name', 'My Company Name') ``` +{% /if %} -{{% /tab %}} - {{% tab "CDN async" %}} - - + +{% if equals($lib_src, "cdn_async") %} ```javascript window.DD_RUM.onReady(function() { window.DD_RUM.setAccountProperty('name', 'My Company Name') }) ``` +{% /if %} -{{% /tab %}} - {{% tab "CDN sync" %}} - - + +{% if equals($lib_src, "cdn_sync") %} ```javascript window.DD_RUM && window.DD_RUM.setAccountProperty('name', 'My Company Name') ``` - -{{% /tab %}} -{{< /tabs >}} +{% /if %} ### Remove account property `datadogRum.removeAccountProperty('')` - -{{< tabs >}} -{{% tab "NPM" %}} - + +{% if equals($lib_src, "npm") %} ```javascript datadogRum.removeAccountProperty('name') ``` +{% /if %} -{{% /tab %}} - {{% tab "CDN async" %}} - - + +{% if equals($lib_src, "cdn_async") %} ```javascript window.DD_RUM.onReady(function() { window.DD_RUM.removeAccountProperty('name') }) ``` +{% /if %} -{{% /tab %}} - {{% tab "CDN sync" %}} - - + +{% if equals($lib_src, "cdn_sync") %} ```javascript window.DD_RUM && window.DD_RUM.removeAccountProperty('name') ``` - -{{% /tab %}} -{{< /tabs >}} +{% /if %} ### Clear account properties `datadogRum.clearAccount()` - -{{< tabs >}} -{{% tab "NPM" %}} - + +{% if equals($lib_src, "npm") %} ```javascript datadogRum.clearAccount() ``` +{% /if %} -{{% /tab %}} - {{% tab "CDN async" %}} - - + +{% if equals($lib_src, "cdn_async") %} ```javascript window.DD_RUM.onReady(function() { window.DD_RUM.clearAccount() }) ``` +{% /if %} -{{% /tab %}} - {{% tab "CDN sync" %}} - - + +{% if equals($lib_src, "cdn_sync") %} ```javascript window.DD_RUM && window.DD_RUM.clearAccount() ``` - -{{% /tab %}} -{{< /tabs >}} +{% /if %} ## Sampling By default, no sampling is applied on the number of collected sessions. To apply a relative sampling (in percent) to the number of sessions collected, use the `sessionSampleRate` parameter when initializing RUM. The following example collects only 90% of all sessions on a given RUM application: - -{{< tabs >}} -{{% tab "NPM" %}} - + +{% if equals($lib_src, "npm") %} ```javascript import { datadogRum } from '@datadog/browser-rum'; @@ -1113,11 +1054,10 @@ datadogRum.init({ sessionSampleRate: 90, }); ``` +{% /if %} -{{% /tab %}} - {{% tab "CDN async" %}} - - + +{% if equals($lib_src, "cdn_async") %} ```javascript window.DD_RUM.onReady(function() { window.DD_RUM.init({ @@ -1128,11 +1068,10 @@ window.DD_RUM.onReady(function() { }) }) ``` +{% /if %} -{{% /tab %}} - {{% tab "CDN sync" %}} - - + +{% if equals($lib_src, "cdn_sync") %} ```javascript window.DD_RUM && window.DD_RUM.init({ @@ -1142,9 +1081,7 @@ window.DD_RUM && sessionSampleRate: 90, }); ``` - -{{% /tab %}} -{{< /tabs >}} +{% /if %} For a sampled out session, all pageviews and associated telemetry for that session are not collected. @@ -1165,10 +1102,8 @@ To change the tracking consent value after the RUM Browser SDK is initialized, u This state is not synchronized between tabs nor persisted between navigation. It is your responsibility to provide the user decision during RUM Browser SDK initialization or by using `setTrackingConsent()`. When `setTrackingConsent()` is used before `init()`, the provided value takes precedence over the initialization parameter. - -{{< tabs >}} -{{% tab "NPM" %}} - + +{% if equals($lib_src, "npm") %} ```javascript import { datadogRum } from '@datadog/browser-rum'; @@ -1181,11 +1116,10 @@ acceptCookieBannerButton.addEventListener('click', function() { datadogRum.setTrackingConsent('granted'); }); ``` +{% /if %} -{{% /tab %}} - {{% tab "CDN async" %}} - - + +{% if equals($lib_src, "cdn_async") %} ```javascript window.DD_RUM.onReady(function() { window.DD_RUM.init({ @@ -1200,10 +1134,10 @@ acceptCookieBannerButton.addEventListener('click', () => { }); }); ``` +{% /if %} -{{% /tab %}} - {{% tab "CDN sync" %}} - + +{% if equals($lib_src, "cdn_sync") %} ```javascript window.DD_RUM && window.DD_RUM.init({ @@ -1215,12 +1149,11 @@ acceptCookieBannerButton.addEventListener('click', () => { window.DD_RUM && window.DD_RUM.setTrackingConsent('granted'); }); ``` - -{{% /tab %}} -{{< /tabs >}} +{% /if %} ## View context + Starting with [version 5.28.0][20], the context of view events is modifiable. Context can be added to the current view only, and populates its child events (such as `action`, `error`, and `timing`) with `startView`, `setViewContext`, and `setViewContextProperty` functions. ### Start view with context @@ -1230,10 +1163,8 @@ Optionally define the context while starting a view with [`startView` options](# ### Add view context Enrich or modify the context of RUM view events and corresponding child events with the `setViewContextProperty(key: string, value: any)` API. - -{{< tabs >}} -{{% tab "NPM" %}} - + +{% if equals($lib_src, "npm") %} ```javascript import { datadogRum } from '@datadog/browser-rum'; @@ -1245,11 +1176,10 @@ datadogRum.setViewContextProperty('activity', { amount: 23.42 }); ``` +{% /if %} -{{% /tab %}} - {{% tab "CDN async" %}} - - + +{% if equals($lib_src, "cdn_async") %} ```javascript window.DD_RUM.onReady(function() { window.DD_RUM.setViewContextProperty('', ''); @@ -1263,11 +1193,10 @@ window.DD_RUM.onReady(function() { }); }) ``` +{% /if %} -{{% /tab %}} - {{% tab "CDN sync" %}} - - + +{% if equals($lib_src, "cdn_sync") %} ```javascript window.DD_RUM && window.DD_RUM.setViewContextProperty('', ''); @@ -1277,17 +1206,13 @@ window.DD_RUM && window.DD_RUM.setViewContextProperty('activity', { amount: 23.42 }); ``` - -{{% /tab %}} -{{< /tabs >}} +{% /if %} ### Replace view context Replace the context of your RUM view events and corresponding child events with `setViewContext(context: Context)` API. - -{{< tabs >}} -{{% tab "NPM" %}} - + +{% if equals($lib_src, "npm") %} ```javascript import { datadogRum } from '@datadog/browser-rum'; datadogRum.setViewContext({ '': '' }); @@ -1297,11 +1222,10 @@ datadogRum.setViewContext({ originalUrl: 'shopist.io/department/chairs', }); ``` +{% /if %} -{{% /tab %}} - {{% tab "CDN async" %}} - - + +{% if equals($lib_src, "cdn_async") %} ```javascript window.DD_RUM.onReady(function() { window.DD_RUM.setViewContext({ '': '' }); @@ -1314,10 +1238,10 @@ window.DD_RUM.onReady(function() { }) }) ``` +{% /if %} -{{% /tab %}} -{{% tab "CDN sync" %}} - + +{% if equals($lib_src, "cdn_sync") %} ```javascript window.DD_RUM && window.DD_RUM.setViewContext({ '': '' }); @@ -1328,9 +1252,7 @@ window.DD_RUM && originalUrl: 'shopist.io/department/chairs', }); ``` - -{{% /tab %}} -{{< /tabs >}} +{% /if %} ## Error context @@ -1338,21 +1260,19 @@ window.DD_RUM && When capturing errors, additional context may be provided at the time an error is generated. Instead of passing extra information through the `addError()` API, you can attach a `dd_context` property directly to the error instance. The RUM Browser SDK automatically detects this property and merges it into the final error event context. -{{< code-block lang="javascript" >}} +```javascript const error = new Error('Something went wrong') error.dd_context = { component: 'Menu', param: 123, } throw error -{{< /code-block >}} +``` ## Global context ### Add global context property After RUM is initialized, add extra context to all RUM events collected from your application with the `setGlobalContextProperty(key: string, value: any)` API: - -{{< tabs >}} -{{% tab "NPM" %}} - + +{% if equals($lib_src, "npm") %} ```javascript import { datadogRum } from '@datadog/browser-rum'; @@ -1365,10 +1285,10 @@ datadogRum.setGlobalContextProperty('activity', { }); ``` -{{% /tab %}} - {{% tab "CDN async" %}} - +{% /if %} + +{% if equals($lib_src, "cdn_async") %} ```javascript window.DD_RUM.onReady(function() { window.DD_RUM.setGlobalContextProperty('', ''); @@ -1382,11 +1302,10 @@ window.DD_RUM.onReady(function() { }); }) ``` +{% /if %} -{{% /tab %}} - {{% tab "CDN sync" %}} - - + +{% if equals($lib_src, "cdn_sync") %} ```javascript window.DD_RUM && window.DD_RUM.setGlobalContextProperty('', ''); @@ -1396,17 +1315,13 @@ window.DD_RUM && window.DD_RUM.setGlobalContextProperty('activity', { amount: 23.42 }); ``` - -{{% /tab %}} -{{< /tabs >}} +{% /if %} ### Remove global context property You can remove a previously defined global context property. - -{{< tabs >}} -{{% tab "NPM" %}} - + +{% if equals($lib_src, "npm") %} ```javascript import { datadogRum } from '@datadog/browser-rum'; datadogRum.removeGlobalContextProperty(''); @@ -1414,10 +1329,10 @@ datadogRum.removeGlobalContextProperty(''); // Code example datadogRum.removeGlobalContextProperty('codeVersion'); ``` +{% /if %} -{{% /tab %}} -{{% tab "CDN async" %}} - + +{% if equals($lib_src, "cdn_async") %} ```javascript window.DD_RUM.onReady(function() { window.DD_RUM.removeGlobalContextProperty(''); @@ -1428,10 +1343,10 @@ window.DD_RUM.onReady(function() { window.DD_RUM.removeGlobalContextProperty('codeVersion'); }) ``` +{% /if %} -{{% /tab %}} -{{% tab "CDN sync" %}} - + +{% if equals($lib_src, "cdn_sync") %} ```javascript window.DD_RUM && window.DD_RUM.removeGlobalContextProperty(''); @@ -1440,17 +1355,13 @@ window.DD_RUM && window.DD_RUM && window.DD_RUM.removeGlobalContextProperty('codeVersion'); ``` - -{{% /tab %}} -{{< /tabs >}} +{% /if %} ### Replace global context Replace the default context for all your RUM events with the `setGlobalContext(context: Context)` API. - -{{< tabs >}} -{{% tab "NPM" %}} - + +{% if equals($lib_src, "npm") %} ```javascript import { datadogRum } from '@datadog/browser-rum'; datadogRum.setGlobalContext({ '': '' }); @@ -1460,10 +1371,10 @@ datadogRum.setGlobalContext({ codeVersion: 34, }); ``` +{% /if %} -{{% /tab %}} -{{% tab "CDN async" %}} - + +{% if equals($lib_src, "cdn_async") %} ```javascript window.DD_RUM.onReady(function() { window.DD_RUM.setGlobalContext({ '': '' }); @@ -1476,10 +1387,10 @@ window.DD_RUM.onReady(function() { }) }) ``` +{% /if %} -{{% /tab %}} -{{% tab "CDN sync" %}} - + +{% if equals($lib_src, "cdn_sync") %} ```javascript window.DD_RUM && window.DD_RUM.setGlobalContext({ '': '' }); @@ -1490,75 +1401,63 @@ window.DD_RUM && codeVersion: 34, }); ``` - -{{% /tab %}} -{{< /tabs >}} +{% /if %} ### Clear global context You can clear the global context by using `clearGlobalContext`. - -{{< tabs >}} -{{% tab "NPM" %}} - + +{% if equals($lib_src, "npm") %} ```javascript import { datadogRum } from '@datadog/browser-rum'; datadogRum.clearGlobalContext(); ``` +{% /if %} -{{% /tab %}} - {{% tab "CDN async" %}} - - + +{% if equals($lib_src, "cdn_async") %} ```javascript window.DD_RUM.onReady(function() { window.DD_RUM.clearGlobalContext(); }); ``` +{% /if %} -{{% /tab %}} -{{% tab "CDN sync" %}} - + +{% if equals($lib_src, "cdn_sync") %} ```javascript window.DD_RUM && window.DD_RUM.clearGlobalContext(); ``` - -{{% /tab %}} -{{< /tabs >}} +{% /if %} ### Read global context Once RUM is initialized, read the global context with the `getGlobalContext()` API. - -{{< tabs >}} -{{% tab "NPM" %}} - + +{% if equals($lib_src, "npm") %} ```javascript import { datadogRum } from '@datadog/browser-rum'; const context = datadogRum.getGlobalContext(); ``` +{% /if %} -{{% /tab %}} - {{% tab "CDN async" %}} - - + +{% if equals($lib_src, "cdn_async") %} ```javascript window.DD_RUM.onReady(function() { const context = window.DD_RUM.getGlobalContext(); }); ``` +{% /if %} -{{% /tab %}} -{{% tab "CDN sync" %}} - + +{% if equals($lib_src, "cdn_sync") %} ```javascript const context = window.DD_RUM && window.DD_RUM.getGlobalContext(); ``` - -{{% /tab %}} -{{< /tabs >}} +{% /if %} ## Contexts life cycle @@ -1569,7 +1468,9 @@ By default, global context and user context are stored in the current page memor 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: + +{% if semverIsAtLeast($rum_browser_sdk_version, "4.49.0") %} +With the introduction of the `storeContextsAcrossPages` configuration option in version 4.49.0, 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 @@ -1580,6 +1481,9 @@ However, this feature comes with some **limitations**: - 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 +{% /if %} + + ## Internal context After the Datadog browser RUM SDK is initialized, you can access the internal context of the SDK. This provides core identifiers and metadata that the SDK uses internally, such as session IDs and application details. @@ -1616,35 +1520,34 @@ You can optionally use `startTime` parameter to get the context of a specific ti ```typescript getInternalContext (startTime?: 'number' | undefined) ``` - -{{< tabs >}} -{{% tab "NPM" %}} - + +{% if equals($lib_src, "npm") %} ```javascript import { datadogRum } from '@datadog/browser-rum' datadogRum.getInternalContext() // { session_id: "xxxx", application_id: "xxxx" ... } ``` +{% /if %} -{{% /tab %}} -{{% tab "CDN async" %}} - + +{% if equals($lib_src, "cdn_async") %} ```javascript window.DD_RUM.onReady(function () { window.DD_RUM.getInternalContext() // { session_id: "xxxx", application_id: "xxxx" ... } }) ``` +{% /if %} -{{% /tab %}} -{{% tab "CDN sync" %}} + +{% if equals($lib_src, "cdn_sync") %} ```javascript window.DD_RUM && window.DD_RUM.getInternalContext() // { session_id: "xxxx", application_id: "xxxx" ... } ``` +{% /if %} -{{% /tab %}} -{{< /tabs >}} - + +{% if semverIsAtLeast($rum_browser_sdk_version, "5.22") %} ## Micro frontend Starting with version 5.22, the RUM Browser SDK supports micro frontend architectures. The mechanism is based on stacktrace. To use it, you must be able to extract service and version properties from your application's file paths and filenames. @@ -1652,9 +1555,8 @@ Starting with version 5.22, the RUM Browser SDK supports micro frontend architec ### How to use it In the `beforeSend` property, you can override the service and version properties. To help you identify where the event originated, use the `context.handlingStack` property. - -{{< tabs >}} -{{% tab "NPM" %}} + +{% if equals($lib_src, "npm") %} ```javascript import { datadogRum } from '@datadog/browser-rum'; @@ -1675,11 +1577,10 @@ datadogRum.init({ }, }); ``` +{% /if %} -{{% /tab %}} - {{% tab "CDN async" %}} - - + +{% if equals($lib_src, "cdn_async") %} ```javascript const SERVICE_REGEX = /some-pathname\/(?\w+)\/(?\w+)\//; @@ -1700,11 +1601,10 @@ window.DD_RUM.onReady(function() { }); }); ``` +{% /if %} -{{% /tab %}} - {{% tab "CDN sync" %}} - - + +{% if equals($lib_src, "cdn_sync") %} ```javascript const SERVICE_REGEX = /some-pathname\/(?\w+)\/(?\w+)\//; @@ -1723,9 +1623,7 @@ window.DD_RUM && window.DD_RUM.init({ }, }); ``` - -{{% /tab %}} -{{< /tabs >}} +{% /if %} Any query done in the RUM Explorer can use the service attribute to filter events. @@ -1737,10 +1635,8 @@ Some events cannot be attributed to an origin, therefore they do not have an ass - Resource events other than XHR and Fetch. - View events (but you can [override default RUM view names][20] instead) - CORS and CSP violations - -## Further Reading - -{{< partial name="whats-next/whats-next.html" >}} +{% /if %} + [1]: /real_user_monitoring/application_monitoring/browser/data_collected/ [2]: /real_user_monitoring/application_monitoring/browser/monitoring_page_performance/ diff --git a/customization_config/en/option_groups/real_user_monitoring.yaml b/customization_config/en/option_groups/real_user_monitoring.yaml index 2b02415bc3f..e0b5fef52cb 100644 --- a/customization_config/en/option_groups/real_user_monitoring.yaml +++ b/customization_config/en/option_groups/real_user_monitoring.yaml @@ -41,3 +41,14 @@ rum_browser_sdk_version_for_proxying_options: default: true - id: gte_4_34_0 - id: lt_4_34_0 + +rum_browser_sdk_version_for_advanced_config_options: +- id: lt_2_13_0 +- id: gte_2_13_0 +- id: gte_2_17_0 +- id: gte_4_13_0 +- id: gte_4_49_0 +- id: gte_5_22_0 +- id: gte_5_28_0 +- id: gte_6_4_0 + default: true diff --git a/customization_config/en/options/version_numbers.yaml b/customization_config/en/options/version_numbers.yaml index 3961cc945fe..a9e5a50acea 100644 --- a/customization_config/en/options/version_numbers.yaml +++ b/customization_config/en/options/version_numbers.yaml @@ -1,5 +1,21 @@ options: +# earlier than 2.13.0 +- label: "<2.13.0" + id: lt_2_13_0 + +# 2.13.0 or later +- label: ">=2.13.0" + id: gte_2_13_0 + +# 2.17.0 or later +- label: ">=2.17.0" + id: gte_2_17_0 + +# 4.13.0 or later +- label: ">=4.13.0" + id: gte_4_13_0 + # Earlier than 4.34.0 - label: "<4.34.0" id: lt_4_34_0 @@ -10,4 +26,20 @@ options: # 5.4.0 or later - label: ">=5.4.0" - id: gte_5_4_0 \ No newline at end of file + id: gte_5_4_0 + +# 4.49.0 or later +- label: ">=4.49.0" + id: gte_4_49_0 + +# 5.4.0 or later +- label: ">=5.22.0" + id: gte_5_22_0 + +# 5.4.0 or later +- label: ">=5.28.0" + id: gte_5_28_0 + +# 6.4.0 +- label: ">=6.4.0" + id: gte_6_4_0 \ No newline at end of file