すべての Canary に適用される Node.js ライブラリクラスおよび関数 UI Canary のみに適用される Node.js ライブラリクラスおよび関数 API Canary のみに適用されるライブラリクラスおよび関数

Node.js Canary スクリプト用のライブラリ関数

このセクションでは、Node.js Canary スクリプトで使用できるライブラリ関数の一覧を示しています。

トピック

すべての Canary に適用される Node.js ライブラリクラスおよび関数
UI Canary のみに適用される Node.js ライブラリクラスおよび関数
API 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 の名前を返します。

getCanaryArn();

Canary の ARN を返します。

getCanaryUserAgentString();

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 の (オプション) に、次のパラメータを含めることができます。

includeRequestHeaders (ブール値) – レポートにリクエストヘッダーを含めるかどうか。デフォルト: false。
includeResponseHeaders (ブール値) – レポートにレスポンスヘッダーを含めるかどうか。デフォルト: false。
restrictedHeaders(配列) – ヘッダーが含まれている場合に無視するヘッダー値のリスト。これは、リクエストヘッダーとレスポンスヘッダーの両方に適用されます。例えば、includeRequestHeaders を true として、restrictedHeaders を ['Authorization'] として渡すことで、認証情報を非表示にすることができます。
includeRequestBody (ブール値) – レポートにリクエスト本文を含めるかどうか。デフォルト: false。
includeResponseBody (ブール値) – レポートにレスポンス本文を含めるかどうか。デフォルト: false。

CloudWatch メトリクスに関する setConfig (オプション)

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 ログのリクエストとともに記録するかどうか。この設定は、logRequest が true である場合にのみ適用されます。デフォルト: false。
logResponseBody（ブール値）-レスポンス本文を Canary ログのレスポンスとともに記録するかどうか。この設定は、logResponse が true である場合にのみ適用されます。デフォルト: false。
logRequestHeaders（ブール値）-リクエストヘッダーを Canary ログのリクエストとともに記録するかどうか。この設定は、logRequest が true である場合にのみ適用されます。デフォルト: false。

includeRequestHeaders は、アーティファクトのヘッダーを有効にすることに注意してください。
logResponseHeaders（ブール値）-レスポンスヘッダーを Canary ログのレスポンスとともに記録するかどうか。この設定は、logResponse が true である場合にのみ適用されます。デフォルト: false。

includeResponseHeaders は、アーティファクトのヘッダーを有効にすることに注意してください。

注記

Duration メトリクスと SuccessPercent メトリクスは、CanaryName メトリクスの有無にかかわらず、常に各 Canary について出力されます。

メトリクスを有効または無効にする方法

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 に対して 2xx ディメンションを持つ CanaryName メトリクスを出力するかどうかを指定します。

with4xxMetric(_4xxMetric)

ブール引数を受け入れます。この引数は、この Canary に対して 4xx ディメンションを持つ CanaryName メトリクスを出力するかどうかを指定します。

with5xxMetric(_5xxMetric)

ブール引数を受け入れます。この引数は、この Canary に対して 5xx ディメンションを持つ CanaryName メトリクスを出力するかどうかを指定します。

withAggregated2xxMetric(aggregated2xxMetric)

ブール引数を受け入れます。この引数は、この Canary に対してディメンションを持たない 2xx メトリクスを出力するかどうかを指定します。

withAggregated4xxMetric(aggregated4xxMetric)

ブール引数を受け入れます。この引数は、この Canary に対してディメンションを持たない 4xx メトリクスを出力するかどうかを指定します。

withAggregated5xxMetric(aggregated5xxMetric)

ブール引数を受け入れます。この引数は、この Canary に対してディメンションを持たない 5xx メトリクスを出力するかどうかを指定します。

withAggregatedFailedCanaryMetric(aggregatedFailedCanaryMetric)

ブール引数を受け入れます。この引数は、この Canary に対してディメンションを持たない Failed メトリクスを出力するかどうかを指定します。

withAggregatedFailedRequestsMetric(aggregatedFailedRequestsMetric)

ブール引数を受け入れます。この引数は、この Canary に対してディメンションを持たない Failed requests メトリクスを出力するかどうかを指定します。

withFailedCanaryMetric(failedCanaryMetric)

ブール引数を受け入れます。この引数は、この Canary に対して Failed ディメンションを持つ CanaryName メトリクスを出力するかどうかを指定します。

withFailedRequestsMetric(failedRequestsMetric)

ブール引数を受け入れます。この引数は、この Canary に対して Failed requests ディメンションを持つ CanaryName メトリクスを出力するかどうかを指定します。

withStepDurationMetric(stepDurationMetric)

ブール引数を受け入れます。この引数は、この Canary に対して Duration ディメンションを持つ CanaryName メトリクスを出力するかどうかを指定します。

withStepSuccessMetric(stepSuccessMetric)

ブール引数を受け入れます。この引数は、この Canary に対して StepSuccess ディメンションを持つ CanaryName メトリクスを出力するかどうかを指定します。

他の機能を有効または無効にする方法

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

ログおよびレポートの URL に表示されるパスワードを、Canary に含めるかどうかを返します。

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(includeResponseHeaders)
withRestrictedHeaders(restrictedHeaders)
withIncludeRequestBody(includeRequestBody)
withIncludeResponseBody(includeResponseBody)
enableReportingOptions() – すべてのレポートオプションを有効にします-- includeRequestHeaders、includeResponseHeaders、includeRequestBody、および includeResponseBody。
disableReportingOptions() – すべてのレポートオプションを無効にします-- includeRequestHeaders、includeResponseHeaders、includeRequestBody、および includeResponseBody。

UI Canary の setConfig(options)

UI Canary の場合、setConfig には次のブール値のパラメータを含めることができます。

continueOnStepFailure (ブール値) – ステップが失敗した後も Canary スクリプトの実行を続行するかどうか (これは executeStep 関数を参照します)。いずれかのステップが失敗しても、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();

コード内の任意の個所でスクリーンショットを有効または無効にすることができます。例えば、1 つのステップでのみスクリーンショットを無効にするには、そのステップを実行する前にスクリーンショットを無効にしてステップの実行後に有効にします。

API Canary の setConfig(options)

API Canary の場合、setConfig には次のブール値のパラメータを含めることができます。

continueOnHttpStepFailure (ブール値) – HTTP ステップが失敗した後も Canary スクリプトの実行を続行するかどうか (これは executeHttpStep 関数を参照します)。いずれかのステップが失敗しても、Canary 実行は失敗としてマークされます。デフォルト: true。

ビジュアルモニターリング

ビジュアルモニターリングは、Canary 実行中に撮影されたスクリーンショットと、ベースライン Canary 実行中に撮影されたスクリーンショットを比較します。2 つのスクリーンショットの不一致がしきい値のパーセンテージを超えると、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:」などが先頭に追加されます。

SyntheticsLogger は、Synthetics Canary ログ記録と同じログレベルで Synethetics ライブラリを実行する場合に使用できます。

S3 の結果の場所にアップロードされるログファイルを作成する場合、SyntheticsLogger を使用する必要はありません。代わりに、別のログファイルを /tmp フォルダ内に作成できます。/tmp フォルダ内に作成したファイルは、アーティファクトとして S3 の結果の場所にアップロードされます。

Synthetics Library logger を使用するには:


const log = require('SyntheticsLogger');

有用な関数定義:

log.debug(message, ex);