Node.js Canary 用のライブラリ関数

このセクションでは、Node.js ランタイムを使用して Canary スクリプトで使用できるライブラリ関数について説明します。

addExecutionError(errorMessage, ex);

errorMessage はエラーの詳細を示し、ex は発生した例外を示します

addExecutionError を使用すると、Canary の実行エラーを設定できます。これにより、スクリプトの実行を中断することなく Canary を失敗させることができます。また、successPercent メトリクスにも影響を与えません。

Canary スクリプトの成功または失敗を確認するために重要でない場合にのみ、エラーを実行エラーとして追跡するようにします。

addExecutionError の使用例を次に示します。ここでは、エンドポイントの可用性をモニターリングしながら、ページが読み込まれた後にスクリーンショットを取得しています。スクリーンショットの作成に失敗したとしても、エンドポイントの可用性が判断されるわけではないため、スクリーンショットの作成中に発生したすべてのエラーは、キャッチした上で実行エラーとして追加します。可用性に関するメトリックスには、依然としてエンドポイントが起動し実行中であることが示されていますが、Canary のステータスは失敗としてマークされています。次に示すコードブロックのサンプルでは、このようなエラーをキャッチし、実行エラーとして追加します。

try {await synthetics.executeStep(stepName, callbackFunc);} catch(ex) {synthetics.addExecutionError('Unable to take screenshot ', ex);}

getCanaryName();

Canary の名前を返します。

getCanaryArn();

Canary の ARN を返します。

getCanaryUserAgentString();

canary のカスタムユーザーエージェントを返します。

getRuntimeVersion();

この関数は、ランタイムバージョン syn-nodejs-3.0 以降で使用できます。これは、Canary の Synthetics ランタイムバージョンを返します。例えば、戻り値は syn-nodejs-3.0 になる可能性があります。

getLogLevel ();

Synthetics ライブラリの現在のログレベルを取得します。取り得る値には以下のものがあります。

例:

let logLevel = synthetics.getLogLevel();

setLogLevel();

Synthetics ライブラリのログレベルを設定します。取り得る値には以下のものがあります。

例:

synthetics.setLogLevel(0);

executeStep(stepName, functionToExecute, [stepConfig])

指定されたステップを実行します。ステップは、開始/成功/失敗のログ記録、成功/失敗と所要時間のメトリクスでラップされます。

executeStep 関数は、次のことも行います。

例

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

提供された HTTP リクエストをステップとして実行し、SuccessPercent (pass/fail) および Duration メトリクスを発行します。

executeHttpStep は、リクエストで指定されたプロトコルに応じて、HTTP または HTTPS ネイティブ関数のいずれかを内部で使用します。

この関数は、Canary のレポートにステップ実行の概要も追加します。概要には、次のような各 HTTP リクエストの詳細が含まれます。

パラメータ

stepName(文字列)

ステップの名前を指定します。この名前は、このステップの CloudWatch メトリクスを発行する場合にも使用されます。

requestOptions(オブジェクトまたは文字列)

このパラメータの値には、URL、URL 文字列、またはオブジェクトを指定できます。オブジェクトの場合、HTTP リクエストを行うために設定可能なオプションのセットである必要があります。Node.js ドキュメントの http.request(options[, callback]) のすべてのオプションをサポートしています。

これらの Node.js オプションに加えて、requestOptions では、追加のパラメータ body がサポートされます。body パラメータを使用して、データをリクエスト本文として渡すことができます。

callback(レスポンス)

(オプション) これは HTTP レスポンスで呼び出されるユーザー関数です。レスポンスは、Class: http.IncomingMessage のタイプです。

stepConfig(オブジェクト)

(オプション) このパラメータを使用して、このステップについて、異なる設定でグローバル Synthetics 設定を上書きします。

executeHttpStep の使用例

次の一連の例は、このオプションのさまざまな用途を説明するために、相互に関連しています。

この最初の例では、リクエストパラメータを設定します。requestOptions として URL を渡すことができます:

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

または、一連のオプションを渡すことができます:

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

次の例では、レスポンスを受け入れるコールバック関数を作成します。デフォルトでは、コールバックを指定しない場合、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 ステップの successPercent および duration メトリクスが表示されます。API 呼び出しステップのメトリクスをモニターリングすることで、API のパフォーマンスをモニターリングできます。

これらの関数を使用する完全なスクリプトのサンプルについては、「マルチステップ API Canary」を参照してください。