可用于 Node.js Canary 脚本的库函数 - Amazon CloudWatch
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

可用于 Node.js Canary 脚本的库函数

本节列出了可用于 Node.js Canary 脚本的库函数。

适用于所有 Canary 的 Node.js 库类和函数

以下用于 Node.js 的 CloudWatch Synthetics 库函数适用于所有 Canary。

Synthetics 类

以下适用于所有 Canary 的函数都属于 Synthetics 类。

addExecutionError(errorMessage, ex);

errorMessage 描述错误,ex 指遇到的异常

您可以使用 addExecutionError 来设置 Canary 的执行错误。它会在不中断脚本执行的情况下导致 Canary 失败。它也不会影响 successPercent 指标。

只有当错误对于指示 Canary 脚本成功或故障并不重要时,才应将错误作为执行错误进行跟踪。

以下是使用 addExecutionError 的示例。您将会监控端点的可用性,并在页面加载完成后捕获屏幕截图。由于捕获屏幕截图故障并不会决定端点的可用性,因此您可以捕获在截图时遇到的任何错误,并将它们添加为执行错误。可用性指标仍会指示端点已启动并正在运行,但 Canary 状态会被标记为失败。以下示例代码块将会捕获此类错误并将其添加为执行错误。

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

getCanaryName();

返回 Canary 的名称。

getRuntimeVersion();

此函数在 syn-nodejs-puppeteer-3.0 和更高版本的运行时中可用。其返回 Canary 的 Synthetics 运行时版本。例如,返回值可能为 syn-nodejs-puppeteer-3.0

getLogLevel();

检索 Synthetics 库的当前日志级别。可能的值包括:

  • 0 – 调试

  • 1 – 信息

  • 2 – 警告

  • 3 – 错误

例如:

let logLevel = synthetics.getLogLevel();

setLogLevel();

设置 Synthetics 库的日志级别。可能的值包括:

  • 0 – 调试

  • 1 – 信息

  • 2 – 警告

  • 3 – 错误

例如:

synthetics.setLogLevel(0);

SyntheticsConfiguration 类

此类仅在 syn-nodejs-2.1 或更高版本的运行时中可用。

您可以使用 SyntheticsConfiguration 类来配置 Synthetics 库函数的行为。例如,您可以使用此类将 executeStep() 函数配置为不捕获屏幕截图。

您可以在全局级别设置 CloudWatch Synthetics 配置,这些配置会应用于 Canary 的所有步骤。您还可以通过传递配置键/值对,在步骤级别覆盖这些配置。

您可以在步骤级别传入选项。有关示例,请参阅 async executeStep(stepName, functionToExecute, [stepConfig]);executeHttpStep(stepName, requestOptions, [callback], [stepConfig])

函数定义:

setConfig(options)

options 是一个对象,它是一组适用于您的 Canary 的可配置选项。以下各节将介绍 options 中的可能字段。

所有 Canary 的 setConfig(options)

对于使用 syn-nodejs-puppeteer-3.2 或更高版本的 Canary,setConfig(options) 可包含以下参数:

  • includeRequestHeaders(布尔值)– 是否在报告中包含请求标头。默认 为 false

  • includeResponseHeaders(布尔值)– 是否在报告中包含响应标头。默认 为 false

  • restrictedHeaders(数组)– 要忽略的标头值列表(如果包含标头)。这对请求标头和响应标头均适用。例如,您可以将 includeRequestHeaders 传递为 true 并将 restrictedHeaders 传递为 ['Authorization'],来隐藏您的凭证。

  • includeRequestBody(布尔值)– 是否在报告中包含请求体。默认 为 false

  • includeResponseBody(布尔值)– 是否在报告中包含响应体。默认 为 false

