Node.js library classes and functions that apply to all canaries Node.js library classes and functions that apply to UI canaries only Node.js library classes and functions that apply to API canaries only

Library functions available for Node.js canary scripts

This section lists the library functions available for Node.js canary scripts.

Topics

Node.js library classes and functions that apply to all canaries
Node.js library classes and functions that apply to UI canaries only
Node.js library classes and functions that apply to API canaries only

Node.js library classes and functions that apply to all canaries

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

Synthetics class

The following functions for all canaries are in the Synthetics class.

addExecutionError(errorMessage, ex);

errorMessage describes the error and ex is the exception that is encountered

You can use addExecutionError to set execution errors for your canary. It fails the canary without interrupting the script execution. It also doesn't impact your successPercent metrics.

You should track errors as execution errors only if they are not important to indicate the success or failure of your canary script.

An example of the use of addExecutionError is the following. You are monitoring the availability of your endpoint and taking screenshots after the page has loaded. Because the failure of taking a screenshot doesn't determine availability of the endpoint, you can catch any errors encountered while taking screenshots and add them as execution errors. Your availability metrics will still indicate that the endpoint is up and running, but your canary status will be marked as failed. The following sample code block catches such an error and adds it as an execution error.


try {
        await synthetics.takeScreenshot(stepName, "loaded");
    } catch(ex) {
        synthetics.addExecutionError('Unable to take screenshot ', ex);
    }

getCanaryName();

Returns the name of the canary.

getCanaryArn();

Returns the ARN of the canary.

getCanaryUserAgentString();

Returns the custom user agent of the canary.

getRuntimeVersion();

This function is available in runtime version syn-nodejs-puppeteer-3.0 and later. It returns the Synthetics runtime version of the canary. For example, the return value could be syn-nodejs-puppeteer-3.0.

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);

SyntheticsConfiguration class

This class is available only in the syn-nodejs-2.1 runtime version or later.

You can use the SyntheticsConfiguration class to configure the behavior of Synthetics library functions. For example, you can use this class to configure the executeStep() function to not capture screenshots.

You can set CloudWatch Synthetics configurations at the global level, which are applied to all steps of canaries. You can also override these configurations at the step level by passing configuration key/value pairs.

You can pass in options at the step level. For examples, see async executeStep(stepName, functionToExecute, [stepConfig]); and executeHttpStep(stepName, requestOptions, [callback], [stepConfig])

Function definitions:

setConfig(options)

options is an object, which is a set of configurable options for your canary. The following sections explain the possible fields in options.

setConfig(options) for all canaries

For canaries using syn-nodejs-puppeteer-3.2 or later, the (options) for setConfig can include the following parameters:

includeRequestHeaders (boolean)— Whether to include request headers in the report. The default is false.
includeResponseHeaders (boolean)— Whether to include response headers in the report. The default is false.
restrictedHeaders (array)— A list of header values to ignore, if headers are included. This applies to both request and response headers. For example, you can hide your credentials by passing includeRequestHeaders as true and restrictedHeaders as ['Authorization'].
includeRequestBody (boolean)— Whether to include the request body in the report. The default is false.
includeResponseBody (boolean)— Whether to include the response body in the report. The default is false.

setConfig(options) regarding CloudWatch metrics

For canaries using syn-nodejs-puppeteer-3.1 or later, the (options) for setConfig can include the following Boolean parameters that determine which metrics are published by the canary. The default for each of these options is true. The options that start with aggregated determine whether the metric is emitted without the CanaryName dimension. You can use these metrics to see the aggregated results for all of your canaries. The other options determine whether the metric is emitted with the CanaryName dimension. You can use these metrics to see results for each individual canary.

For a list of CloudWatch metrics emitted by canaries, see CloudWatch metrics published by canaries.

