Send custom events

CloudWatch RUM records and ingests the events listed in Information collected by the CloudWatch RUM web client. If you use version 1.12.0 or later of the CloudWatch RUM web client, you can define, record, and send additional custom events. You define the event type name and the data to send for each event type that you define. Each custom event payload can be up to 6 KB.

Custom events are ingested only if the app monitor has custom events enabled. To update the configuration settings of your app monitor, use the CloudWatch RUM console or the UpdateAppMonitor API.

After you enable custom events, and then define and send custom events, you can search for them in the CloudWatch RUM console. Choose your app monitor, and then choose the Sessions tab. In the filter bar at the top of the tab, enter event_type = followed by your custom event type (for example, event_type = my_custom_event). Select the matching suggestion, and then choose Apply filters. The Most recent sessions table then lists only the sessions that contain that event. To view the event details, choose a session, choose the event in the session waterfall, and then choose the Raw event tab.

If you turn on Data storage for your app monitor, you can also query custom events across sessions by using CloudWatch Logs Insights.

Requirements and syntax

Custom events consist of an event type and event details. The requirements for these are as follows:

Examples of recording custom events

There are two ways to record custom events in the CloudWatch RUM web client.

Send a custom event using the recordEvent API, NPM example

awsRum.recordEvent('my_custom_event', {
        location: 'IAD', 
        current_url: 'amazonaws.com', 
        user_interaction: {
            interaction_1 : "click",
            interaction_2 : "scroll"
        }, 
        visit_count:10
    }
)

Send a custom event using the recordEvent API, embedded script example

cwr('recordEvent', {
    type: 'my_custom_event', 
    data: {
        location: 'IAD', 
        current_url: 'amazonaws.com', 
        user_interaction: {
            interaction_1 : "click",
            interaction_2 : "scroll"
        }, 
        visit_count:10
    }
})

Example of sending a custom event using a customized plugin

// Example of a plugin that listens to a scroll event, and
// records a 'custom_scroll_event' that contains the timestamp of the event.
class MyCustomPlugin implements Plugin {
    // Initialize MyCustomPlugin.
    constructor() {
        this.enabled;
        this.context;
        this.id = 'custom_event_plugin';
    }
    // Load MyCustomPlugin.
    load(context) {
        this.context = context;
        this.enable();
    }
    // Turn on MyCustomPlugin.
    enable() {
        this.enabled = true;
        this.addEventHandler();
    }
    // Turn off MyCustomPlugin.
    disable() {
        this.enabled = false;
        this.removeEventHandler();
    }
    // Return MyCustomPlugin Id.
    getPluginId() {
        return this.id;
    }
    // Record custom event.
    record(data) {
        this.context.record('custom_scroll_event', data);
    }
    // EventHandler.
    private eventHandler = (scrollEvent: Event) => {
        this.record({timestamp: Date.now()})
    }
    // Attach an eventHandler to scroll event.
    private addEventHandler(): void {
        window.addEventListener('scroll', this.eventHandler);
    }
    // Detach eventHandler from scroll event.
    private removeEventHandler(): void {
        window.removeEventListender('scroll', this.eventHandler);
    }
}