Library Functions Available for Canary Scripts - Amazon CloudWatch

Library Functions Available for Canary Scripts

CloudWatch Synthetics includes several built-in functions that you can call when writing Node.js scripts to use as canaries.

Some functions apply to both UI and API canaries. Others apply to UI canaries only. A UI canary is a canary that uses the getPage() function and uses Puppeteer as a web driver to navigate and interact with webpages.

Library Functions That Apply to All Canaries

The following CloudWatch Synthetics library functions are useful for all canaries.

getLogLevel();

Retrieves the current log level for the Synthetics library. Possible values are the following:

  • 0 – Debug

  • 1 – Info

  • 2 – Warn

  • 3 – Error

Example:

let logLevel = synthetics.getLogLevel();

setLogLevel();

Sets the log level for the Synthetics library. Possible values are the following:

  • 0 – Debug

  • 1 – Info

  • 2 – Warn

  • 3 – Error

Example:

synthetics.setLogLevel(0);

Synthetics Logger

SyntheticsLogger writes logs out to both the console and to a local log file at the same log level. This log file is written to both locations only if the log level is at or below the desired logging level of the log function that was called.

The logging statements in the local log file are prepended with "DEBUG: ", "INFO: ", and so on to match the log level of the function that was called.

You can use the SyntheticsLogger assuming you want to run the Synethetics Library at the same log level as your Synthetics canary logging.

Using the SyntheticsLogger is not required to create a log file that is uploaded your S3 results location. You could instead create a different log file in the /tmp folder. Any files created under the /tmp folder are uploaded to the results location in S3 as artifacts.

To use the Synthetics Library logger:

const log = require('SyntheticsLogger');

Useful function definitions:

log.debug(message, ex);

Parameters: message is the message to log. ex is the exception, if any, to log.

Example:

log.debug("Starting step - login.");

log.error(message, ex);

Parameters: message is the message to log. ex is the exception, if any, to log.

Example:

try { await login(); catch (ex) { log.error("Error encountered in step - login.", ex); }

log.info(message, ex);

Parameters: message is the message to log. ex is the exception, if any, to log.

Example:

log.info("Successfully completed step - login.");

log.log(message, ex);

This is an alias for log.info.

Parameters: message is the message to log. ex is the exception, if any, to log.

Example:

log.log("Successfully completed step - login.");

log.warn(message, ex);

Parameters: message is the message to log. ex is the exception, if any, to log.

Example:

log.warn("Exception encountered trying to publish CloudWatch Metric.", ex);

Library Functions That Apply to UI Canaries Only

The following CloudWatch Synthetics library functions are useful only for UI canaries.

async addUserAgent(page, userAgentString);

This function appends userAgentString to the specified page's user-agent header.

Example:

await synthetics.addUserAgent(page, "MyApp-1.0");

Results in the page’s user-agent header being set to browsers-user-agent-header-valueMyApp-1.0

async executeStep(stepName = null, functionToExecute);

Executes the provided step, wrapping it with start/pass/fail logging, start/pass/fail screenshots, and pass/fail and duration metrics. It also does the following:

  • Logs that the step started.

  • Takes a screenshot named <stepName>-starting.

  • Starts a timer.

  • Executes the provided function.

  • If the function returns normally, it counts as passing. If the function throws, it counts as failing.

  • End the timer.

  • Logs whether the step passed or failed

  • Takes a screenshot named <stepName>-succeeded or <stepName>-failed.

  • Emits the stepName SuccessPercent metric, 100 for pass or 0 for failure.

  • Emits the stepName Duration metric, with a value based on the step start and end times.

  • Finally, returns what the functionToExecute returned or re-throws what functionToExecute threw.

Example:

await synthetics.executeStep('navigateToUrl', async function (timeoutInMillis = 30000) { await page.goto(url, {waitUntil: ['load', 'networkidle0'], timeout: timeoutInMillis});});

Response:

Returns what functionToExecute returns.

getPage();

Returns the current open page as a Puppeteer object. For more information, see Puppeteer API v1.14.0.

Example:

let page = synthetics.getPage();

Response:

The page (Puppeteer object) that is currently open in the current browser session.

getRequestResponseLogHelper();

Use this function as a builder pattern for tweaking the request and response logging flags.

Example:

synthetics.setRequestResponseLogHelper(getRequestResponseLogHelper().withLogRequestHeaders(false));;

Response:

{RequestResponseLogHelper}

RequestResponseLogHelper class

Handles the fine-grained configuration and creation of string representations of request and response payloads.

class RequestResponseLogHelper { constructor () { this.request = {url: true, resourceType: false, method: false, headers: false, postData: false}; this.response = {status: true, statusText: true, url: true, remoteAddress: false, headers: false}; } withLogRequestUrl(logRequestUrl); withLogRequestResourceType(logRequestResourceType); withLogRequestMethod(logRequestMethod); withLogRequestHeaders(logRequestHeaders); withLogRequestPostData(logRequestPostData); withLogResponseStatus(logResponseStatus); withLogResponseStatusText(logResponseStatusText); withLogResponseUrl(logResponseUrl); withLogResponseRemoteAddress(logResponseRemoteAddress); withLogResponseHeaders(logResponseHeaders);

Example:

synthetics.setRequestResponseLogHelper(getRequestResponseLogHelper() .withLogRequestPostData(true) .withLogRequestHeaders(true) .withLogResponseHeaders(true));

Response:

{RequestResponseLogHelper}

setRequestResponseLogHelper();

Use this function as a builder pattern for setting the request and response logging flags.

Example:

synthetics.setRequestResponseLogHelper().withLogRequestHeaders(true).withLogResponseHeaders(true);

Response:

{RequestResponseLogHelper}