CloudWatch 指标的相关 setConfig(options

对于使用 syn-nodejs-puppeteer-3.1 或更高版本的 Canary,setConfig(options) 可包含以下布尔参数,这些参数决定将由 Canary 发布的指标。其中每个选项的默认值均为 true。以 aggregated 开头的选项决定是否不带 CanaryName 维度发出指标。您可以使用该等指标查看所有 Canary 的聚合结果。其他选项决定是否带 CanaryName 维度发出指标。您可以使用该等指标查看每个 Canary 的结果。

有关 Canary 发出的 CloudWatch 指标的列表,请参阅 Canary 发布的 CloudWatch 指标

  • failedCanaryMetric(布尔值)– 是否发出此 Canary 的 Failed 指标(带 CanaryName 维度)。默认 为 true

  • failedRequestsMetric(布尔值)– 是否发出此 Canary 的 Failed requests 指标(带 CanaryName 维度)。默认 为 true

  • _2xxMetric(布尔值)– 是否发出此 Canary 的 2xx 指标(带 CanaryName 维度)。默认 为 true

  • _4xxMetric(布尔值)– 是否发出此 Canary 的 4xx 指标(带 CanaryName 维度)。默认 为 true

  • _5xxMetric(布尔值)– 是否发出此 Canary 的 5xx 指标(带 CanaryName 维度)。默认 为 true

  • stepDurationMetric(布尔值)– 是否发出此 Canary 的 Step duration 指标(带 CanaryName StepName 维度)。默认 为 true

  • stepSuccessMetric(布尔值)– 是否发出此 Canary 的 Step success 指标(带 CanaryName StepName 维度)。默认 为 true

  • aggregatedFailedCanaryMetric(布尔值)– 是否发出此 Canary 的 Failed 指标(不带 CanaryName 维度)。默认 为 true

  • aggregatedFailedRequestsMetric(布尔值)– 是否发出此 Canary 的 Failed Requests 指标(不带 CanaryName 维度)。默认 为 true

  • aggregated2xxMetric(布尔值)– 是否发出此 Canary 的 2xx 指标(不带 CanaryName 维度)。默认 为 true

  • aggregated4xxMetric(布尔值)– 是否发出此 Canary 的 4xx 指标(不带 CanaryName 维度)。默认 为 true

  • aggregated5xxMetric(布尔值)– 是否发出此 Canary 的 5xx 指标(不带 CanaryName 维度)。默认 为 true

  • visualMonitoringSuccessPercentMetric(布尔值)– 是否发出此 Canary 的 visualMonitoringSuccessPercent 指标。默认 为 true

  • visualMonitoringTotalComparisonsMetric(布尔值)– 是否发出此 Canary 的 visualMonitoringTotalComparisons 指标。默认 为 false

  • stepsReport(布尔值)– 是否报告步骤执行摘要。默认 为 true

  • includeUrlPassword(布尔值)– 是否包含 URL 中显示的密码。预设情况下,URL 中显示的密码会在日志和报告中进行编辑,以防泄露敏感数据。默认 为 false

  • restrictedUrlParameters(数组)– 要编辑的 URL 路径或查询参数的列表。这适用于出现在日志、报告和错误中的 URL。此参数区分大小写。您可以传递星号 (*) 作为值来编辑所有 URL 路径和查询参数值。默认值为空数组。

  • logRequest(布尔值)– 是否将每个请求都记录在 Canary 日志中。对于 UI Canary,这会记录浏览器发送的每个请求。默认 为 true

  • logResponse(布尔值)– 是否将每个响应都记录在 Canary 日志中。对于 UI Canary,这会记录浏览器收到的每个响应。默认 为 true

  • logRequestBody(布尔值)– 是否随请求一起将请求体记录在 Canary 日志中。仅当 logRequesttrue 时,此配置才适用。默认 为 false

  • logResponseBody(布尔值)– 是否随响应一起将响应体记录在 Canary 日志中。仅当 logResponsetrue 时,此配置才适用。默认 为 false

  • logRequestHeaders(布尔值)– 是否随请求一起将请求标头记录在 Canary 日志中。仅当 logRequesttrue 时,此配置才适用。默认 为 false

    请注意,includeRequestHeaders 会在构件中启用标头。

  • logResponseHeaders(布尔值)– 是否随响应一起将响应标头记录在 Canary 日志中。仅当 logResponsetrue 时,此配置才适用。默认 为 false

    请注意,includeResponseHeaders 会在构件中启用标头。

注意

始终会发出每个 Canary 的 DurationSuccessPercent 指标,这两个指标都会带有和不带 CanaryName 指标。

用于启用或禁用指标的方法

disableAggregatedRequestMetrics()

禁用 Canary 发出以不带 CanaryName 维度形式发出的所有请求指标。

disableRequestMetrics()

禁用所有请求指标,包括每个 Canary 的指标和跨所有 Canary 聚合的指标。

disableStepMetrics()

禁用所有步骤指标,包括步骤成功指标和步骤持续时间指标。

enableAggregatedRequestMetrics()

启用 Canary 发出以不带 CanaryName 维度形式发出的所有请求指标。

enableRequestMetrics()

启用所有请求指标,包括每个 Canary 的指标和跨所有 Canary 聚合的指标。

enableStepMetrics()

启用所有步骤指标,包括步骤成功指标和步骤持续时间指标。

get2xxMetric()

返回 Canary 是否发出带 CanaryName 维度的 2xx 指标。

get4xxMetric()

返回 Canary 是否发出带 CanaryName 维度的 4xx 指标。

get5xxMetric()

返回 Canary 是否发出带 CanaryName 维度的 5xx 指标。

getAggregated2xxMetric()

返回 Canary 是否发出不带维度的 2xx 指标。

getAggregated4xxMetric()

返回 Canary 是否发出不带维度的 4xx 指标。

getAggregatedFailedCanaryMetric()

返回 Canary 是否发出不带维度的 Failed 指标。

getAggregatedFailedRequestsMetric()

返回 Canary 是否发出不带维度的 Failed requests 指标。

getAggregated5xxMetric()

返回 Canary 是否发出不带维度的 5xx 指标。

getFailedCanaryMetric()

返回 Canary 是否发出带 CanaryName 维度的 Failed 指标。

getFailedRequestsMetric()

返回 Canary 是否发出带 CanaryName 维度的 Failed requests 指标。

getStepDurationMetric()

返回 Canary 是否发出带有此 Canary 的 CanaryName 维度的 Duration 指标。

getStepSuccessMetric()

返回 Canary 是否发出带有此 Canary 的 CanaryName 维度的 StepSuccess 指标。

with2xxMetric(_2xxMetric)

接受一个布尔参数,该参数指定是否为此 Canary 发出带 CanaryName 维度的 2xx 指标。

with4xxMetric(_4xxMetric)

接受一个布尔参数,该参数指定是否为此 Canary 发出带 CanaryName 维度的 4xx 指标。

with5xxMetric(_5xxMetric)

接受一个布尔参数,该参数指定是否为此 Canary 发出带 CanaryName 维度的 5xx 指标。

withAggregated2xxMetric(aggregated2xxMetric)

接受一个布尔参数,该参数指定是否为此 Canary 发出不带维度的 2xx 指标。

withAggregated4xxMetric(aggregated4xxMetric)

接受一个布尔参数,该参数指定是否为此 Canary 发出不带维度的 4xx 指标。

withAggregated5xxMetric(aggregated5xxMetric)

接受一个布尔参数,该参数指定是否为此 Canary 发出不带维度的 5xx 指标。

withAggregatedFailedCanaryMetric(aggregatedFailedCanaryMetric)

接受一个布尔参数,该参数指定是否为此 Canary 发出不带维度的 Failed 指标。

withAggregatedFailedRequestsMetric(aggregatedFailedRequestsMetric)

接受一个布尔参数,该参数指定是否为此 Canary 发出不带维度的 Failed requests 指标。

withFailedCanaryMetric(failedCanaryMetric)

接受一个布尔参数,该参数指定是否为此 Canary 发出带 CanaryName 维度的 Failed 指标。

withFailedRequestsMetric(failedRequestsMetric)

接受一个布尔参数,该参数指定是否为此 Canary 发出带 CanaryName 维度的 Failed requests 指标。

withStepDurationMetric(stepDurationMetric)

接受一个布尔参数,该参数指定是否为此 Canary 发出带 CanaryName 维度的 Duration 指标。

withStepSuccessMetric(stepSuccessMetric)

接受一个布尔参数,该参数指定是否为此 Canary 发出带 CanaryName 维度的 StepSuccess 指标。

启用或禁用其他功能的方法

withHarFile()

接受一个布尔参数,该参数指定是否为此 Canary 创建 HAR 文件。

withStepsReport()

接受一个布尔参数,该参数指定是否报告此 Canary 的步骤执行摘要。

withIncludeUrlPassword()

接受一个布尔参数,该参数指定是否在日志和报告中包含 URL 中出现的密码。

withRestrictedUrlParameters()

接受要编辑的 URL 路径或查询参数的数组。这适用于出现在日志、报告和错误中的 URL。您可以传递星号 (*) 作为值来编辑所有 URL 路径和查询参数值

withLogRequest()

接受一个布尔参数,该参数指定是否将每个请求记录在 Canary 的日志中。

withLogResponse()

接受一个布尔参数,该参数指定是否将每个响应记录在 Canary 的日志中。

withLogRequestBody()

接受一个布尔参数,该参数指定是否将每个请求体记录在 Canary 的日志中。

withLogResponseBody()

接受一个布尔参数,该参数指定是否将每个响应体记录在 Canary 的日志中。

withLogRequestHeaders()

接受一个布尔参数,该参数指定是否将每个请求标头记录在 Canary 的日志中。

withLogResponseHeaders()

接受一个布尔参数,该参数指定是否将每个响应标头记录在 Canary 日志中。

getHarFile()

返回 Canary 是否创建 HAR 文件。

getStepsReport()

返回 Canary 是否报告步骤执行摘要。

getIncludeUrlPassword()

返回 Canary 是否在日志和报告中包含 URL 中出现的密码。

getRestrictedUrlParameters()

返回 Canary 是否编辑 URL 路径或查询参数。

getLogRequest()

返回 Canary 是否将每个请求记录在 Canary 的日志中。

getLogResponse()

返回 Canary 是否将每个响应记录在 Canary 的日志中。

getLogRequestBody()

返回 Canary 是否将每个请求体记录在 Canary 的日志中。

getLogResponseBody()

返回 Canary 是否将每个响应体记录在 Canary 的日志中。

getLogRequestHeaders()

返回 Canary 是否将每个请求标头记录在 Canary 的日志中。

getLogResponseHeaders()

返回 Canary 是否将每个响应标头记录在 Canary 的日志中。

所有 Canary 的函数

  • withIncludeRequestHeaders(includeRequestHeaders)

  • withIncludeResponseHeaders(包括响应标题)

  • withRestrictedHeaders(restrictedHeaders)

  • withIncludeRequestBody(includeRequestBody)

  • withIncludeResponseBody(includeResponseBody)

  • enableReportingOptions() – 启用所有报告选项-- includeRequestHeadersincludeResponseHeadersincludeRequestBodyincludeResponseBody

  • disableReportingOptions() – 禁用所有报告选项-- includeRequestHeadersincludeResponseHeadersincludeRequestBodyincludeResponseBody

用于 UI Canary 的 setConfig(options)

对于 UI Canary,setConfig 可包含以下布尔参数:

  • continueOnStepFailure(布尔值)– 是否在步骤失败(指 executeStep 函数)后继续运行 Canary 脚本。如果任何步骤失败,Canary 运行仍将被标记为失败。默认 为 false

  • harFile(布尔值)– 是否创建 HAR 文件。默认 为 True

  • screenshotOnStepStart(布尔值)– 是否在开始步骤之前捕获屏幕截图。

  • screenshotOnStepSuccess(布尔值)– 是否在成功完成步骤后捕获屏幕截图。

  • screenshotOnStepFailure(布尔值)– 是否在步骤失败后捕获屏幕截图。

启用或禁用屏幕截图的方法

disableStepScreenshots()

禁用所有屏幕截图选项(screenshotOnStepStart、screenshotOnStepSuccess 和 screenshotOnStepFailure)。

enableStepScreenshots()

启用所有屏幕截图选项(screenshotOnStepStart、screenshotOnStepSuccess 和 screenshotOnStepFailure)。预设情况下,这些方法均未启用。

getScreenshotOnStepFailure()

返回 Canary 是否在步骤失败后捕获屏幕截图。

getScreenshotOnStepStart()

返回 Canary 是否在开始步骤之前捕获屏幕截图。

getScreenshotOnStepSuccess()

返回 Canary 是否在成功完成步骤后捕获屏幕截图。

withScreenshotOnStepStart(screenshotOnStepStart)

接受一个布尔参数,该参数指示是否在开始步骤之前捕获屏幕截图。

withScreenshotOnStepSuccess(screenshotOnStepSuccess)

接受一个布尔参数,该参数指示是否在成功完成步骤后捕获屏幕截图。

withScreenshotOnStepFailure(screenshotOnStepFailure)

接受一个布尔参数,该参数指示是否在步骤失败后捕获屏幕截图。

在 UI Canary 中的使用情况

首先,导入 Synthetics 依赖关系并获取配置。

// Import Synthetics dependency const synthetics = require('Synthetics'); // Get Synthetics configuration const synConfig = synthetics.getConfiguration();

然后,通过使用以下选项之一调用 setConfig 方法来设置每个选项的配置。

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

或者

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

若要禁用所有屏幕截图,请使用 disableStepScreenshots() 函数,如本示例所示。

synConfig.disableStepScreenshots();

您可以在代码中的任何位置启用和禁用屏幕截图。例如,若要仅禁用一个步骤的屏幕截图,请在运行该步骤之前禁用屏幕截图,然后在该步骤后启用它们。

用于 API Canary 的 setConfig(options)

对于 API Canary,setConfig 可包含以下布尔参数:

  • continueOnHttpStepFailure(布尔值)- 是否在 HTTP 步骤(指 executeHttpStep 函数)失败后继续运行 Canary 脚本。如果任何步骤失败,Canary 运行仍将被标记为失败。默认 为 true

可视化监控

可视化监控将在 Canary 运行期间捕获的屏幕截图与在基准 Canary 运行期间捕获的屏幕截图进行比较。如果两个屏幕截图之间的差异超出阈值百分比,则 Canary 失败,您可以在 Canary 运行报告中看到以高亮颜色突出显示的差异区域。运行 syn-puppeteer-node-3.2 和更高版本的 Canary 支持可视化监控。运行 Python 和 Selenium 的 Canary 中目前不支持可视化监控。

若要启用可视化监控,请将以下代码行添加到 Canary 脚本中。有关更多信息,请参阅 SyntheticsConfiguration 类

syntheticsConfiguration.withVisualCompareWithBaseRun(true);

将此行添加到脚本后,Canary 首次成功运行时,它会使用在该运行期间捕获的屏幕截图作为比较基准。在 Canary 的该首次运行之后,您可以使用 CloudWatch 控制台编辑 Canary 以执行以下任一操作:

  • 将 Canary 的下一次运行设置为新基准。

  • 在当前基准屏幕截图上绘制边界,以指定在可视化比较过程中要忽略的屏幕截图区域。

  • 删除屏幕截图,使其不用于可视化监控。

有关使用 CloudWatch 控制台编辑 Canary 的更多信息,请参阅 编辑或删除 Canary

可视化监控的其他选项

syntheticsConfiguration.withVisualVarianceThresholdPercentage(desiredPercentage)

设置可视化对比中屏幕截图差异的可接受百分比。

syntheticsConfiguration.withVisualVarianceHighlightHexColor("#fafa00")

设置在查看使用可视化监控的 Canary 运行报告时指明差异区域的突出显示颜色。

syntheticsConfiguration.withFailCanaryRunOnVisualVariance(failCanary)

设置当存在超过阈值的可视化差异时 Canary 是否失败。默认为 Canary 失败。

Synthetics Logger

SyntheticsLogger 将日志写入控制台和同一日志级别的本地日志文件。仅当日志级别与所调用的日志函数所需的日志记录级别相同或比其级别低时,此日志文件才会写入到这两个位置。

本地日志文件中的日志记录语句前面加上“DEBUG:”、“INFO:”等,以便与所调用的函数的日志级别相匹配。

如果您希望在与 Synthetics Canary 日志记录相同的日志级别运行 Synthetics 库,可以使用 SyntheticsLogger。

如果要创建上载到 S3 结果位置的日志文件,不需要使用 SyntheticsLogger。您可以在 /tmp 文件夹中创建不同的日志文件。在 /tmp 文件夹下创建的任何文件都会作为构件上传到 S3 中的结果位置。

要使用 Synthetics 库日志记录程序,请执行以下操作:

const log = require('SyntheticsLogger');

有用的函数定义:

log.debug(message, ex);

参数:message 是要记录的消息。ex 是要记录的异常(如果有)。

例如:

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

log.error(message, ex);

参数:message 是要记录的消息。ex 是要记录的异常(如果有)。

例如:

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

log.info(message, ex);

参数:message 是要记录的消息。ex 是要记录的异常(如果有)。

例如:

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

log.log(message, ex);

这是 log.info 的一个别名。

参数:message 是要记录的消息。ex 是要记录的异常(如果有)。

例如:

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

log.warn(message, ex);

参数:message 是要记录的消息。ex 是要记录的异常(如果有)。

例如:

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

SyntheticsLogHelper 类

SyntheticsLogHelper 类在 syn-nodejs-puppeteer-3.2 和更高版本的运行时中可用。其已在 CloudWatch Synthetics 库中初始化,并配置了 Synthetics 配置。您可以将它作为依赖项添加到脚本中。此类使您能够清理 URL、标头和错误消息,以编辑敏感信息。

注意

根据 Synthetics 配置设置 restrictedUrlParameters,Synthetics 会对其记录的所有 URL 和错误消息进行清理,然后再将它们纳入日志、报告、HAR 文件和 Canary 运行错误中。仅当您在脚本中记录 URL 或错误时,才必须使用 getSanitizedUrlgetSanitizedErrorMessage。除了脚本引发的 Canary 错误之外,Synthetics 不会存储任何 Canary 构件。Canary 运行构件存储在您的客户账户中。有关更多信息,请参阅 Synthetics Canary 的安全注意事项

getSanitizedUrl(url, stepConfig = null)

此函数在 syn-nodejs-puppeteer-3.2 和更高版本中可用。它根据配置返回经过清理的 url 字符串。您可以通过设置 restrictedUrlParameters 属性选择编辑敏感 URL 参数(如密码和 access_token)。预设情况下,会编辑 URL 中的密码。如果需要,您可以通过将 includeUrlPassword 设置为 true 来启用 URL 密码。

如果传入的 URL 不是有效 URL,此函数会引发一个错误。

:参数

  • url 是一个字符串,也是要清理的 URL。

  • StepConfig(可选)覆盖此函数的全局 Synthetics 配置。如果 stepConfig 未传入,则使用全局配置清理 URL。

示例:

此示例使用以下示例 URL:https://example.com/learn/home?access_token=12345&token_type=Bearer&expires_in=1200。在此示例中,access_token 包含不应记录下来的敏感信息。请注意,Synthetics 服务不会存储任何 Canary 运行构件。日志、屏幕截图和报告等构件都存储在您客户账户的 Amazon S3 存储桶中。

第一步,设置 Synthetics 配置。

// Import Synthetics dependency const synthetics = require('Synthetics'); // Import Synthetics logger for logging url const log = require('SyntheticsLogger'); // Get Synthetics configuration const synConfig = synthetics.getConfiguration(); // Set restricted parameters synConfig.setConfig({ restrictedUrlParameters: ['access_token']; });

接下来,清理并记录 URL

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

这一步会将以下内容记录在您的 Canary 日志中。

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

您可以通过传入包含 Synthetics 配置选项的可选参数来覆盖 URL 的 Synthetics 配置,如以下示例所示。

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

上面的示例编辑了所有查询参数,并记录如下:

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

getSanitizedErrorMessage

此函数在 syn-nodejs-puppeteer-3.2 和更高版本中可用。它根据 Synthetics 配置对所存在的任何 URL 进行清理,返回已清理的错误字符串。您可以选择在调用此函数时通过传递一个可选的 stepConfig 参数来覆盖全局 Synthetics 配置。

:参数

  • error 是要清理的错误。它可以是 Error 对象或字符串。

  • StepConfig(可选)覆盖此函数的全局 Synthetics 配置。如果 stepConfig 未传入,则使用全局配置清理 URL。

示例:

此示例使用以下内容:Failed to load url: https://example.com/learn/home?access_token=12345&token_type=Bearer&expires_in=1200

第一步,设置 Synthetics 配置。

// Import Synthetics dependency const synthetics = require('Synthetics'); // Import Synthetics logger for logging url const log = require('SyntheticsLogger'); // Get Synthetics configuration const synConfig = synthetics.getConfiguration(); // Set restricted parameters synConfig.setConfig({ restrictedUrlParameters: ['access_token']; });

接下来,清理并记录错误消息

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

这一步会将以下内容记录在您的 Canary 日志中。

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

getSanitizedHeaders(headers, stepConfig=null)

此函数在 syn-nodejs-puppeteer-3.2 和更高版本中可用。它根据 syntheticsConfigurationrestrictedHeaders 属性返回经清理的标头。restrictedHeaders 属性中指定的标头是在日志、HAR 文件和报告中编辑的。

:参数

  • headers 是一个包含要清理的标题的对象。

  • StepConfig(可选)覆盖此函数的全局 Synthetics 配置。如果 stepConfig 未传入,则使用全局配置来清理标头。

仅适用于 UI Canary 的 Node.js 库类和函数

以下用于 Node.js 的 CloudWatch Synthetics 库函数仅适用于 UI Canary。

Synthetics 类

以下函数位于 Synthetics 类中。

async addUserAgent(page, userAgentString);

此函数可将 userAgentString 附加到指定页面的 User-Agent 标头。

例如:

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

结果是页面的 User-Agent 标头被设置为 browsers-user-agent-header-valueMyApp-1.0

async executeStep(stepName, functionToExecute, [stepConfig]);

执行提供的步骤,并使用开始/通过/失败日志记录、开始/通过/失败屏幕截图,以及通过/失败和持续时间指标对其进行包装。

注意

如果您使用的是 syn-nodejs-2.1 或更高版本的运行时,您可以配置是否以及何时捕获屏幕截图。有关更多信息,请参阅 SyntheticsConfiguration 类

executeStep 函数还执行以下操作:

  • 记录步骤开始。

  • 获取名为 <stepName>-starting 的屏幕截图。

  • 启动计时器。

  • 执行提供的函数。

  • 如果函数正常返回,则计为通过。如果函数引发异常,则计为失败。

  • 结束计时器。

  • 记录步骤是通过还是失败

  • 获取名为 <stepName>-succeeded<stepName>-failed 的屏幕截图。

  • 发出 stepName SuccessPercent 指标,100 表示通过,0 表示失败。

  • 发出 stepName Duration 指标,指标的值基于步骤开始和结束时间。

  • 最后,返回 functionToExecute 返回的内容或重新抛出 functionToExecute 抛出的内容。

如果 Canary 使用 syn-nodejs-2.0 或更高版本的运行时,则此函数还将步骤执行摘要添加到 Canary 的报告中。摘要包括有关每个步骤的详细信息,例如开始时间、结束时间、状态 (PASSED/FAILED)、故障原因(如失败)以及在每个步骤执行过程中捕获的屏幕截图。

例如:

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

响应:

返回 functionToExecute 返回的内容。

syn-nodejs-2.2 的更新

syn-nodejs-2.2 开始,您可以选择传递步骤配置来在步骤级别覆盖 CloudWatch Synthetics 配置。有关可以传递给 executeStep 的选项列表,请参阅 SyntheticsConfiguration 类

在以下示例中,用 true 覆盖 continueOnStepFailure 的默认 false 配置,并指定捕获屏幕截图的时间。

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

getDefaultLaunchOptions() 函数返回 CloudWatch Synthetics 使用的浏览器启动选项。有关更多信息,请参阅 puppeteer.launch([options])

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

getPage();

返回当前打开的页面作为 Puppeteer 对象。有关更多信息,请参阅 Puppeteer API v1.14.0

例如:

let page = synthetics.getPage();

响应:

在当前浏览器会话中打开的页面(Puppeteer 对象)。

getRequestResponseLogHelper();

重要

在使用 syn-nodejs-puppeteer-3.2 或更高版本运行时的 Canary 中,此函数将与 RequestResponseLogHelper 类一起弃用。对此函数的任何使用都会导致在 Canary 日志中出现警告。将在未来的运行时版本中删除此函数。如果您正在使用此函数,请改为使用 RequestResponseLogHelper 类

将此函数用作生成器模式,用于调整请求和响应日志记录标记。

例如:

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

响应:

{RequestResponseLogHelper}

launch(options)

此函数的选项仅在 syn-nodejs-2.1 版本或更高版本的运行时中可用。

此函数仅用于 UI Canary。它的作用是关闭现有浏览器并启动一个新的浏览器。

注意

在开始运行脚本之前,CloudWatch Synthetics 始终启动浏览器。除非您想使用自定义选项启动新浏览器,否则不需要调用 launch()。

(options) 是在浏览器上设置的一组可配置的选项。有关更多信息,请参阅 puppeteer.launch([options])

如果您在不设置选项的情况下调用此函数,Synthetics 会以默认参数、executablePathdefaultViewport 启动浏览器。CloudWatch Synthetics 中的默认视区是 1920 x 1080。

您可以覆盖 CloudWatch Synthetics 使用的启动参数,并在启动浏览器时传递其他参数。例如,以下代码段以默认参数和默认可执行文件路径启动浏览器,但视区为 800 x 600。

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

以下示例代码向 CloudWatch Synthetics 启动参数中添加了一个新的 ignoreHTTPSErrors 参数。

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

您可以通过向 CloudWatch Synthetics 启动参数中的参数添加一个 --disable-web-security 标志来禁用 Web 安全:

// 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 类

重要

在使用 syn-nodejs-puppeteer-3.2 或更高版本运行时的 Canary 中,此类将被弃用。对此类的任何使用都会导致在 Canary 日志中出现警告。将在未来的运行时版本中删除此函数。如果您正在使用此函数,请改为使用 RequestResponseLogHelper 类。

处理精细配置,以及创建请求和响应负载的字符串表示。

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

例如:

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

响应:

{RequestResponseLogHelper}

setRequestResponseLogHelper();

重要

在使用 syn-nodejs-puppeteer-3.2 或更高版本运行时的 Canary 中,此函数将与 RequestResponseLogHelper 类一起弃用。对此函数的任何使用都会导致在 Canary 日志中出现警告。将在未来的运行时版本中删除此函数。如果您正在使用此函数,请改为使用 RequestResponseLogHelper 类

将此函数用作成生器模式,用于设置请求和响应日志记录标记。

例如:

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

响应:

{RequestResponseLogHelper}

async takeScreenshot(name, suffix);

捕获当前页面的屏幕截图 (.PNG) 并命名和添加后缀(可选)。

例如:

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

在此示例中,捕获了名为 01-navigateToUrl-loaded.png 的屏幕截图并将其上载到 Canary 的 S3 存储桶。

您可以传递 stepName 作为第一个参数,捕获特定 Canary 步骤的屏幕截图。屏幕截图会链接到报告中的 Canary 步骤,以帮助您在调试时跟踪每个步骤。

CloudWatch Synthetics Canary 会在开始步骤之前(executeStep 函数)和步骤完成后(除非您将 Canary 配置为禁用屏幕截图)自动捕获屏幕截图。您可以通过将步骤名称传入 takeScreenshot 函数来捕获多个屏幕截图。

在以下示例中,捕获屏幕截图并将 signupForm 作为 stepName 的值。屏幕截图将被命名为 02-signupForm-address,并链接到 Canary 报告中名为 signupForm 的步骤。

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

BrokenLinkCheckerReport 类

此类提供了添加 Synthetics 链接的方法。仅在使用 syn-nodejs-2.0-beta 或更高版本运行时的 Canary 上支持此类。

若要使用 BrokenLinkCheckerReport,脚本中需包括以下行:

const BrokenLinkCheckerReport = require('BrokenLinkCheckerReport'); const brokenLinkCheckerReport = new BrokenLinkCheckerReport();

有用的函数定义:

addLink(syntheticsLink, isBroken)

syntheticsLink 是一个 SyntheticsLink 对象,表示链接。此函数根据状态代码添加链接。预设情况下,如果状态代码不可用或状态代码为 400 或以上,则其会将链接视为无效。您可以通过传入可选参数 isBrokenLink(带有值 truefalse)来覆盖此默认行为。

此函数无返回值。

getLinks()

此函数返回一组 SyntheticsLink 对象,这些对象包含在无效链接检查器报告。

getTotalBrokenLinks()

此函数返回一个表示无效链接总数的数字。

getTotalLinksChecked()

此函数返回一个表示包含在报告中的链接总数的数字。

如何使用 BrokenLinkCheckerReport

以下 Canary 脚本代码段展示了导航到链接并将其添加到无效链接检查器报告的示例。

  1. 导入 SyntheticsLinkBrokenLinkCheckerReportSynthetics

    const BrokenLinkCheckerReport = require('BrokenLinkCheckerReport'); const SyntheticsLink = require('SyntheticsLink'); // Synthetics dependency const synthetics = require('Synthetics');
  2. 若要向报告添加链接,请创建 BrokenLinkCheckerReport 实例。

    let brokenLinkCheckerReport = new BrokenLinkCheckerReport();
  3. 导航到 URL 并将其添加到无效链接检查器报告中。

    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);
  4. 将报告添加到 Synthetics。这样,Canary 每次运行都会在 S3 存储桶中创建一个名为 BrokenLinkCheckerReport.json 的 JSON 文件。您可以在控制台中查看 Canary 每次运行的链接报告以及屏幕截图、日志和 HAR 文件。

    await synthetics.addReport(brokenLinkCheckerReport);

