Canary

Source: src/AWS/Synthetics/Canary.ts

A CloudWatch Synthetics canary — a scripted probe that monitors your endpoints and APIs on a schedule from the outside in.

The canary script is provided inline and packaged automatically for the chosen runtime. Unless you pass executionRoleArn, an IAM execution role is created with least-privilege access to the artifact bucket, CloudWatch Logs, and Synthetics metrics.

Creating Canaries

Heartbeat Canary (created stopped)

import * as Synthetics from "alchemy/AWS/Synthetics";

const canary = yield* Synthetics.Canary("Heartbeat", {
  script: `
    const synthetics = require("Synthetics");
    exports.handler = async () => {
      return await synthetics.executeStep("heartbeat", async () => {});
    };
  `,
  artifactS3Location: Output.interpolate`s3://${bucket.bucketName}/canary`,
});

Started Canary on a Schedule

const canary = yield* Synthetics.Canary("ApiMonitor", {
  script: myCanaryScript,
  artifactS3Location: "s3://my-artifacts/api-monitor",
  schedule: { expression: "rate(5 minutes)" },
  start: true,
});

Configuration

Custom Runtime, Timeout and Environment

const canary = yield* Synthetics.Canary("Checkout", {
  script: checkoutScript,
  runtimeVersion: "syn-nodejs-puppeteer-16.1",
  artifactS3Location: "s3://my-artifacts/checkout",
  runConfig: {
    timeout: "60 seconds",
    environmentVariables: { TARGET_URL: "https://example.com" },
  },
  successRetentionPeriod: "7 days",
  failureRetentionPeriod: "31 days",
});

Bring Your Own Execution Role

const canary = yield* Synthetics.Canary("Probe", {
  script: probeScript,
  artifactS3Location: "s3://my-artifacts/probe",
  executionRoleArn: role.roleArn,
});