failedCanaryMetric (boolean)— Whether to emit the Failed metric (with the CanaryName dimension) for this canary. The default is true.
failedRequestsMetric (boolean)— Whether to emit the Failed requests metric (with the CanaryName dimension) for this canary. The default is true.
_2xxMetric (boolean)— Whether to emit the 2xx metric (with the CanaryName dimension) for this canary. The default is true.
_4xxMetric (boolean)— Whether to emit the 4xx metric (with the CanaryName dimension) for this canary. The default is true.
_5xxMetric (boolean)— Whether to emit the 5xx metric (with the CanaryName dimension) for this canary. The default is true.
stepDurationMetric (boolean)— Whether to emit the Step duration metric (with the CanaryName StepName dimensions) for this canary. The default is true.
stepSuccessMetric (boolean)— Whether to emit the Step success metric (with the CanaryName StepName dimensions) for this canary. The default is true.
aggregatedFailedCanaryMetric (boolean)— Whether to emit the Failed metric (without the CanaryName dimension) for this canary. The default is true.
aggregatedFailedRequestsMetric (boolean)— Whether to emit the Failed Requests metric (without the CanaryName dimension) for this canary. The default is true.
aggregated2xxMetric (boolean)— Whether to emit the 2xx metric (without the CanaryName dimension) for this canary. The default is true.
aggregated4xxMetric (boolean)— Whether to emit the 4xx metric (without the CanaryName dimension) for this canary. The default is true.
aggregated5xxMetric (boolean)— Whether to emit the 5xx metric (without the CanaryName dimension) for this canary. The default is true.
visualMonitoringSuccessPercentMetric (boolean)— Whether to emit the visualMonitoringSuccessPercent metric for this canary. The default is true.
visualMonitoringTotalComparisonsMetric (boolean)— Whether to emit the visualMonitoringTotalComparisons metric for this canary. The default is false.
stepsReport (boolean)— Whether to report a step execution summary. The default is true.
includeUrlPassword (boolean)— Whether to include a password that appears in the URL. By default, passwords that appear in URLs are redacted from logs and reports, to prevent disclosing sensitive data. The default is false.
restrictedUrlParameters (array)— A list of URL path or query parameters to redact. This applies to URLs appearing in logs, reports, and errors. The parameter is case-insensitive. You can pass an asterisk (*) as a value to redact all URL path and query parameter values. The default is an empty array.
logRequest (boolean)— Whether to log every request in canary logs. For UI canaries, this logs each request sent by the browser. The default is true.
logResponse (boolean)— Whether to log every response in canary logs. For UI canaries, this logs every response received by the browser. The default is true.
logRequestBody (boolean)— Whether to log request bodies along with the requests in canary logs. This configuration applies only if logRequest is true. The default is false.
logResponseBody (boolean)— Whether to log response bodies along with the responses in canary logs. This configuration applies only if logResponse is true. The default is false.
logRequestHeaders (boolean)— Whether to log request headers along with the requests in canary logs. This configuration applies only if logRequest is true. The default is false.

Note that includeRequestHeaders enables headers in artifacts.
logResponseHeaders (boolean)— Whether to log response headers along with the responses in canary logs. This configuration applies only if logResponse is true. The default is false.

Note that includeResponseHeaders enables headers in artifacts.

Note

The Duration and SuccessPercent metrics are always emitted for each canary, both with and without the CanaryName metric.

Methods to enable or disable metrics

disableAggregatedRequestMetrics()

Disables the canary from emitting all request metrics that are emitted with no CanaryName dimension.

disableRequestMetrics()

Disables all request metrics, including both per-canary metrics and metrics aggregated across all canaries.

disableStepMetrics()

Disables all step metrics, including both step success metrics and step duration metrics.

enableAggregatedRequestMetrics()

Enables the canary to emit all request metrics that are emitted with no CanaryName dimension.

enableRequestMetrics()

Enables all request metrics, including both per-canary metrics and metrics aggregated across all canaries.

enableStepMetrics()

Enables all step metrics, including both step success metrics and step duration metrics.

get2xxMetric()

Returns whether the canary emits a 2xx metric with the CanaryName dimension.

get4xxMetric()

Returns whether the canary emits a 4xx metric with the CanaryName dimension.

get5xxMetric()

Returns whether the canary emits a 5xx metric with the CanaryName dimension.

getAggregated2xxMetric()

Returns whether the canary emits a 2xx metric with no dimension.

getAggregated4xxMetric()

Returns whether the canary emits a 4xx metric with no dimension.

getAggregatedFailedCanaryMetric()

Returns whether the canary emits a Failed metric with no dimension.

getAggregatedFailedRequestsMetric()

Returns whether the canary emits a Failed requests metric with no dimension.

getAggregated5xxMetric()

Returns whether the canary emits a 5xx metric with no dimension.

getFailedCanaryMetric()

Returns whether the canary emits a Failed metric with the CanaryName dimension.

getFailedRequestsMetric()

Returns whether the canary emits a Failed requests metric with the CanaryName dimension.

getStepDurationMetric()

Returns whether the canary emits a Duration metric with the CanaryName dimension for this canary.

getStepSuccessMetric()

Returns whether the canary emits a StepSuccess metric with the CanaryName dimension for this canary.

