Send RUM Custom Actions

Overview

Real User Monitoring automatically collects actions on your web application. You can collect additional events and timings such as form completions and business transactions.

Custom RUM actions allow you to monitor interesting events with all the relevant context attached. For example, collecting a user’s checkout information on an e-commerce website.

Instrument your code

Create a RUM action using the addAction API. Give your action a name and attach context attributes in the form of a JavaScript object.

The following example creates a checkout action with details about the user cart when the user clicks on the checkout button.

import { datadogRum } from '@datadog/browser-rum';

function onCheckoutButtonClick(cart) {
    datadogRum.addAction('checkout', {
        'value': cart.value, // for example, 42.12
        'items': cart.items, // for example, ['tomato', 'strawberries']
    })
}

Ensure that you wrap the API call with the onReady callback:

function onCheckoutButtonClick(cart) {
    DD_RUM.onReady(function() {
        DD_RUM.addAction('checkout', {
            'value': cart.value, // for example, 42.12
            'items': cart.items, // for example, ['tomato', 'strawberries']
        })
    })    
}

Ensure that you check for DD_RUM before the API call:

window.DD_RUM && DD_RUM.addAction('<NAME>', '<JSON_OBJECT>');

function onCheckoutButtonClick(cart) {
    window.DD_RUM && DD_RUM.addAction('checkout', {
        'value': cart.value, // for example, 42.12
        'items': cart.items, // for example, ['tomato', 'strawberries']
    })
}

All RUM context such as current page view information, geoIP data, and browser information, is automatically attached along with extra attributes provided with the Global Context API.

Create facets and measures on attributes

After deploying the code that creates your custom actions, they appear in the Actions tab of the RUM Explorer.

To filter on your custom actions, use the Action Target Name attribute: @action.target.name:<ACTION_NAME>.

The example below uses the following filter: @action.target.name:checkout.

After clicking on an action, a side panel with metadata appears. You can find your action attributes in the Custom Attributes section and create facets or measures for these attributes by clicking on them.

Use facets for distinctive values (IDs) and measures for quantitative values such as timings and latency. For example, create a facet for the cart items and a measure for the cart value.

Use attributes in the RUM Explorer

You can use action attributes along with facets and measures in the RUM Explorer to build dashboard widgets, monitors, and advanced queries.

The following example displays the average cart value per country in the last two days. Click the Export button to export the search query into a dashboard widget or monitor.

Use RUM actions in the RUM Explorer

Further Reading

Additional helpful documentation, links, and articles: