Create fine-grained CloudWatch canary schedules with cron expressions

In this post, I’ll explain how to create fine-grained canary schedules to meet your business requirements using built-in cron expression scheduling in Amazon CloudWatch Synthetics.

You can use CloudWatch Synthetics to create canaries, configurable scripts that run on a schedule, to monitor your endpoints and APIs. Because canaries follow the same routes and perform the same actions as a customer, you can verify your customer experience even when you don’t have any customer traffic on your applications. By using canaries, you can discover issues before your customers do.

Canaries can be run ad-hoc, which is useful for one-off tests and for adding to CI/CD pipeline builds for extra assurance. You can schedule canaries to run every 1 to 60 minutes or daily at a specified time.

If you want to monitor your application only at a certain time of the day or just once a month, use the built-in cron functionality.

Consider an application that needs to be available only between 9:00 am and 5:00 pm Monday to Friday. It’s scaled in during other times for cost-saving purposes. In this case, it makes sense to only run the canary between 9:00 am and 5:00 pm Monday to Friday without having to worry about adjusting or suppressing alarms during the off-peak period.

Create a canary schedule

Let’s assume that you need to run the canary every 10 minutes during peak times.

You can configure the canary schedule when you create the canary or afterward. In this example, I will edit an existing canary schedule.

1. In the Amazon CloudWatch console, choose the canary, choose Actions, and then choose Edit.
2. In Schedule, choose CRON expression.
3. In the input field, enter 0 9-17 ? * MON-FRI, as shown in Figure 1.

Note: Canary cron schedules are specified in UTC time. If your requirements reflect a different time zone, you will have to convert your time to UTC.

Figure 1: Canary schedule with CRON expression

Let’s break this down:
0 9-17 ? * MON-FRI

0 means that the canary runs on the hour.
9-17 specifies that the canary will run (every hour) between 9:00 am and 5:59 pm UTC.
? means that day of the month is ignored because day of the week was specified.
* means that it will run every month of the year
MON-FRI – means that the canary will run Monday through Friday only.

Use the following AWS CLI command to update the canary:

aws synthetics update-canary --name mycanary --schedule Expression="cron(0 9-17 ? * MON-FRI *)"

Unlike the expression you entered in the console, the CLI command requires an asterisk (*) at the end, which signifies the year. Because CloudWatch canaries cannot exceed a year in between runs, the use of the year field is limited. When you use the CLI, you must still specify the year value with *. If you enter another value (for example, 2021), you will receive an error.

More examples

Consider an application that only needs to be monitored on a specific day of each month (for example, a payroll run). Let’s monitor the application every 5 minutes on the 15th day of each month, from 7:00 am to 8:00 pm UTC.

Here is the expression:

In the console, you enter the following

0/5 7-19 15 * ?

In the CLI, you use:

aws synthetics update-canary --name mycanary --schedule Expression="cron(0/5 7-19 15 * ? *)"

0/5 means that the canary runs every 5 minutes.
7-19 specifies that the canary will run (every 5 minutes) between 7:00 am and 7:59 pm UTC.
15 means the canary will run on the 15th of the month.
* means that the canary will run every month of the year.
? means that day of the week is ignored because day of the month was specified.

Consider a case where the canary only needs to run during a specific period in the future. For this example, let’s say that an application publishes exam results on August 16 and the website must be monitored every 10 minutes, 24 hours per day, between August 16 and 20.

Here is the expression:

In the console, you enter the following:

aws synthetics update-canary --name mycanary --schedule Expression="cron(0/10 * 16-20 8 ? *)"

0/10 means that the canary runs every 10 minutes.
* specifies that the canary will run all day.
16-20 means the canary will run between the 16th and 20th of the month.
8 means that the canary will run in August.
? means that day of the week is ignored because day of the month was specified.

Remember to remove or edit this canary after it has served its purpose; otherwise, it will run during those dates the following year.

Conclusion

In this blog post, I showed you how to customize canary schedules to meet your business requirements. For more information, see Scheduling canary runs using cron in the Amazon CloudWatch User Guide.

About the author