# Library functions available for canary scripts
<a name="CloudWatch_Synthetics_Canaries_Function_Library"></a>

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

Some 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.

**Note**  
Whenever you upgrade a canary to use a new version of the the Synthetics runtime, all Synthetics library functions that your canary uses are also automatically upgraded to the same version of NodeJS that the Synthetics runtime supports.

**Topics**
+ [Library functions available for Node.js canary](Library_function_Nodejs.md)
+ [Library functions available for Java canary](CloudWatch_Synthetics_Canaries_Java.md)
+ [Library functions available for Node.js canary scripts using Playwright](CloudWatch_Synthetics_Canaries_Nodejs_Playwright.md)
+ [Library functions available for Node.js canary scripts using Puppeteer](CloudWatch_Synthetics_Canaries_Library_Nodejs.md)
+ [Library functions available for Python canary scripts using Selenium](CloudWatch_Synthetics_Canaries_Library_Python.md)

# Library functions available for Node.js canary
<a name="Library_function_Nodejs"></a>

This section describes the library functions that are available for canary scripts using the Node.js runtime.

**Topics**
+ [addExecutionError(errorMessage, ex);](#Library_function_Nodejs_addExecutionError_Nodecanary)
+ [getCanaryName();](#Library_function_Nodejs_getCanaryName)
+ [getCanaryArn();](#Library_function_Nodejs_Nodecanary)
+ [getCanaryUserAgentString();](#Library_function_Nodejs_getCanaryUserAgentString_Nodecanary)
+ [getRuntimeVersion();](#Library_function_Nodejs_getRuntimeVersion_Nodecanary)
+ [getLogLevel();](#Library_function_Nodejs_getLogLevel_Nodecanary)
+ [setLogLevel();](#Library_function_Nodejs_setLogLevel_Nodecanary)
+ [executeStep(stepName, functionToExecute, [stepConfig])](#Library_function_Nodejs_executestep_Nodecanary)
+ [executeHttpStep(stepName, requestOptions, [callback], [stepConfig])](#Library_function_Nodejs_executeHttpStep)

## addExecutionError(errorMessage, ex);
<a name="Library_function_Nodejs_addExecutionError_Nodecanary"></a>

`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.executeStep(stepName, callbackFunc);} catch(ex) {synthetics.addExecutionError('Unable to take screenshot ', ex);}
```

## getCanaryName();
<a name="Library_function_Nodejs_getCanaryName"></a>

Returns the name of the canary.

## getCanaryArn();
<a name="Library_function_Nodejs_Nodecanary"></a>

Returns the ARN of the canary.

## getCanaryUserAgentString();
<a name="Library_function_Nodejs_getCanaryUserAgentString_Nodecanary"></a>

Returns the custom user agent of the canary.

## getRuntimeVersion();
<a name="Library_function_Nodejs_getRuntimeVersion_Nodecanary"></a>

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

## getLogLevel();
<a name="Library_function_Nodejs_getLogLevel_Nodecanary"></a>

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();
<a name="Library_function_Nodejs_setLogLevel_Nodecanary"></a>

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

## executeStep(stepName, functionToExecute, [stepConfig])
<a name="Library_function_Nodejs_executestep_Nodecanary"></a>

Executes the provided step, wrapping it with start/pass/fail logging and pass/fail and duration metrics.

The `executeStep` function also does the following:
+ Logs that the step started
+ Starts a timer
+ Executes the provided function
+ When the function returns normally, it counts as passing. If the function throws, it counts as failing
+ Ends the timer
+ Logs whether the step passed or 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
+ Returns what the functionToExecute returned or re-throws what ` functionToExecute` threw
+ Adds a step execution summary to the canary's report

 **Example** 

```
await synthetics.executeStep(stepName, async function () {
    return new Promise((resolve, reject) => {
        const req = https.request(url, (res) => {
            console.log(`Status: ${res.statusCode}`);
            if (res.statusCode >= 400) {
                reject(new Error(`Request failed with status ${res.statusCode} for ${url}`));
            } else {
                resolve();
            }
        });

        req.on('error', (err) => {
            reject(new Error(`Request failed for ${url}: ${err.message}`));
        });

        req.end();
    });
});
```

## executeHttpStep(stepName, requestOptions, [callback], [stepConfig])
<a name="Library_function_Nodejs_executeHttpStep"></a>

Executes the provided HTTP request as a step, and publishes `SuccessPercent` (pass/fail) and `Duration` metrics.

**executeHttpStep** uses either HTTP or HTTPS native functions under the hood, depending upon the protocol specified in the request.

This function also adds a step execution summary to the canary's report. The summary includes details about each HTTP request, such as the following:
+ Start time
+ End time
+ Status (PASSED/FAILED)
+ Failure reason, if it failed
+ HTTP call details such as request/response headers, body, status code, status message, and performance timings. 

**Topics**
+ [Parameters](#Library_function_Nodejs_executeHttpStep_parameters_Nodecanary)
+ [Examples of using executeHttpStep](#Library_function_Nodejs_executeHttpStep_examples_Nodecanary)

### Parameters
<a name="Library_function_Nodejs_executeHttpStep_parameters_Nodecanary"></a>

 **stepName(*String*)** 

Specifies the name of the step. This name is also used for publishing CloudWatch metrics for this step.

 **requestOptions(*Object or String*)** 

The value of this parameter can be a URL, a URL string, or an object. If it is an object, then it must be a set of configurable options to make an HTTP request. It supports all options in [ http.request(options[, callback])](https://nodejs.org/api/http.html#http_http_request_options_callback) in the Node.js documentation.

In addition to these Node.js options, **requestOptions** supports the additional parameter `body`. You can use the `body` parameter to pass data as a request body.

 **callback(*response*)** 

(Optional) This is a user function which is invoked with the HTTP response. The response is of the type [ Class: http.IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage).

 **stepConfig(*object*)** 

(Optional) Use this parameter to override global synthetics configurations with a different configuration for this step.

### Examples of using executeHttpStep
<a name="Library_function_Nodejs_executeHttpStep_examples_Nodecanary"></a>

The following series of examples build on each other to illustrate the various uses of this option.

This first example configures request parameters. You can pass a URL as ** requestOptions**:

```
let requestOptions = 'https://www.amazon.com';
```

Or you can pass a set of options:

```
let requestOptions = {
        'hostname': 'myproductsEndpoint.com',
        'method': 'GET',
        'path': '/test/product/validProductName',
        'port': 443,
        'protocol': 'https:'
    };
```

The next example creates a callback function which accepts a response. By default, if you do not specify **callback**, CloudWatch Synthetics validates that the status is between 200 and 299 inclusive.

```
// Handle validation for positive scenario
    const callback = async function(res) {
        return new Promise((resolve, reject) => {
            if (res.statusCode < 200 || res.statusCode > 299) {
                throw res.statusCode + ' ' + res.statusMessage;
            }
     
            let responseBody = '';
            res.on('data', (d) => {
                responseBody += d;
            });
     
            res.on('end', () => {
                // Add validation on 'responseBody' here if required. For ex, your status code is 200 but data might be empty
                resolve();
            });
        });
    };
```

The next example creates a configuration for this step that overrides the global CloudWatch Synthetics configuration. The step configuration in this example allows request headers, response headers, request body (post data), and response body in your report and restrict 'X-Amz-Security-Token' and 'Authorization' header values. By default, these values are not included in the report for security reasons. If you choose to include them, the data is only stored in your S3 bucket.

```
// By default headers, post data, and response body are not included in the report for security reasons. 
// Change the configuration at global level or add as step configuration for individual steps
let stepConfig = {
    includeRequestHeaders: true, 
    includeResponseHeaders: true,
    restrictedHeaders: ['X-Amz-Security-Token', 'Authorization'], // Restricted header values do not appear in report generated.
    includeRequestBody: true,
    includeResponseBody: true
};
```

This final example passes your request to **executeHttpStep** and names the step.

```
await synthetics.executeHttpStep('Verify GET products API', requestOptions, callback, stepConfig);
```

With this set of examples, CloudWatch Synthetics adds the details from each step in your report and produces metrics for each step using **stepName**.

 You will see `successPercent` and `duration` metrics for the `Verify GET products API` step. You can monitor your API performance by monitoring the metrics for your API call steps. 

For a sample complete script that uses these functions, see [Multi-step API canary](CloudWatch_Synthetics_Canaries_Samples.md#CloudWatch_Synthetics_Canaries_Samples_APIsteps).

# Library functions available for Java canary
<a name="CloudWatch_Synthetics_Canaries_Java"></a>

The `executeStep` function is used to modularize the canary code and execute it in steps. In CloudWatch Synthetics, a Synthetics step is a way to break down your canary script into a series of clearly defined actions, allowing you to monitor different parts of your application journey separately. For each step, CloudWatch Synthetics does the following:
+ A report, including a summary of step execution details like the duration of a step, *pass* or *fail* status, and so on, is created for each canary run. When you choose a run in the CloudWatch Synthetics console, you can view execution details of each step on the **Step** tab.
+ *SuccessPercent* and *Duration* CloudWatch metrics are emitted for each step, enabling users to monitor availability and latency of each step.

   **Usage** 

  ```
  synthetics.executeStep(stepName,()->{
      try {
          //step code to be executed
          return null;
      } catch (Exception e) {
          throw e;
      }
  }).get();
  ```

   **Parameters** 
  + *stepName*, String (required) – A descriptive name of the Synthetics step
  + *function to execute*, Callable<T> (required) – Represents the tasks to be executed
  + *stepOptions*, `com.amazonaws.synthetics.StepOptions (optional)` – StepOptions object that can be used to configure the step execution. 

    *stepConfiguration*, ` com.amazonaws.synthetics.StepConfiguration`(required as part of the stepOptions)

 **Returns** 

The value returned is *CompletableFuture<T>*.

**Note**  
Synthetics only supports sequential steps. Make sure to call the `.get()` method as shown in the example to ensure that the step completes before proceeding to the subsequent step.

# Library functions available for Node.js canary scripts using Playwright
<a name="CloudWatch_Synthetics_Canaries_Nodejs_Playwright"></a>

This section describes the library functions that are available for canary scripts using the Node.js Playwright runtime.

**Topics**
+ [launch](#Synthetics_Library_Nodejs_Playwright_functions)
+ [newPage](#Synthetics_Library_Nodejs_Playwright_function_newPage)
+ [close](#Synthetics_Library_Nodejs_Playwright_function_close)
+ [getDefaultLaunchOptions](#Synthetics_Library_Nodejs_Playwright_function_getDefaultLaunchOptions)
+ [executeStep](#Synthetics_Library_Nodejs_Playwright_function_executeStep)

## launch
<a name="Synthetics_Library_Nodejs_Playwright_functions"></a>

This function launches a Chromium browser using a Playwright launch function, and returns the browser object. It decompresses browser binaries and launches the chromium browser by using default options suitable for a headless browser. For more information about the `launch` function, see [https://playwright.dev/docs/api/class-browsertype#browser-type-launch](https://playwright.dev/docs/api/class-browsertype#browser-type-launch) in the Playwright documentation.

 **Usage** 

```
const browser = await synthetics.launch();
```

 **Arguments** 

`options` [options](https://playwright.dev/docs/api/class-browsertype#browser-type-launch) (optional) is a configurable set of options for the browser.

 **Returns** 

Promise `<Browser>` where [Browser](https://playwright.dev/docs/api/class-browser) is a Playwright browser instance.

If this function is called again, a previously-opened browser is closed before initiating a new browser. You can override launch parameters used by CloudWatch Synthetics, and pass additional parameters when launching the browser. For example, the following code snippet launches a browser with default arguments and a default executable path, but with a viewport of 800 x 600 pixels. For more information, see [Playwright launch options](https://playwright.dev/docs/api/class-browsertype#browser-type-launch) in the Playwright documentation.

```
const browser = await synthetics.launch({
  defaultViewport: { 
      "deviceScaleFactor": 1, 
      "width": 800,
      "height": 600 
}});
```

 You can also add or override Chromium flags passed on by default to the browser. For example, you can disable web security by adding a `--disable-web-security` flag to arguments in the CloudWatch Synthetics launch parameters: 

```
// This function adds the --disable-web-security flag to the launch parameters
const defaultOptions = await synthetics.getDefaultLaunchOptions();
const launchArgs = [...defaultOptions.args, '--disable-web-security'];
const browser = await synthetics.launch({
    args: launchArgs
  });
```

## newPage
<a name="Synthetics_Library_Nodejs_Playwright_function_newPage"></a>

The `newPage()` function creates and returns a new Playwright page. Synthetics automatically sets up a Chrome DevTools Protocol (CDP) connection to enable network captures for HTTP archive (HAR) generation.

 **Usage** 

Use `newPage()` in either of the following ways:

 **1. Creating a new page in a new browser context:** 

```
const page = await synthetics.newPage(browser);
```

 **2. Creating a new page in a specified browser context:** 

```
// Create a new browser context
const browserContext = await browser.newContext();

// Create a new page in the specified browser context
const page = await synthetics.newPage(browserContext)
```

 **Arguments** 

Accepts either Playwright [Browser](https://playwright.dev/docs/api/class-browser) instance or Playwright [ BrowserContext](https://playwright.dev/docs/api/class-browsercontext) instance. 

 **Returns** 

Promise <Page> where Page is a Playwright [Page](https://playwright.dev/docs/api/class-page) instance.

## close
<a name="Synthetics_Library_Nodejs_Playwright_function_close"></a>

Closes the currently-opened browser.

 **Usage** 

```
await synthetics.close();
```

It is recommended to close the browser in a `finally` block of your script.

 **Arguments** 

None 

 **Returns** 

Returns Promise<void> used by the Synthetics launch function for launching the browser.

## getDefaultLaunchOptions
<a name="Synthetics_Library_Nodejs_Playwright_function_getDefaultLaunchOptions"></a>

The `getDefaultLaunchOptions()` function returns the browser launch options that are used by CloudWatch Synthetics.

 **Usage** 

```
const defaultOptions = await synthetics.getDefaultLaunchOptions();
```

 **Arguments** 

None 

 **Returns** 

Returns Playwright [ launch options](https://playwright.dev/docs/api/class-browsertype#browser-type-launch) used by the Synthetics `launch` function for launching the browser.

## executeStep
<a name="Synthetics_Library_Nodejs_Playwright_function_executeStep"></a>

The `executeStep` function is used to execute a step in a Synthetics script. In CloudWatch Synthetics, a Synthetics step is a way to break down your canary script into a series of clearly defined actions, allowing you to monitor different parts of your application journey separately. For each step, CloudWatch Synthetics does the following:
+ Automatically captures a screenshot before step starts and after a step is complete. You can also capture screenshots inside a step. Screenshots are captured by default, but can be turned off by using Synthetics configurations.
+ A report, including a summary, of step execution details like the duration of a step, `pass` or `fail` status, source and destination page URLs, associated screenshots, etc. is created for each canary run. When you choose a run in the CloudWatch Synthetics console, you can view execution details of each step on the **Step** tab.
+ `SuccessPercent` and `Duration` CloudWatch metrics are emitted for each step, enabling users to monitor availability and latency of each step.

 **Usage** 

```
await synthetics.executeStep("mystepname", async function () {
  await page.goto(url, { waitUntil: 'load', timeout: 30000 });
}
```

**Note**  
Steps should run sequentially. Be sure to use `await` on promises.

 **Arguments** 
+ `stepName` string (required) (boolean)— Name of the Synthetics step. 
+ `functionToExecute` async function (required)— The function that you want Synthetics to run. This function should contain the logic for the step.
+ `stepConfig` object (optional)— Step configuration overrides the global Synthetics configuration for this step.
  + `continueOnStepFailure` boolean (optional) — Whether to continue running the canary script after this step fails. 
  + `screenshotOnStepStart` boolean (optional) — Whether to take a screenshot at the start of this step. 
  + `screenshotOnStepSuccess` boolean (optional) — Whether to take a screenshot if this step succeeds. 
  + `screenshotOnStepFailure` boolean (optional) — Whether to take a screenshot if this step fails. 
+ `page` — Playwright page object (optional)

  A Playwright page object. Synthetics uses this page object to capture screenshots and URLs. By default, Synthetics uses the Playwright page created when the `synthetics.newPage()` function is called for capturing page details like screenshots and URLs.

 **Returns** 

Returns a Promise that resolves with the value returned by the ` functionToExecute` function. For an example script, see [Sample code for canary scripts](CloudWatch_Synthetics_Canaries_Samples.md) in this guide.

# Library functions available for Node.js canary scripts using Puppeteer
<a name="CloudWatch_Synthetics_Canaries_Library_Nodejs"></a>

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

**Topics**
+ [Node.js library classes and functions that apply to all canaries](#CloudWatch_Synthetics_Library_allcanaries)
+ [Node.js library classes and functions that apply to UI canaries only](#CloudWatch_Synthetics_Library_UIcanaries)
+ [Node.js library classes and functions that apply to API canaries only](#CloudWatch_Synthetics_Library_APIcanaries)

## Node.js library classes and functions that apply to all canaries
<a name="CloudWatch_Synthetics_Library_allcanaries"></a>

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

**Topics**
+ [Synthetics class](#CloudWatch_Synthetics_Library_Synthetics_Class_all)
+ [SyntheticsConfiguration class](#CloudWatch_Synthetics_Library_SyntheticsConfiguration)
+ [Synthetics logger](#CloudWatch_Synthetics_Library_SyntheticsLogger)
+ [SyntheticsLogHelper class](#CloudWatch_Synthetics_Library_SyntheticsLogHelper)

### Synthetics class
<a name="CloudWatch_Synthetics_Library_Synthetics_Class_all"></a>

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

**Topics**
+ [addExecutionError(errorMessage, ex);](#CloudWatch_Synthetics_Library_addExecutionError)
+ [getCanaryName();](#CloudWatch_Synthetics_Library_getCanaryName)
+ [getCanaryArn();](#CloudWatch_Synthetics_Library_getCanaryARN)
+ [getCanaryUserAgentString();](#CloudWatch_Synthetics_Library_getCanaryUserAgentString)
+ [getRuntimeVersion();](#CloudWatch_Synthetics_Library_getRuntimeVersion)
+ [getLogLevel();](#CloudWatch_Synthetics_Library_getLogLevel)
+ [setLogLevel();](#CloudWatch_Synthetics_Library_setLogLevel)

#### addExecutionError(errorMessage, ex);
<a name="CloudWatch_Synthetics_Library_addExecutionError"></a>

`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();
<a name="CloudWatch_Synthetics_Library_getCanaryName"></a>

Returns the name of the canary.

#### getCanaryArn();
<a name="CloudWatch_Synthetics_Library_getCanaryARN"></a>

Returns the ARN of the canary.

#### getCanaryUserAgentString();
<a name="CloudWatch_Synthetics_Library_getCanaryUserAgentString"></a>

Returns the custom user agent of the canary.

#### getRuntimeVersion();
<a name="CloudWatch_Synthetics_Library_getRuntimeVersion"></a>

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();
<a name="CloudWatch_Synthetics_Library_getLogLevel"></a>

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();
<a name="CloudWatch_Synthetics_Library_setLogLevel"></a>

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
<a name="CloudWatch_Synthetics_Library_SyntheticsConfiguration"></a>

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 and value pairs.

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

**Topics**
+ [setConfig(options)](#CloudWatch_Synthetics_Library_setConfig)
+ [Visual monitoring](#CloudWatch_Synthetics_Library_SyntheticsLogger_VisualTesting)

#### setConfig(options)
<a name="CloudWatch_Synthetics_Library_setConfig"></a>

` 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
<a name="CloudWatch_Synthetics_Library_setConfigall"></a>

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`.
**Important**  
If you enable either `includeResponseBody` or ` logResponseBody`, the data object is not returned in the response from some APIs, such as aws-sdk v3 clients. This is because of a limitation of Node.js and the type of response object used.

 **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](CloudWatch_Synthetics_Canaries_metrics.md).
+ `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`.
+ `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 (\$1) 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`.
**Important**  
If you enable either `includeResponseBody` or ` logResponseBody`, the data object is not returned in the response from some APIs, such as aws-sdk v3 clients. This is because of a limitation of Node.js and the type of response object used.
+ `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
<a name="CloudWatch_Synthetics_Library_setConfig_metrics"></a>

 **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(\$12xxMetric)** 

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

 **with4xxMetric(\$14xxMetric)** 

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

 **with5xxMetric(\$15xxMetric)** 

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
<a name="CloudWatch_Synthetics_Library_setConfig_methods"></a>

 **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 (\$1) 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
<a name="CloudWatch_Synthetics_Library_setConfigUI"></a>

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
<a name="CloudWatch_Synthetics_Library_setConfig_screenshots"></a>

 **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('@aws/synthetics-puppeteer');

// 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
    });
```

Or

```
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
<a name="CloudWatch_Synthetics_Library_setConfigAPI"></a>

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
<a name="CloudWatch_Synthetics_Library_SyntheticsLogger_VisualTesting"></a>

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](#CloudWatch_Synthetics_Library_SyntheticsConfiguration).

```
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](synthetics_canaries_deletion.md).

 **Other options for visual monitoring** 

 ** syntheticsConfiguration.withVisualVarianceThresholdPercentage(desiredPercentage)** 

Set the acceptable percentage for screenshot variance in visual comparisons.

 ** syntheticsConfiguration.withVisualVarianceHighlightHexColor("\$1fafa00")** 

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
<a name="CloudWatch_Synthetics_Library_SyntheticsLogger"></a>

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('@aws/synthetics-logger');
```

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

### SyntheticsLogHelper class
<a name="CloudWatch_Synthetics_Library_SyntheticsLogHelper"></a>

The `SyntheticsLogHelper` class is available in the runtime ` syn-nodejs-puppeteer-3.2` and later runtimes. It is already initialized in the CloudWatch Synthetics library and is configured with Synthetics configuration. You can add this as a dependency in your script. This class enables you to sanitize URLs, headers, and error messages to redact sensitive information.

**Note**  
Synthetics sanitizes all URLs and error messages it logs before including them in logs, reports, HAR files, and canary run errors based on the Synthetics configuration setting `restrictedUrlParameters`. You have to use ` getSanitizedUrl` or `getSanitizedErrorMessage` only if you are logging URLs or errors in your script. Synthetics does not store any canary artifacts except for canary errors thrown by the script. Canary run artifacts are stored in your customer account. For more information, see [Security considerations for Synthetics canaries](servicelens_canaries_security.md).

**Topics**
+ [getSanitizedUrl(url, stepConfig = null)](#CloudWatch_Synthetics_Library_getSanitizedUrl)
+ [getSanitizedErrorMessage](#CloudWatch_Synthetics_Library_getSanitizedErrorMessage)
+ [getSanitizedHeaders(headers, stepConfig=null)](#CloudWatch_Synthetics_Library_getSanitizedHeaders)

#### getSanitizedUrl(url, stepConfig = null)
<a name="CloudWatch_Synthetics_Library_getSanitizedUrl"></a>

This function is available in `syn-nodejs-puppeteer-3.2` and later. It returns sanitized url strings based on the configuration. You can choose to redact sensitive URL parameters such as password and access\$1token by setting the property `restrictedUrlParameters`. By default, passwords in URLs are redacted. You can enable URL passwords if needed by setting `includeUrlPassword` to true. 

This function throws an error if the URL passed in is not a valid URL.

 **Parameters ** 
+ *url* is a string and is the URL to sanitize.
+  *stepConfig* (Optional) overrides the global Synthetics configuration for this function. If `stepConfig` is not passed in, the global configuration is used to sanitize the URL.

 **Example ** 

This example uses the following sample URL: ` https://example.com/learn/home?access_token=12345&token_type=Bearer&expires_in=1200`. In this example, `access_token` contains your sensitive information which shouldn't be logged. Note that the Synthetics services doesn't store any canary run artifacts. Artifacts such as logs, screenshots, and reports are all stored in an Amazon S3 bucket in your customer account.

The first step is to set the Synthetics configuration.

```
// Import Synthetics dependency
const synthetics = require('@aws/synthetics-puppeteer');

// Import Synthetics logger for logging url
const log = require('@aws/synthetics-logger');

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

// Set restricted parameters
synConfig.setConfig({
   restrictedUrlParameters: ['access_token'];
});
// Import SyntheticsLogHelper dependency
const syntheticsLogHelper = require('@aws/synthetics-log-helper');

const sanitizedUrl = syntheticsLogHelper.getSanitizedUrl('URL');



const urlConfig = {
   restrictedUrlParameters = ['*']
};
const sanitizedUrl = syntheticsLogHelper.getSanitizedUrl('URL', urlConfig);
logger.info('My example url is: ' + sanitizedUrl);
```

Next, sanitize and log the URL

```
// Import SyntheticsLogHelper dependency
const syntheticsLogHelper = require('@aws/synthetics-log-helper');

const sanitizedUrl = syntheticsLogHelper.getSanitizedUrl('https://example.com/learn/home?access_token=12345&token_type=Bearer&expires_in=1200');
```

This logs the following in your canary log.

```
My example url is: https://example.com/learn/home?access_token=REDACTED&token_type=Bearer&expires_in=1200
```

You can override the Synthetics configuration for a URL by passing in an optional parameter containing Synthetics configuration options, as in the following example.

```
const urlConfig = {
   restrictedUrlParameters = ['*']
};
const sanitizedUrl = syntheticsLogHelper.getSanitizedUrl('https://example.com/learn/home?access_token=12345&token_type=Bearer&expires_in=1200', urlConfig);
logger.info('My example url is: ' + sanitizedUrl);
```

The preceding example redacts all query parameters, and is logged as follows:

```
My example url is: https://example.com/learn/home?access_token=REDACTED&token_type=REDACTED&expires_in=REDACTED
```

#### getSanitizedErrorMessage
<a name="CloudWatch_Synthetics_Library_getSanitizedErrorMessage"></a>

This function is available in `syn-nodejs-puppeteer-3.2` and later. It returns sanitized error strings by sanitizing any URLs present based on the Synthetics configuration. You can choose to override the global Synthetics configuration when you call this function by passing an optional `stepConfig` parameter. 

 **Parameters ** 
+ *error* is the error to sanitize. It can be an Error object or a string.
+  *stepConfig* (Optional) overrides the global Synthetics configuration for this function. If `stepConfig` is not passed in, the global configuration is used to sanitize the URL.

 **Example ** 

This example uses the following error: ` Failed to load url: https://example.com/learn/home?access_token=12345&token_type=Bearer&expires_in=1200`

The first step is to set the Synthetics configuration.

```
// Import Synthetics dependency
const synthetics = require('@aws/synthetics-puppeteer');

// Import Synthetics logger for logging url
const log = require('@aws/synthetics-logger');

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

// Set restricted parameters
synConfig.setConfig({
   restrictedUrlParameters: ['access_token'];
});
```

Next, sanitize and log the error message

```
// Import SyntheticsLogHelper dependency
const syntheticsLogHelper = require('@aws/synthetics-log-helper');

try {
   // Your code which can throw an error containing url which your script logs
} catch (error) {
    const sanitizedErrorMessage = syntheticsLogHelper.getSanitizedErrorMessage(errorMessage);
    logger.info(sanitizedErrorMessage);
}
```

This logs the following in your canary log.

```
Failed to load url: https://example.com/learn/home?access_token=REDACTED&token_type=Bearer&expires_in=1200
```

#### getSanitizedHeaders(headers, stepConfig=null)
<a name="CloudWatch_Synthetics_Library_getSanitizedHeaders"></a>

This function is available in `syn-nodejs-puppeteer-3.2` and later. It returns sanitized headers based on the `restrictedHeaders` property of ` syntheticsConfiguration`. The headers specified in the `restrictedHeaders` property are redacted from logs, HAR files, and reports. 

 **Parameters ** 
+ *headers* is an object containing the headers to sanitize.
+ *stepConfig* (Optional) overrides the global Synthetics configuration for this function. If `stepConfig` is not passed in, the global configuration is used to sanitize the headers.

## Node.js library classes and functions that apply to UI canaries only
<a name="CloudWatch_Synthetics_Library_UIcanaries"></a>

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

**Topics**
+ [Synthetics class](#CloudWatch_Synthetics_Library_Synthetics_Class)
+ [BrokenLinkCheckerReport class](#CloudWatch_Synthetics_Library_BrokenLinkCheckerReport)
+ [SyntheticsLink class](#CloudWatch_Synthetics_Library_SyntheticsLink)

### Synthetics class
<a name="CloudWatch_Synthetics_Library_Synthetics_Class"></a>

The following functions are in the Synthetics class.

**Topics**
+ [async addUserAgent(page, userAgentString);](#CloudWatch_Synthetics_Library_addUserAgent)
+ [async executeStep(stepName, functionToExecute, [stepConfig]);](#CloudWatch_Synthetics_Library_executeStep)
+ [getDefaultLaunchOptions();](#CloudWatch_Synthetics_Library_getDefaultLaunchOptions)
+ [getPage();](#CloudWatch_Synthetics_Library_getPage)
+ [getRequestResponseLogHelper();](#CloudWatch_Synthetics_Library_getRequestResponseLogHelper)
+ [launch(options)](#CloudWatch_Synthetics_Library_LaunchOptions)
+ [RequestResponseLogHelper class](#CloudWatch_Synthetics_Library_RequestResponseLogHelper)
+ [setRequestResponseLogHelper();](#CloudWatch_Synthetics_Library_setRequestResponseLogHelper)
+ [async takeScreenshot(name, suffix);](#CloudWatch_Synthetics_Library_takeScreenshot)

#### async addUserAgent(page, userAgentString);
<a name="CloudWatch_Synthetics_Library_addUserAgent"></a>

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, functionToExecute, [stepConfig]);
<a name="CloudWatch_Synthetics_Library_executeStep"></a>

Executes the provided step, wrapping it with start/pass/fail logging, start/pass/fail screenshots, and pass/fail and duration metrics.

**Note**  
If you are using the `syn-nodejs-2.1` or later runtime, you can configure whether and when screenshots are taken. For more information, see [SyntheticsConfiguration class](#CloudWatch_Synthetics_Library_SyntheticsConfiguration).

The `executeStep` function 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.
+ Ends 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.

If the canary uses the `syn-nodejs-2.0` runtime or later, this function also adds a step execution summary to the canary's report. The summary includes details about each step, such as start time, end time, status (PASSED/FAILED), failure reason (if failed), and screenshots captured during the execution of each step.

Example:

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

Response:

Returns what `functionToExecute` returns.

 **Updates with syn-nodejs-2.2** 

Starting with `syn-nodejs-2.2`, you can optionally pass step configurations to override CloudWatch Synthetics configurations at the step level. For a list of options that you can pass to `executeStep`, see [SyntheticsConfiguration class](#CloudWatch_Synthetics_Library_SyntheticsConfiguration).

The following example overrides the default `false` configuration for ` continueOnStepFailure` to `true` and specifies when to take screenthots.

```
var stepConfig = {
    'continueOnStepFailure': true,
    'screenshotOnStepStart': false,
    'screenshotOnStepSuccess': true,
    'screenshotOnStepFailure': false
}

await executeStep('Navigate to amazon', async function (timeoutInMillis = 30000) {
      await page.goto(url, {waitUntil: ['load', 'networkidle0'], timeout: timeoutInMillis});
 }, stepConfig);
```

#### getDefaultLaunchOptions();
<a name="CloudWatch_Synthetics_Library_getDefaultLaunchOptions"></a>

The `getDefaultLaunchOptions()` function returns the browser launch options that are used by CloudWatch Synthetics. For more information, see [Launch options type](https://pptr.dev/browsers-api/browsers.launchoptions/) 

```
// This function returns default launch options used by Synthetics.
const defaultOptions = await synthetics.getDefaultLaunchOptions();
```

#### getPage();
<a name="CloudWatch_Synthetics_Library_getPage"></a>

Returns the current open page as a Puppeteer object. For more information, see [Puppeteer API v1.14.0](https://github.com/puppeteer/puppeteer/blob/v1.14.0/docs/api.md).

Example:

```
let page = await synthetics.getPage();
```

Response:

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

#### getRequestResponseLogHelper();
<a name="CloudWatch_Synthetics_Library_getRequestResponseLogHelper"></a>

**Important**  
In canaries that use the `syn-nodejs-puppeteer-3.2` runtime or later, this function is deprecated along with the `RequestResponseLogHelper` class. Any use of this function causes a warning to appear in your canary logs. This function will be removed in future runtime versions. If you are using this function, use [RequestResponseLogHelper class](#CloudWatch_Synthetics_Library_RequestResponseLogHelper) instead. 

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

Example:

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

Response:

```
{RequestResponseLogHelper}
```

#### launch(options)
<a name="CloudWatch_Synthetics_Library_LaunchOptions"></a>

The options for this function are available only in the `syn-nodejs-2.1` runtime version or later.

This function is used only for UI canaries. It closes the existing browser and launches a new one.

**Note**  
CloudWatch Synthetics always launches a browser before starting to run your script. You don't need to call launch() unless you want to launch a new browser with custom options.

(options) is a configurable set of options to set on the browser. For more information, [Launch options type](https://pptr.dev/browsers-api/browsers.launchoptions/) .

If you call this function with no options, Synthetics launches a browser with default arguments, `executablePath`, and `defaultViewport`. The default viewport in CloudWatch Synthetics is 1920 by 1080.

You can override launch parameters used by CloudWatch Synthetics and pass additional parameters when launching the browser. For example, the following code snippet launches a browser with default arguments and a default executable path, but with a viewport of 800 x 600.

```
await synthetics.launch({
        defaultViewport: { 
            "deviceScaleFactor": 1, 
            "width": 800,
            "height": 600 
    }});
```

The following sample code adds a new `ignoreHTTPSErrors` parameter to the CloudWatch Synthetics launch parameters:

```
await synthetics.launch({
        ignoreHTTPSErrors: true
 });
```

You can disable web security by adding a `--disable-web-security` flag to args in the CloudWatch Synthetics launch parameters:

```
// This function adds the --disable-web-security flag to the launch parameters
const defaultOptions = await synthetics.getDefaultLaunchOptions();
const launchArgs = [...defaultOptions.args, '--disable-web-security'];
await synthetics.launch({
     args: launchArgs
  });
```

#### RequestResponseLogHelper class
<a name="CloudWatch_Synthetics_Library_RequestResponseLogHelper"></a>

**Important**  
In canaries that use the `syn-nodejs-puppeteer-3.2` runtime or later, this class is deprecated. Any use of this class causes a warning to appear in your canary logs. This function will be removed in future runtime versions. If you are using this function, use [RequestResponseLogHelper class](#CloudWatch_Synthetics_Library_RequestResponseLogHelper) instead.

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();
<a name="CloudWatch_Synthetics_Library_setRequestResponseLogHelper"></a>

**Important**  
In canaries that use the `syn-nodejs-puppeteer-3.2` runtime or later, this function is deprecated along with the `RequestResponseLogHelper` class. Any use of this function causes a warning to appear in your canary logs. This function will be removed in future runtime versions. If you are using this function, use [RequestResponseLogHelper class](#CloudWatch_Synthetics_Library_RequestResponseLogHelper) instead. 

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

Example:

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

Response:

```
{RequestResponseLogHelper}
```

#### async takeScreenshot(name, suffix);
<a name="CloudWatch_Synthetics_Library_takeScreenshot"></a>

Takes a screenshot (.PNG) of the current page with name and suffix (optional).

Example:

```
await synthetics.takeScreenshot("navigateToUrl", "loaded")
```

This example captures and uploads a screenshot named ` 01-navigateToUrl-loaded.png` to the canary's S3 bucket.

You can take a screenshot for a particular canary step by passing the ` stepName` as the first parameter. Screenshots are linked to the canary step in your reports, to help you track each step while debugging.

CloudWatch Synthetics canaries automatically take screenshots before starting a step (the `executeStep` function) and after the step completion (unless you configure the canary to disable screenshots). You can take more screenshots by passing in the step name in the `takeScreenshot` function.

The following example takes screenshot with the `signupForm` as the value of the `stepName`. The screenshot will be named ` 02-signupForm-address` and will be linked to the step named ` signupForm` in the canary report.

```
await synthetics.takeScreenshot('signupForm', 'address')
```

### BrokenLinkCheckerReport class
<a name="CloudWatch_Synthetics_Library_BrokenLinkCheckerReport"></a>

This class provides methods to add a synthetics link. It's supported only on canaries that use the `syn-nodejs-2.0-beta` version of the runtime or later. 

To use `BrokenLinkCheckerReport`, include the following lines in the script:

```
const BrokenLinkCheckerReport = require('@aws/synthetics-broken-link-checker-report');
            
const brokenLinkCheckerReport = new BrokenLinkCheckerReport();
```

Useful function definitions:

 **addLink(*syntheticsLink*, isBroken)** 

` syntheticsLink ` is a ` SyntheticsLink` object representing a link. This function adds the link according to the status code. By default, it considers a link to be broken if the status code is not available or the status code is 400 or higher. You can override this default behavior by passing in the optional parameter `isBrokenLink` with a value of `true` or `false`.

This function does not have a return value.

 **getLinks()** 

This function returns an array of `SyntheticsLink` objects that are included in the broken link checker report.

 **getTotalBrokenLinks()** 

This function returns a number representing the total number of broken links.

 **getTotalLinksChecked()** 

This function returns a number representing the total number of links included in the report.

 **How to use BrokenLinkCheckerReport** 

The following canary script code snippet demonstrates an example of navigating to a link and adding it to the broken link checker report.

1. Import `SyntheticsLink`, `BrokenLinkCheckerReport`, and ` Synthetics`.

   ```
   const BrokenLinkCheckerReport = require('@aws/synthetics-broken-link-checker-report');
   const SyntheticsLink = require('@aws/synthetics-link');
   
   // Synthetics dependency
   const synthetics = require('@aws/synthetics-puppeteer');
   ```

1. To add a link to the report, create an instance of ` BrokenLinkCheckerReport`.

   ```
   let brokenLinkCheckerReport = new BrokenLinkCheckerReport();
   ```

1. Navigate to the URL and add it to the broken link checker report.

   ```
   let url = "https://amazon.com";
   
   let syntheticsLink = new SyntheticsLink(url);
   
   // Navigate to the url.
   let page = await synthetics.getPage();
   
   // Create a new instance of Synthetics Link
   let link = new SyntheticsLink(url)
   
   try {
       const response = await page.goto(url, {waitUntil: 'domcontentloaded', timeout: 30000});
   } catch (ex) {
       // Add failure reason if navigation fails.
       link.withFailureReason(ex);
   }
   
   if (response) {
       // Capture screenshot of destination page
       let screenshotResult = await synthetics.takeScreenshot('amazon-home', 'loaded');
      
       // Add screenshot result to synthetics link
       link.addScreenshotResult(screenshotResult);
   
       // Add status code and status description to the link
       link.withStatusCode(response.status()).withStatusText(response.statusText())
   }
   
   // Add link to broken link checker report.
   brokenLinkCheckerReport.addLink(link);
   ```

1. Add the report to Synthetics. This creates a JSON file named ` BrokenLinkCheckerReport.json` in your S3 bucket for each canary run. You can see a links report in the console for each canary run along with screenshots, logs, and HAR files.

   ```
   await synthetics.addReport(brokenLinkCheckerReport);
   ```

### SyntheticsLink class
<a name="CloudWatch_Synthetics_Library_SyntheticsLink"></a>

This class provides methods to wrap information. It's supported only on canaries that use the `syn-nodejs-2.0-beta` version of the runtime or later. 

To use `SyntheticsLink`, include the following lines in the script:

```
const SyntheticsLink = require('@aws/synthetics-link');

const syntheticsLink = new SyntheticsLink("https://www.amazon.com");
```

This function returns `syntheticsLinkObject`

Useful function definitions:

 **withUrl(*url*)** 

` url ` is a URL string. This function returns `syntheticsLinkObject`

 **withText(*text*)** 

` text ` is a string representing anchor text. This function returns `syntheticsLinkObject`. It adds anchor text corresponding to the link.

 **withParentUrl(*parentUrl*)** 

` parentUrl ` is a string representing the parent (source page) URL. This function returns `syntheticsLink Object`

 **withStatusCode(*statusCode*)** 

` statusCode ` is a string representing the status code. This function returns `syntheticsLinkObject`

 **withFailureReason(*failureReason*)** 

` failureReason ` is a string representing the failure reason. This function returns `syntheticsLink Object`

 **addScreenshotResult(*screenshotResult*)** 

` screenshotResult ` is an object. It is an instance of `ScreenshotResult` that was returned by the Synthetics function `takeScreenshot`. The object includes the following:
+ `fileName`— A string representing the ` screenshotFileName`
+ `pageUrl` (optional)
+ `error` (optional)

## Node.js library classes and functions that apply to API canaries only
<a name="CloudWatch_Synthetics_Library_APIcanaries"></a>

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

**Topics**
+ [executeHttpStep(stepName, requestOptions, [callback], [stepConfig])](#CloudWatch_Synthetics_Library_executeHttpStep)

### executeHttpStep(stepName, requestOptions, [callback], [stepConfig])
<a name="CloudWatch_Synthetics_Library_executeHttpStep"></a>

Executes the provided HTTP request as a step, and publishes `SuccessPercent` (pass/fail) and `Duration` metrics.

**executeHttpStep** uses either HTTP or HTTPS native functions under the hood, depending upon the protocol specified in the request.

This function also adds a step execution summary to the canary's report. The summary includes details about each HTTP request, such as the following:
+ Start time
+ End time
+ Status (PASSED/FAILED)
+ Failure reason, if it failed
+ HTTP call details such as request/response headers, body, status code, status message, and performance timings. 

**Topics**
+ [Parameters](#CloudWatch_Synthetics_Library_executeHttpStep_parameters)
+ [Examples of using executeHttpStep](#CloudWatch_Synthetics_Library_executeHttpStep_examples)

#### Parameters
<a name="CloudWatch_Synthetics_Library_executeHttpStep_parameters"></a>

 **stepName(*String*)** 

Specifies the name of the step. This name is also used for publishing CloudWatch metrics for this step.

 **requestOptions(*Object or String*)** 

The value of this parameter can be a URL, a URL string, or an object. If it is an object, then it must be a set of configurable options to make an HTTP request. It supports all options in [ http.request(options[, callback])](https://nodejs.org/api/http.html#http_http_request_options_callback) in the Node.js documentation.

In addition to these Node.js options, **requestOptions** supports the additional parameter `body`. You can use the `body` parameter to pass data as a request body.

 **callback(*response*)** 

(Optional) This is a user function which is invoked with the HTTP response. The response is of the type [ Class: http.IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage).

 **stepConfig(*object*)** 

(Optional) Use this parameter to override global synthetics configurations with a different configuration for this step.

#### Examples of using executeHttpStep
<a name="CloudWatch_Synthetics_Library_executeHttpStep_examples"></a>

The following series of examples build on each other to illustrate the various uses of this option.

This first example configures request parameters. You can pass a URL as ** requestOptions**:

```
let requestOptions = 'https://www.amazon.com';
```

Or you can pass a set of options:

```
let requestOptions = {
        'hostname': 'myproductsEndpoint.com',
        'method': 'GET',
        'path': '/test/product/validProductName',
        'port': 443,
        'protocol': 'https:'
    };
```

The next example creates a callback function which accepts a response. By default, if you do not specify **callback**, CloudWatch Synthetics validates that the status is between 200 and 299 inclusive.

```
// Handle validation for positive scenario
    const callback = async function(res) {
        return new Promise((resolve, reject) => {
            if (res.statusCode < 200 || res.statusCode > 299) {
                throw res.statusCode + ' ' + res.statusMessage;
            }
     
            let responseBody = '';
            res.on('data', (d) => {
                responseBody += d;
            });
     
            res.on('end', () => {
                // Add validation on 'responseBody' here if required. For ex, your status code is 200 but data might be empty
                resolve();
            });
        });
    };
```

The next example creates a configuration for this step that overrides the global CloudWatch Synthetics configuration. The step configuration in this example allows request headers, response headers, request body (post data), and response body in your report and restrict 'X-Amz-Security-Token' and 'Authorization' header values. By default, these values are not included in the report for security reasons. If you choose to include them, the data is only stored in your S3 bucket.

```
// By default headers, post data, and response body are not included in the report for security reasons. 
// Change the configuration at global level or add as step configuration for individual steps
let stepConfig = {
    includeRequestHeaders: true, 
    includeResponseHeaders: true,
    restrictedHeaders: ['X-Amz-Security-Token', 'Authorization'], // Restricted header values do not appear in report generated.
    includeRequestBody: true,
    includeResponseBody: true
};
```

This final example passes your request to **executeHttpStep** and names the step.

```
await synthetics.executeHttpStep('Verify GET products API', requestOptions, callback, stepConfig);
```

With this set of examples, CloudWatch Synthetics adds the details from each step in your report and produces metrics for each step using **stepName**.

 You will see `successPercent` and `duration` metrics for the `Verify GET products API` step. You can monitor your API performance by monitoring the metrics for your API call steps. 

For a sample complete script that uses these functions, see [Multi-step API canary](CloudWatch_Synthetics_Canaries_Samples.md#CloudWatch_Synthetics_Canaries_Samples_APIsteps).

# Library functions available for Python canary scripts using Selenium
<a name="CloudWatch_Synthetics_Canaries_Library_Python"></a>

This section lists the Selenium library functions available for Python canary scripts.

**Topics**
+ [Python and Selenium library classes and functions that apply to all canaries](#CloudWatch_Synthetics_Library_allcanaries_Python)
+ [Python and Selenium library classes and functions that apply to UI canaries only](#CloudWatch_Synthetics_Library_Python_UIcanaries)

## Python and Selenium library classes and functions that apply to all canaries
<a name="CloudWatch_Synthetics_Library_allcanaries_Python"></a>

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

**Topics**
+ [SyntheticsConfiguration class](#CloudWatch_Synthetics_Library_SyntheticsConfiguration_Python)
+ [SyntheticsLogger class](#CloudWatch_Synthetics_Library_SyntheticsLogger_Python)

### SyntheticsConfiguration class
<a name="CloudWatch_Synthetics_Library_SyntheticsConfiguration_Python"></a>

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.

Function definitions:

#### set\$1config(options)
<a name="CloudWatch_Synthetics_Library_setConfig_Python"></a>

```
from aws_synthetics.common import synthetics_configuration
```

` options ` is an object, which is a set of configurable options for your canary. The following sections explain the possible fields in ` options `.
+ `screenshot_on_step_start` (boolean)— Whether to take a screenshot before starting a step.
+ `screenshot_on_step_success` (boolean)— Whether to take a screenshot after completing a successful step.
+ `screenshot_on_step_failure` (boolean)— Whether to take a screenshot after a step fails.

 **with\$1screenshot\$1on\$1step\$1start(screenshot\$1on\$1step\$1start)** 

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

 **with\$1screenshot\$1on\$1step\$1success(screenshot\$1on\$1step\$1success)** 

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

 **with\$1screenshot\$1on\$1step\$1failure(screenshot\$1on\$1step\$1failure)** 

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

 **get\$1screenshot\$1on\$1step\$1start()** 

Returns whether to take a screenshot before starting a step.

 **get\$1screenshot\$1on\$1step\$1success()** 

Returns whether to take a screenshot after completing a step successfully.

 **get\$1screenshot\$1on\$1step\$1failure()** 

Returns whether to take a screenshot after a step fails.

 **disable\$1step\$1screenshots()** 

Disables all screenshot options (get\$1screenshot\$1on\$1step\$1start, get\$1screenshot\$1on\$1step\$1success, and get\$1screenshot\$1on\$1step\$1failure).

 **enable\$1step\$1screenshots()** 

Enables all screenshot options (get\$1screenshot\$1on\$1step\$1start, get\$1screenshot\$1on\$1step\$1success, and get\$1screenshot\$1on\$1step\$1failure). By default, all these methods are enabled.

 **setConfig(options) regarding CloudWatch metrics** 

For canaries using `syn-python-selenium-1.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](CloudWatch_Synthetics_Canaries_metrics.md).
+ `failed_canary_metric` (boolean)— Whether to emit the ` Failed` metric (with the `CanaryName` dimension) for this canary. The default is `true`.
+ `failed_requests_metric` (boolean)— Whether to emit the `Failed requests` metric (with the `CanaryName` dimension) for this canary. The default is `true`.
+ `2xx_metric` (boolean)— Whether to emit the `2xx` metric (with the `CanaryName` dimension) for this canary. The default is `true`.
+ `4xx_metric` (boolean)— Whether to emit the `4xx` metric (with the `CanaryName` dimension) for this canary. The default is `true`.
+ `5xx_metric` (boolean)— Whether to emit the `5xx` metric (with the `CanaryName` dimension) for this canary. The default is `true`.
+ `step_duration_metric` (boolean)— Whether to emit the `Step duration` metric (with the `CanaryName` `StepName` dimensions) for this canary. The default is `true`.
+ `step_success_metric` (boolean)— Whether to emit the `Step success` metric (with the `CanaryName` `StepName` dimensions) for this canary. The default is `true`.
+ `aggregated_failed_canary_metric` (boolean)— Whether to emit the `Failed` metric (without the `CanaryName` dimension) for this canary. The default is `true`.
+ `aggregated_failed_requests_metric` (boolean)— Whether to emit the `Failed Requests` metric (without the `CanaryName` dimension) for this canary. The default is `true`.
+ `aggregated_2xx_metric` (boolean)— Whether to emit the ` 2xx` metric (without the `CanaryName` dimension) for this canary. The default is `true`.
+ `aggregated_4xx_metric` (boolean)— Whether to emit the ` 4xx` metric (without the `CanaryName` dimension) for this canary. The default is `true`.
+ `aggregated_5xx_metric` (boolean)— Whether to emit the ` 5xx` metric (without the `CanaryName` dimension) for this canary. The default is `true`.

 **with\$12xx\$1metric(2xx\$1metric)** 

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

 **with\$14xx\$1metric(4xx\$1metric)** 

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

 **with\$15xx\$1metric(5xx\$1metric)** 

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.

 **with\$1aggregated\$15xx\$1metric(aggregated\$15xx\$1metric)** 

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

 ** with\$1aggregated\$1failed\$1canary\$1metric(aggregated\$1failed\$1canary\$1metric)** 

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

 ** with\$1aggregated\$1failed\$1requests\$1metric(aggregated\$1failed\$1requests\$1metric)** 

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

 **with\$1failed\$1canary\$1metric(failed\$1canary\$1metric)** 

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

 **with\$1failed\$1requests\$1metric(failed\$1requests\$1metric)** 

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

 **with\$1step\$1duration\$1metric(step\$1duration\$1metric)** 

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

 **with\$1step\$1success\$1metric(step\$1success\$1metric)** 

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

##### Methods to enable or disable metrics
<a name="CloudWatch_Synthetics_Python_setConfig_metrics"></a>

 **disable\$1aggregated\$1request\$1metrics()** 

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

 **disable\$1request\$1metrics()** 

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

 **disable\$1step\$1metrics()** 

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

 **enable\$1aggregated\$1request\$1metrics()** 

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

 **enable\$1request\$1metrics()** 

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

 **enable\$1step\$1metrics()** 

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

 **Usage in UI canaries** 

First, import the synthetics dependency and fetch the configuration. Then, set the configuration for each option by calling the setConfig method using one of the following options.

```
from aws_synthetics.common import synthetics_configuration

synthetics_configuration.set_config(
     {
        "screenshot_on_step_start": False,
        "screenshot_on_step_success": False,
        "screenshot_on_step_failure": True
     }
)

or
```

Or

```
synthetics_configuration.with_screenshot_on_step_start(False).with_screenshot_on_step_success(False).with_screenshot_on_step_failure(True)
```

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

```
synthetics_configuration.disable_step_screenshots()
```

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.

##### set\$1config(options) for UI canaries
<a name="CloudWatch_Synthetics_Library_Python_UI"></a>

Starting with `syn-python-selenium-1.1`, for UI canaries, ` set_config` can include the following Boolean parameters:
+ `continue_on_step_failure` (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`.

### SyntheticsLogger class
<a name="CloudWatch_Synthetics_Library_SyntheticsLogger_Python"></a>

`synthetics_logger` 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.

Using `synthetics_logger` is not required to create a log file that is uploaded to your Amazon 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 the S3 bucket as artifacts.

To use `synthetics_logger`:

```
from aws_synthetics.common import synthetics_logger
```

****Useful function definitions:

Get log level:

```
log_level = synthetics_logger.get_level()
```

Set log level:

```
synthetics_logger.set_level()
```

Log a message with a specified level. The level can be `DEBUG`, ` INFO`, `WARN`, or `ERROR`, as in the following syntax examples:

```
synthetics_logger.debug(message, *args, **kwargs)
```

```
synthetics_logger.info(message, *args, **kwargs)
```

```
synthetics_logger.log(message, *args, **kwargs)
```

```
synthetics_logger.warning(message, *args, **kwargs)
```

```
synthetics_logger.error(message, *args, **kwargs)
```

For information about debug parameters, see the standard Python documentation at [logging.debug](https://docs.python.org/3/library/logging.html#logging.debug)

In these logging functions, the `message` is the message format string. The `args` are the arguments that are merged into `msg` using the string formatting operator.

There are three keyword arguments in `kwargs`:
+ `exc_info`– If not evaluated as false, adds exception information to the logging message.
+ `stack_info`– defaults to false. If true, adds stack information to the logging message, including the actual logging call.
+ `extra`– The third optional keyword argument, which you can use to pass in a dictionary that is used to populate the `__dict__` of the `LogRecord` created for the logging event with user-defined attributes.

Examples:

Log a message with the level `DEBUG`:

```
synthetics_logger.debug('Starting step - login.')
```

Log a message with the level `INFO`. `logger.log` is a synonym for `logger.info`:

```
synthetics_logger.info('Successfully completed step - login.')
```

or

```
synthetics_logger.log('Successfully completed step - login.')
```

Log a message with the level `WARN`:

```
synthetics_logger.warning('Warning encountered trying to publish %s', 'CloudWatch Metric')
```

Log a message with the level `ERROR`:

```
synthetics_logger.error('Error encountered trying to publish %s', 'CloudWatch Metric')
```

Log an exception:

```
synthetics_logger.exception(message, *args, **kwargs)
```

Logs a message with level `ERROR`. Exception information is added to the logging message. You should call this function only from an exception handler.

For information about exception parameters, see the standard Python documentation at [ logging.exception](https://docs.python.org/3/library/logging.html#logging.exception)

The `message` is the message format string. The `args` are the arguments, which are merged into `msg` using the string formatting operator.

There are three keyword arguments in `kwargs`:
+ `exc_info`– If not evaluated as false, adds exception information to the logging message.
+ `stack_info`– defaults to false. If true, adds stack information to the logging message, including the actual logging call.
+ `extra`– The third optional keyword argument, which you can use to pass in a dictionary that is used to populate the `__dict__` of the `LogRecord` created for the logging event with user-defined attributes.

Example:

```
synthetics_logger.exception('Error encountered trying to publish %s', 'CloudWatch Metric')
```

## Python and Selenium library classes and functions that apply to UI canaries only
<a name="CloudWatch_Synthetics_Library_Python_UIcanaries"></a>

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

**Topics**
+ [SyntheticsBrowser class](#CloudWatch_Synthetics_Library_Python_SyntheticsBrowser)
+ [SyntheticsWebDriver class](#CloudWatch_Synthetics_Library_Python_SyntheticsWebDriver)

### SyntheticsBrowser class
<a name="CloudWatch_Synthetics_Library_Python_SyntheticsBrowser"></a>

**Note**  
`SyntheticsBrowser` is supported only on the Chrome browser.

When you create a browser instance by calling `synthetics_webdriver.Chrome()`, the returned browser instance is of the type `SyntheticsBrowser`. The ` SyntheticsBrowser` class inherits the WebDriver class and provides access to all the methods exposed by the [WebDriver](https://www.selenium.dev/documentation/webdriver/). It controls the ChromeDriver, and enables the canary script to drive the browser, allowing the Selenium WebDriver to work with Synthetics.

**Note**  
Synthetics overrides the WebDriver [ quit](https://www.selenium.dev/selenium/docs/api/py/selenium_webdriver_firefox/selenium.webdriver.firefox.webdriver.html) method to take no action. You don't need to worry about quitting the browser, as Synthetics handles that for you.

In addition to the standard Selenium methods, it also provides the following methods. 

**Topics**
+ [set\$1viewport\$1size(width, height)](#CloudWatch_Synthetics_Library_set_viewport_size)
+ [save\$1screenshot(filename, suffix)](#CloudWatch_Synthetics_Library_save_screenshot)

#### set\$1viewport\$1size(width, height)
<a name="CloudWatch_Synthetics_Library_set_viewport_size"></a>

Sets the viewport of the browser. Example:

```
browser.set_viewport_size(1920, 1080)
```

#### save\$1screenshot(filename, suffix)
<a name="CloudWatch_Synthetics_Library_save_screenshot"></a>

Saves screenshots to the `/tmp` directory. The screenshots are uploaded from there to the canary artifacts folder in the S3 bucket.

*filename* is the file name for the screenshot, and * suffix* is an optional string to be used for naming the screenshot.

Example:

```
browser.save_screenshot('loaded.png', 'page1')
```

### SyntheticsWebDriver class
<a name="CloudWatch_Synthetics_Library_Python_SyntheticsWebDriver"></a>

To use this class, use the following in your script:

```
from aws_synthetics.selenium import synthetics_webdriver
```

**Topics**
+ [add\$1execution\$1error(errorMessage, ex);](#CloudWatch_Synthetics_Library_Python_addExecutionError)
+ [add\$1user\$1agent(user\$1agent\$1str)](#CloudWatch_Synthetics_Library_add_user_agent)
+ [execute\$1step(step\$1name, function\$1to\$1execute)](#CloudWatch_Synthetics_Library_Python_execute_step)
+ [get\$1http\$1response(url)](#CloudWatch_Synthetics_Library_Python_get_http_response)
+ [Chrome()](#CloudWatch_Synthetics_Library_Python_Chrome)

#### add\$1execution\$1error(errorMessage, ex);
<a name="CloudWatch_Synthetics_Library_Python_addExecutionError"></a>

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

You can use `add_execution_error` 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 `add_execution_error` 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:
    browser.save_screenshot("loaded.png")  
except Exception as ex:
   self.add_execution_error("Unable to take screenshot", ex)
```

#### add\$1user\$1agent(user\$1agent\$1str)
<a name="CloudWatch_Synthetics_Library_add_user_agent"></a>

Appends the value of `user_agent_str` to the browser's user agent header. You must assign `user_agent_str` before creating the browser instance.

Example:

```
await synthetics_webdriver.add_user_agent('MyApp-1.0')
```

`add_user_agent` should be used inside an `async` function.

#### execute\$1step(step\$1name, function\$1to\$1execute)
<a name="CloudWatch_Synthetics_Library_Python_execute_step"></a>

Processes one function. 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.
+ Ends 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:

```
from selenium.webdriver.common.by import By

def custom_actions():
        #verify contains
        browser.find_element(By.XPATH, "//*[@id=\"id_1\"][contains(text(),'login')]")
        #click a button
        browser.find_element(By.XPATH, '//*[@id="submit"]/a').click()

    await synthetics_webdriver.execute_step("verify_click", custom_actions)
```

#### get\$1http\$1response(url)
<a name="CloudWatch_Synthetics_Library_Python_get_http_response"></a>

Makes an HTTP request to the provided URL and returns the response code of the HTTP request. If an exception occurred during the HTTP request, a string with value "error" is returned instead.

Example:

```
response_code = syn_webdriver.get_http_response(url)
if not response_code or response_code == "error" or response_code < 200 or response_code > 299:
    raise Exception("Failed to load page!")
```

#### Chrome()
<a name="CloudWatch_Synthetics_Library_Python_Chrome"></a>

Launches an instance of the Chromium browser and returns the created instance of the browser.

Example:

```
browser = synthetics_webdriver.Chrome()
browser.get("https://example.com/)
```

To launch a browser in incognito mode, use the following:

```
add_argument('——incognito')
```

To add proxy settings, use the following:

```
add_argument('--proxy-server=%s' % PROXY)
```

Example:

```
from selenium.webdriver.chrome.options import Options
chrome_options = Options()
chrome_options.add_argument("——incognito")
browser = syn_webdriver.Chrome(chrome_options=chrome_options)
```