AWS.Synthetics reference

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.

Canary: 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,
});

Canary: 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,
});

DescribeCanariesLastRun

Source: src/AWS/Synthetics/DescribeCanariesLastRun.ts

Runtime binding for synthetics:DescribeCanariesLastRun — read the most recent run of every canary in the account (optionally filtered by Names), e.g. to render a fleet-wide status page.

Provide Synthetics.DescribeCanariesLastRunHttp on the hosting Lambda Function to satisfy the requirement.

DescribeCanariesLastRun: Reading Canary Status

// init — grants synthetics:DescribeCanariesLastRun
const describeCanariesLastRun =
  yield* AWS.Synthetics.DescribeCanariesLastRun();

// runtime
const { CanariesLastRun } = yield* describeCanariesLastRun();
const failing = CanariesLastRun?.filter(
  (c) => c.LastRun?.Status?.State === "FAILED",
);

GetCanary

Source: src/AWS/Synthetics/GetCanary.ts

Runtime binding for synthetics:GetCanary — read the full configuration and current status (state, last run, timeline) of the bound Canary; the canary name is injected automatically.

Provide Synthetics.GetCanaryHttp on the hosting Lambda Function to satisfy the requirement.

GetCanary: Reading Canary Status

// init — grants synthetics:GetCanary on the canary
const getCanary = yield* AWS.Synthetics.GetCanary(canary);

// runtime
const { Canary } = yield* getCanary();
const state = Canary?.Status?.State;

GetCanaryRuns

Source: src/AWS/Synthetics/GetCanaryRuns.ts

Runtime binding for synthetics:GetCanaryRuns — list the run results (status, timeline, artifact location) of the bound Canary; the canary name is injected automatically.

Provide Synthetics.GetCanaryRunsHttp on the hosting Lambda Function to satisfy the requirement.

GetCanaryRuns: Reading Canary Runs

// init — grants synthetics:GetCanaryRuns on the canary
const getCanaryRuns = yield* AWS.Synthetics.GetCanaryRuns(canary);

// runtime
const { CanaryRuns } = yield* getCanaryRuns({ MaxResults: 10 });
const failed = CanaryRuns?.filter((run) => run.Status?.State === "FAILED");

Group

Source: src/AWS/Synthetics/Group.ts

A CloudWatch Synthetics group — associates canaries (including cross-Region canaries) so you can view aggregated run results and manage them as a unit. A group can hold as many as 10 canaries, and an account can have as many as 20 groups.

Group: Creating Groups

Group of Canaries

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

const group = yield* Synthetics.Group("ApiCanaries", {
  members: [checkoutCanary.canaryArn, searchCanary.canaryArn],
});

Empty Group with Tags

const group = yield* Synthetics.Group("Fleet", {
  tags: { team: "platform" },
});

StartCanary

Source: src/AWS/Synthetics/StartCanary.ts

Runtime binding for synthetics:StartCanary — start the bound Canary running on its configured schedule (e.g. trigger an on-demand smoke test after a deployment); the canary name is injected automatically.

Provide Synthetics.StartCanaryHttp on the hosting Lambda Function to satisfy the requirement.

StartCanary: Controlling the Canary

// init — grants synthetics:StartCanary on the canary
const startCanary = yield* AWS.Synthetics.StartCanary(canary);

// runtime — a ConflictException means it is already starting/running
yield* startCanary().pipe(
  Effect.catchTag("ConflictException", () => Effect.void),
);

StopCanary

Source: src/AWS/Synthetics/StopCanary.ts

Runtime binding for synthetics:StopCanary — stop future runs of the bound Canary (an in-flight run completes on its own); the canary name is injected automatically.

Provide Synthetics.StopCanaryHttp on the hosting Lambda Function to satisfy the requirement.

StopCanary: Controlling the Canary

// init — grants synthetics:StopCanary on the canary
const stopCanary = yield* AWS.Synthetics.StopCanary(canary);

// runtime — a ConflictException means it is not currently running
yield* stopCanary().pipe(
  Effect.catchTag("ConflictException", () => Effect.void),
);