with2xxMetric(_2xxMetric)

Accepts a Boolean argument, which specifies whether to emit a 2xx metric with the CanaryName dimension for this canary.

with4xxMetric(_4xxMetric)

Accepts a Boolean argument, which specifies whether to emit a 4xx metric with the CanaryName dimension for this canary.

with5xxMetric(_5xxMetric)

Accepts a Boolean argument, which specifies whether to emit a 5xx metric with the CanaryName dimension for this canary.

withAggregated2xxMetric(aggregated2xxMetric)

Accepts a Boolean argument, which specifies whether to emit a 2xx metric with no dimension for this canary.

withAggregated4xxMetric(aggregated4xxMetric)

Accepts a Boolean argument, which specifies whether to emit a 4xx metric with no dimension for this canary.

withAggregated5xxMetric(aggregated5xxMetric)

Accepts a Boolean argument, which specifies whether to emit a 5xx metric with no dimension for this canary.

withAggregatedFailedCanaryMetric(aggregatedFailedCanaryMetric)

Accepts a Boolean argument, which specifies whether to emit a Failed metric with no dimension for this canary.

withAggregatedFailedRequestsMetric(aggregatedFailedRequestsMetric)

Accepts a Boolean argument, which specifies whether to emit a Failed requests metric with no dimension for this canary.

withFailedCanaryMetric(failedCanaryMetric)

Accepts a Boolean argument, which specifies whether to emit a Failed metric with the CanaryName dimension for this canary.

withFailedRequestsMetric(failedRequestsMetric)

Accepts a Boolean argument, which specifies whether to emit a Failed requests metric with the CanaryName dimension for this canary.

withStepDurationMetric(stepDurationMetric)

Accepts a Boolean argument, which specifies whether to emit a Duration metric with the CanaryName dimension for this canary.

withStepSuccessMetric(stepSuccessMetric)

Accepts a Boolean argument, which specifies whether to emit a StepSuccess metric with the CanaryName dimension for this canary.

Methods to enable or disable other features

withHarFile()

Accepts a Boolean argument, which specifies whether to create a HAR file for this canary.

withStepsReport()

Accepts a Boolean argument, which specifies whether to report a step execution summary for this canary.

withIncludeUrlPassword()

Accepts a Boolean argument, which specifies whether to include passwords that appear in URLs in logs and reports.

withRestrictedUrlParameters()

Accepts an array of URL path or query parameters to redact. This applies to URLs appearing in logs, reports, and errors. You can pass an asterisk (*) as a value to redact all URL path and query parameter values

withLogRequest()

Accepts a Boolean argument, which specifies whether to log every request in the canary's logs.

withLogResponse()

Accepts a Boolean argument, which specifies whether to log every response in the canary's logs.

withLogRequestBody()

Accepts a Boolean argument, which specifies whether to log every request body in the canary's logs.

withLogResponseBody()

Accepts a Boolean argument, which specifies whether to log every response body in the canary's logs.

withLogRequestHeaders()

Accepts a Boolean argument, which specifies whether to log every request header in the canary's logs.

withLogResponseHeaders()

Accepts a Boolean argument, which specifies whether to log every response header in the canary's logs.

getHarFile()

Returns whether the canary creates a HAR file.

getStepsReport()

Returns whether the canary reports a step execution summary.

getIncludeUrlPassword()

Returns whether the canary includes passwords that appear in URLs in logs and reports.

getRestrictedUrlParameters()

Returns whether the canary redacts URL path or query parameters.

getLogRequest()

Returns whether the canary logs every request in the canary's logs.

getLogResponse()

Returns whether the canary logs every response in the canary's logs.

getLogRequestBody()

Returns whether the canary logs every request body in the canary's logs.

getLogResponseBody()

Returns whether the canary logs every response body in the canary's logs.

getLogRequestHeaders()

Returns whether the canary logs every request header in the canary's logs.

getLogResponseHeaders()

Returns whether the canary logs every response header in the canary's logs.

Functions for all canaries

withIncludeRequestHeaders(includeRequestHeaders)
withIncludeResponseHeaders(includeResponseHeaders)
withRestrictedHeaders(restrictedHeaders)
withIncludeRequestBody(includeRequestBody)
withIncludeResponseBody(includeResponseBody)
enableReportingOptions()— Enables all reporting options-- includeRequestHeaders, includeResponseHeaders, includeRequestBody, and includeResponseBody, .
disableReportingOptions()— Disables all reporting options-- includeRequestHeaders, includeResponseHeaders, includeRequestBody, and includeResponseBody, .

