How and when to enable session cookies with Amazon CloudWatch RUM

Amazon CloudWatch RUM is a real user monitoring service that closes the gap between the end-user experience in a web application, and the serving of that content from your AWS or on-premises environment. By measuring client-side application performance, such as page load time and JavaScript errors, you have access to new and powerful tools for assessing users’ experiences as they traverse your web applications.

Amazon CloudWatch RUM provides an AWS-based, cloud-native client-side application telemetry solution that integrates directly into CloudWatch metrics, logs, and alarms, as well as Amazon CloudWatch Evidently and AWS X-Ray.

How it works

CloudWatch RUM works by collecting data from your web application and emitting that data to AWS for analysis. As shown in Figure 1 below, once CloudWatch RUM has received data from your application, you can examine metrics relating to sessions, page views, performance, errors, and HTTP requests. You can create alarms based on your targets, and optionally export data into CloudWatch logs where you can write queries to extract additional insights.

In this architectural diagram, we examine the flow of telemetry from a web browser into CloudWatch RUM, and then into other CloudWatch services.

Figure 1: High-level overview of the flow of data into CloudWatch RUM

A key part of RUM is the concept of a session. A session aims to capture data pertaining to your web application’s performance while a single user of your application performs a task, or series of tasks. For example, if a customer visits your e-commerce site, adds an item to their cart, completes a purchase, and then leaves – this would be a single session. But, to persist a session across multiple page loads, RUM must set a cookie to identify and resume the session.

It is useful to understand these RUM cookies well in advance!

RUM web client cookies

Using cookies or cookie-like technologies may require the user’s consent in various jurisdictions. User consent and privacy law are beyond the scope of this post. Be mindful of relevant privacy laws when you create your application monitor and install the RUM web client in your application.

The CloudWatch RUM web client is a JavaScript library that records RUM data inside of your web application. The web client is downloaded and configured for your web application using a code snippet generated by the CloudWatch RUM console. The code snippet is placed in the <head> tag of your web application.

Although CloudWatch RUM continues to operate and provide valuable insights without cookies enabled, certain CloudWatch RUM features require cookies. For example, the number of active sessions, number of sessions with errors, and user journeys (where users land and drop off your application) are all metrics that require cookies.

The RUM web client sets two cookies: cwr_s (the session identifier) and cwr_u (the user identifier). Both the session identifier and user identifier are anonymous uuid v4 identifiers created specifically for use by the RUM system. They are not related to any user or session identifiers created by your application. See our documentation for more information.

Note: Personally identifiable information (PII), such as application-level user identifiers or email addresses, are not explicitly collected by CloudWatch RUM, and they are never available for analysis using this service. You must make sure that your application doesn’t leak PII to CloudWatch RUM through error messages or URLs. We built CloudWatch RUM to be secure and private by design. See our documentation for more information.

A newly created RUM application will present you with a script such as the following. In this example, we have enabled cookies:

The default, standard script that is generated for a new application monitor. This example shows the allowCookies value set to true.

Figure 2: a sample of the output from the CloudWatch RUM app monitor creation page

How to enable cookies

When you create a new app monitor in the CloudWatch RUM console, you will be asked whether or not the CloudWatch RUM web client may use cookies.

Enabling cookies can be done from the RUM console, which generates a version of the web client configuration.

Figure 3: enabling cookies in the web client is configurable from the creation page

Checking this option adds the following configuration property to the code snippet provided to you after the app monitor has been created. And you will place it in your web application to install the CloudWatch RUM web client:

allowCookies: true

A complete example may look similar to the following (JSON expanded for readability):

<script>(function(n,i,v,r,s,c,x,z){x=window.AwsRumClient={q:[],n:n,i:i,v:v,r:r,c:c};window[n]=function(c,p){x.q.push({c:c,p:p});};z=document.createElement('script');z.async=true;z.src=s;document.head.insertBefore(z,document.getElementsByTagName('script')[0]);})
    (
        'cwr',
        'cf16e469-bda3-4f8b-a9e3-64664dsample',
        '1.0.0',
        'us-east-2',
        'https://client.rum.us-east-1.amazonaws.com/1.0.2/cwr.js',
        {
            sessionSampleRate:1, guestRoleArn:'arn:aws:iam::000000000000:role/RUM-Monitor-us-west-2-000000000000-1893821407361-Unauth',
            identityPoolId:'us-west-2:f962e054-68c4-43ff-98d7-d98e33sample',
            endpoint:"https://dataplane.rum.us-east-2.amazonaws.com",
            telemetries:['errors','http','performance'],
            allowCookies:true
        }
    );
</script>

This approach will let the web client use cookies as soon as it is initialized.

Alternatively, you can allow or disallow the web client to use cookies dynamically after it is initialized. Add the following JavaScript command anywhere in your application code after the snippet:

cwr('allowCookies', true);

And, with that, you can now emit session data into CloudWatch RUM!

How to use advanced cookie configurations

In some cases, the web application will need to override the default cookie attributes used by the web client. Such cases may include:

The web application owns multiple sub-domains.
The web application runs on a shared domain and uses a specific URL path.
The web application does not use SSL.

For example, consider an application whose root URL is http://example.com/myapp. This application does not support SSL (is accessed using http only) and runs under the /myapp path, because it shares the example.com domain with other applications.

To enable RUM web client cookies for this application, we would add the cookieAttributes property to the web client configuration. The configuration argument of the code snippet would contain the following cookie configuration (truncated for readability):

{
    ...
    allowCookies: true,
    cookieAttributes: {
        path: “/myapp”,
        secure: false
    }
}

You can learn more about the web client’s cookie configuration options from our documentation.

Results

Now that you have cookies enabled, you can take advantage of the user journey features of CloudWatch RUM.

Sample of a user journey in the CloudWatch RUM console.

Figure 4: an example of the user journey view from within the CloudWatch RUM console

Next steps

Enabling cookies for CloudWatch RUM is only the beginning your journey with client-side telemetry, and there is a great deal more to learn from our documentation. Variable session sample rates, custom page view recording, configurable cookie domains, and variations in pages to include or exclude are all features that you can now take advantage of!

AWS Cloud Operations & Migrations Blog