此类提供了包装信息的方法。仅在使用 syn-nodejs-2.0-beta 或更高版本运行时的 Canary 上支持此类。

若要使用 SyntheticsLink,脚本中需包括以下行:

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

此函数返回 syntheticsLinkObject

有用的函数定义:

withUrl(url)

url 是一个 URL 字符串。此函数返回 syntheticsLinkObject

withText(text)

text 是一个表示锚文本的字符串。此函数返回 syntheticsLinkObject。它会添加与链接相对应的锚文本。

withParentUrl(parentUrl)

parentUrl 是一个表示父(源页面)URL 的字符串。此函数返回 syntheticsLinkObject

withStatusCode(statusCode)

statusCode 是一个表示状态代码的字符串。此函数返回 syntheticsLinkObject

withFailureReason(failureReason)

failureReason 是一个表示故障原因的字符串。此函数返回 syntheticsLinkObject

addScreenshotResult(screenshotResult)

screenshotResult 是一个对象。它是 Synthetics 函数 takeScreenshot 返回的 ScreenshotResult 的实例。此对象包括以下属性:

  • fileName – 表示 的字符串screenshotFileName

  • pageUrl(可选)

  • error(可选)

仅适用于 API Canary 的 Node.js 库类和函数

以下用于 Node.js 的 CloudWatch Synthetics 库函数仅适用于 API Canary。