setConfig(options) for UI canaries

For UI canaries, setConfig can include the following Boolean parameters:

continueOnStepFailure (boolean)— Whether to continue with running the canary script after a step fails (this refers to the executeStep function). If any steps fail, the canary run will still be marked as failed. The default is false.
harFile (boolean)— Whether to create a HAR file. The default is True.
screenshotOnStepStart (boolean)— Whether to take a screenshot before starting a step.
screenshotOnStepSuccess (boolean)— Whether to take a screenshot after completing a successful step.
screenshotOnStepFailure (boolean)— Whether to take a screenshot after a step fails.

Methods to enable or disable screenshots

disableStepScreenshots()

Disables all screenshot options (screenshotOnStepStart, screenshotOnStepSuccess, and screenshotOnStepFailure).

enableStepScreenshots()

Enables all screenshot options (screenshotOnStepStart, screenshotOnStepSuccess, and screenshotOnStepFailure). By default, all these methods are enabled.

getScreenshotOnStepFailure()

Returns whether the canary takes a screenshot after a step fails.

getScreenshotOnStepStart()

Returns whether the canary takes a screenshot before starting a step.

getScreenshotOnStepSuccess()

Returns whether the canary takes a screenshot after completing a step successfully.

withScreenshotOnStepStart(screenshotOnStepStart)

Accepts a Boolean argument, which indicates whether to take a screenshot before starting a step.

withScreenshotOnStepSuccess(screenshotOnStepSuccess)

Accepts a Boolean argument, which indicates whether to take a screenshot after completing a step successfully.

withScreenshotOnStepFailure(screenshotOnStepFailure)

Accepts a Boolean argument, which indicates whether to take a screenshot after a step fails.

Usage in UI canaries

First, import the synthetics dependency and fetch the configuration.


// Import Synthetics dependency
const synthetics = require('Synthetics');

// Get Synthetics configuration
const synConfig = synthetics.getConfiguration();

Then, set the configuration for each option by calling the setConfig method using one of the following options.


// Set configuration values
    synConfig.setConfig({
        screenshotOnStepStart: true, 
        screenshotOnStepSuccess: false,
        screenshotOnStepFailure: false
    });


synConfig.withScreenshotOnStepStart(false).withScreenshotOnStepSuccess(true).withScreenshotOnStepFailure(true)

To disable all screenshots, use the disableStepScreenshots() function as in this example.


synConfig.disableStepScreenshots();

You can enable and disable screenshots at any point in the code. For example, to disable screenshots only for one step, disable them before running that step and then enable them after the step.

setConfig(options) for API canaries

For API canaries, setConfig can include the following Boolean parameters:

continueOnHttpStepFailure (boolean)— Whether to continue with running the canary script after an HTTP step fails (this refers to the executeHttpStep function). If any steps fail, the canary run will still be marked as failed. The default is true.

Visual monitoring

Visual monitoring compares screenshots taken during a canary run with screenshots taken during a baseline canary run. If the discrepancy between the two screenshots is beyond a threshold percentage, the canary fails and you can see the areas with differences highlighted in color in the canary run report. Visual monitoring is supported in canaries running syn-puppeteer-node-3.2 and later. It is not currently supported in canaries running Python and Selenium.

To enable visual monitoring, add the following line of code to the canary script. For more details, see SyntheticsConfiguration class.


syntheticsConfiguration.withVisualCompareWithBaseRun(true);

The first time that the canary runs successfully after this line is added to the script, it uses the screenshots taken during that run as the baseline for comparison. After that first canary run, you can use the CloudWatch console to edit the canary to do any of the following:

Set the next run of the canary as the new baseline.
Draw boundaries on the current baseline screenshot to designate areas of the screenshot to ignore during visual comparisons.
Remove a screenshot from being used for visual monitoring.

For more information about using the CloudWatch console to edit a canary, see Edit or delete a canary.

Other options for visual monitoring

syntheticsConfiguration.withVisualVarianceThresholdPercentage(desiredPercentage)

Set the acceptable percentage for screenshot variance in visual comparisons.

syntheticsConfiguration.withVisualVarianceHighlightHexColor("#fafa00")

Set the highlight color that designates variance areas when you look at canary run reports that use visual monitoring.

syntheticsConfiguration.withFailCanaryRunOnVisualVariance(failCanary)

Set whether or not the canary fails when there is a visual difference that is more than the threshold. The default is to fail the canary.

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 Synthetics 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 to 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);