Fullstack observability with AWS CDK V2 Canary's and Synthetics

Time to read: 11 minutes

Version 2 of the AWS Cloud Development Kit (CDK) shipped a couple weeks ago.

As part of that release AWS have separated stable and experimental cdk libraries. In this blog I am going to build out with some of te new tools and features to learn a little about how to use experimental constructs, and also to share some observability tooling setups for monitoring your websites.

In this blog

  • Build a website with AWS CDK
  • Create a canary to continuously monitor the websites up time
  • Create a cloudwatch dashboard as a single source of truth for observability
  • Add Real User Monitoring to the website to get detailed user journeys and page load analytics

TL; DR

The canary stack can be found here: https://github.com/simonireilly/canary-stack

Once deployed you will have a Dashboard and Alarm for an S3 bucket website.

The architecture that is built once complete is:

AWS Architecture diagram showing links canary and s3 hosted website

Starting a cdk v2 project

Lets begin.

I do the following to get the project configured:

mkdir canary

cd canary

npx [email protected] init app --language typescript

This creates the basic structure.

Previous modules would ship separately, this is still the case for experimental modules.

Adding Experimental modules

To add an experimental module you need to install it with yarn or npm.

yarn add @aws-cdk/aws-synthetics-alpha

You know, I could not recommend cdk-dia enough, with will give you a nice diagram of your stack:

yarn add --dev cdk-dia

Building a Website with canaries

Get started by adding a website to your stack:

mkdir -p lib/website

touch lib/website/index.html

In there you need some HTML, this will do:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>Your website</title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
  </head>
  <body>
    <main style="display: flex; flex-direction: column; align-items: center;">
      <h1>
        Welcome to the canary stack
      </h1>

      <p>
        This is a simple single page website that show cases the aws-cdk.
      </p>
    </main>
  </body>
</html>

Now you can deploy your website from the stack using 2 AWS buckets, one to hold the zipped files, and another to deploy as a public website.

import { Bucket } from 'aws-cdk-lib/aws-s3';
import { BucketDeployment, Source } from 'aws-cdk-lib/aws-s3-deployment';
import { Construct } from 'constructs';
import { Stack, StackProps, CfnOutput } from 'aws-cdk-lib';
import * as path from 'path';

export class CanaryStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const websiteBucket = new Bucket(this, 'WebsiteBucket', {
      websiteIndexDocument: 'index.html',
      publicReadAccess: true,
    });

    new BucketDeployment(this, 'DeployWebsite', {
      sources: [Source.asset(path.join(__dirname, 'website'))],
      destinationBucket: websiteBucket,
    });

    new CfnOutput(this, 'WebsiteUrl', {
      value: websiteBucket.bucketWebsiteUrl,
    });
  }
}

The output from this will reveal your website URL:

 ✅  CanaryStack

Outputs:
CanaryStack.WebsiteUrl = http://canarystack-websitebucket75c24d94-z8brk94c8nvu.s3-website-eu-west-1.amazonaws.com

Adding a Canary

We want to be able to monitor our websites up time, to do that we can add a canary.

The canary code looks like this:

    const canary = new Canary(this, 'MyCanary', {
      schedule: Schedule.rate(Duration.minutes(5)),
      test: Test.custom({
        code: Code.fromAsset(path.join(__dirname, 'canary')),
        handler: 'index.handler',
      }),
      runtime: Runtime.SYNTHETICS_NODEJS_PUPPETEER_3_3,
      environmentVariables: {
        SITE_URL: websiteBucket.bucketWebsiteUrl,
      },
    });

You need to be specific about where you put the canary javascript. From what I can tell it follows the same patter as when building AWS layers.

mkdir -p lib/canary/nodejs/node_modules

touch lib/canary/nodejs/node_modules/index.js

Now you want to put the canary javascript into that file like so:

const synthetics = require('Synthetics');
const log = require('SyntheticsLogger');

const pageLoadBlueprint = async function () {
  // Configure the stage of the API using environment variables
  const url = String(process.env.SITE_URL);

  const page = await synthetics.getPage();
  const response = await page.goto(url, {
    waitUntil: 'domcontentloaded',
    timeout: 30000,
  });
  // Wait for page to render. Increase or decrease wait time based on endpoint being monitored.
  await page.waitFor(15000);
  // This will take a screenshot that will be included in test output artifacts.
  await synthetics.takeScreenshot('loaded', 'loaded');
  const pageTitle = await page.title();
  log.info('Page title: ' + pageTitle);
  if (response.status() !== 200) {
    throw 'Failed to load page!';
  }
};

exports.handler = async () => {
  return await pageLoadBlueprint();
};

Now we can deploy again:

yarn cdk deploy

This time we will have a canary to go and see in the dashboard which looks like this:

AWS Admin panel screenshot showing canary polled every 5 minutes

Adding Alerts

Monitoring is hard, but it doesn't need to be hard to implement.

The CDK can make creating a dashboard and an alarm for the canary very easy.

Here is the code you need:

    const alarm = new Alarm(this, 'CanaryAlarm', {
      metric: canary.metricSuccessPercent(),
      evaluationPeriods: 2,
      threshold: 90,
      comparisonOperator: ComparisonOperator.LESS_THAN_THRESHOLD,
    });

    const alarmWidget = new AlarmWidget({
      alarm,
      title: 'Canary Alarm',
    });

    const dashboard = new Dashboard(this, 'MainDashbaord', {
      dashboardName: 'Main-Dashboard',
      periodOverride: PeriodOverride.AUTO,
      widgets: [[alarmWidget]],
    });

Thats all it takes to get setup with a dashboard for your site.

Canary alarm on a cloudwatch dashboard

Adding Real User Monitoring

AWS just launched Real User Monitoring (RUM). This is a client side tool that tracks the real user journey and page load analytics.

You can read about RUM in Jeff Barr's announcement blog post: https://aws.amazon.com/blogs/aws/cloudwatch-rum/

You should follow the wizard to set this up and chose the option to get a new cognito user pool.

Then you can copy the snippet produced into the <head> tag within the lib/website/index.html.

Now we deploy again:

yarn deploy

When we go to the rum dashboard we will see all the stats for a users session:

Real user monitoring dashboard

Closing

With a canary in place you have:

  • A simple health check for your web application.
  • You can now layer more features onto the canary, such as:
    • User login using aws-sdk and cognito
    • Visual regression testing
  • In the future