executeHttpStep(stepName, requestOptions, [callback], [stepConfig])

作为步骤执行提供的 HTTP 请求,并发布 SuccessPercent(通过/失败)和 Duration 指标。

executeHttpStep 在后台使用 HTTP 或 HTTPS 本机函数,具体取决于请求中指定的协议。

此函数还将步骤执行摘要添加到 Canary 的报告中。摘要中包括有关每个 HTTP 请求的详细信息,如下所示:

  • 开始时间

  • 结束时间

  • 状态 (PASSED/FAILED)

  • 故障原因(如失败)

  • HTTP 调用详细信息,如请求/响应标头、请求/响应体、状态代码、状态消息和性能计时。

参数

stepName(String)

指定步骤的名称。此名称也用于发布此步骤的 CloudWatch 指标。

requestOptions(Object or String)

此参数的值可以是 URL、URL 字符串或对象。如果为对象,则必须是用以发出 HTTP 请求的一组可配置选项。其支持 Node.js 文档中 http.request(options[, callback]) 中的所有选项。

除了这些 Node.js 选项之外,requestOptions 支持附加参数 body。您可以使用 body 参数将数据作为请求体传递。

callback(response)

(可选)此函数是与 HTTP 响应一起调用的用户函数。响应的类型为 Class: http.IncomingMessage

