How and when to enable session cookies with Amazon CloudWatch RUM
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.
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.
<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:
Figure 2: a sample of the output from the CloudWatch RUM app monitor creation page
How to enable cookies
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:
A complete example may look similar to the following (JSON expanded for readability):
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):
You can learn more about the web client’s cookie configuration options from our documentation.
Now that you have cookies enabled, you can take advantage of the user journey features of CloudWatch RUM.
Figure 4: an example of the user journey view from within the CloudWatch RUM console
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!