When you launch a web application to users globally, you want to be able to monitor the experience of your end users as they interact with the application. The end users can be accessing the application with different browsers, geographic locations, connectivity and so forth which can lead to varied user experiences.
During re:Invent 2021, AWS announced Amazon CloudWatch Real-User Monitoring (RUM) for web applications. The CloudWatch RUM service enables you to collect, view, and analyze client-side data about your web application performance from actual user sessions in near real time. Application Developers and DevOps engineers can use this data to quickly identify and debug client-side issues to optimize end user experience. To get started, you simply generate a JavaScript snippet for your application by creating a RUM app monitor. This snippet is added to the header section in the HTML of your application. As users interact with your application, the RUM web client will collect and send data about the session to CloudWatch RUM for visualization and analysis.
You can choose to try the setup described in the repository and blog post by either using the provided sample code or by creating your own React app from scratch.
- An AWS Account which you can use as the target to deploy the Amplify Application
- Node.js version 16.x or higher and npm version 8.x or higher
- Amplify CLI (
npm i -g @aws-amplify/cli@latest) - which can be setup following the instructions here - A terminal and IDE from your local computer or any a cloud based environment like Cloud9
- (Optional) If using Cloud9 consider resizing the EBS Volume to allow enough space for the project
As a first step, open a new terminal window in the project's root after cloning the repo, and then run the following command to install the application's dependencies:
npm ciNext, while still in the project's root directory, run the following command to initialize the Amplify app:
amplify initNow that you have configured the Amplify app, you can deploy the AWS resources by running the following command:
amplify publishNote In the command above we are using
publishinstead ofpushbecause we want to make sure that the Amplify app is properly deployed to Amplify Hosting and an URL is generated.
As output of the previous step, you should have a new URL that you can use to access your Amplify app. This URL will be used by the CloudWatch RUM service to collect data about your application. We need to update the CDK template for the CloudWatch RUM resources to use this URL.
Open the amplify/backend/custom/cloudwatchrum/cdk-stack.ts file and find the line that looks like the one below, then replace the value with the one that was generated in the previous step.
domain: "dev.xXxxXXxxxxxxxx.amplifyapp.com",Then run amplify push -y once again to deploy the resources.
After running the previous command the post-push.js script present in the amplify/hooks/ folder should have been run. This script retrieves all the configurations that were generated by the Amplify CLI and then outputs them in the console so that you can copy and add them to the JavaScript snippet to the header of the HTML of the application.
Below an example of the output you should see in the terminal:
----- 🪝 post-push execution start -----
Copy/paste these values in public/index.html with CloudWatch RUM code snippet below
appMonitorId 36663679-cbb1-4a91-afc1-e25517517f8e
appMonitorGuestRoleArn arn:aws:iam::123456789101:role/amplify-amplifycloudwatchrum-unauthRole
appMonitoridentityPoolId eu-west-1:3c57c6f1-7f27-44c2-ad46-99636a4cb218
awsRegion eu-west-1
----- 🪝 post-push execution end -----Open the index.html file and add the following JavaScript snippet to the header of the HTML of your application:
<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.head.getElementsByTagName("script")[0]
);
})(
"cwr",
"[appMonitorId]", // Replace this with appMonitorId
"1.0.0",
"[awsRegion]", // Replace this with awsRegion
"https://client.rum.us-east-1.amazonaws.com/1.2.1/cwr.js",
{
sessionSampleRate: 1,
guestRoleArn: "[appMonitorGuestRoleArn]", // Replace this with appMonitorGuestRoleArn
identityPoolId: "[appMonitoridentityPoolId]", // Replace this with appMonitoridentityPoolId
endpoint: "https://dataplane.rum.[awsRegion].amazonaws.com", // Replace this with awsRegion
telemetries: ["performance", "errors", "http"],
allowCookies: true,
enableXRay: true,
}
);
</script>While you are at it, make sure to replace all the placeholder values with the values that were generated by the Amplify CLI.
Now that all the pieces are in place, run the following command to deploy the application to Amplify Hosting:
amplify publish -yIf everything went well, you should see in the terminal the url of your Amplify Hosting application. When visiting it you should see the application load successfully.
After reloading the page a few times, go check out the CloudWatch RUM console in the AWS Management Console and see if you see any new telemetry data.
If you want to create your own app, please follow the steps described in the blog post.
In case you want to avoid having to copy and paste the JavaScript snippet and the values (Step 6), you can use the alternative post-push.js hook found in the amplify/hooks/ folder. This file will be run after each amplify push command and will overwrite the content of the index.html file with the values that were generated by the Amplify CLI.
See CONTRIBUTING for more information.
This library is licensed under the MIT-0 License. See the LICENSE file.