stepConfig(object)

(可选)使用此参数,可以用此步骤的不同配置覆盖全局 synthetics 配置。

executeHttpStep 的使用示例

以下一系列示例相互依存,以说明此选项的各种用途。

第一个示例展示配置请求参数。您可以将 URL 作为 requestOptions 传递:

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

或者,您也可以传递一组选项:

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

在下一个示例中,创建一个接受响应的回调函数。预设情况下,如果您未指定 callback,CloudWatch Synthetics 会验证状态是否介于 200 和 299 之间(含)。

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

下一个示例展示为此步骤创建覆盖全局 CloudWatch Synthetics 配置的配置。在本示例中,步骤配置允许报告中包含请求标头、响应标头、请求体(发布数据)和响应体,并限制了“X-Amz-Security-Token”和“Authorization”标头值。预设情况下,出于安全原因,报告中不包括这些值。如果您选择将它们包含在报告中,则这些数据仅存储在 S3 存储桶中。

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

最后一个例子展示将请求传递给 executeHttpStep 并对步骤命名。

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

在这组示例中,CloudWatch Synthetics 将每个步骤的详细信息添加在报告中,并使用 stepName 生成每个步骤的指标。

您将看到 Verify GET products API 步骤的 successPercentduration 指标。您可以通过监控 API 调用步骤的指标来监控 API 性能。

有关使用这些函数的完整脚本示例,请参阅 多步骤 API Canary