# Canary を作成する **重要** Synthetics Canary を使用して、所有権またはアクセス許可を持つエンドポイントと API のみを監視します。Canary の実行回数の設定によっては、これらのエンドポイントでのトラフィックが増える場合があります。 CloudWatch コンソールを使用して Canary を作成する場合、CloudWatch が提供するブループリントを使用して Canary を作成することも、独自のスクリプトを作成することもできます。詳細については、「[Canary 設計図の使用](CloudWatch_Synthetics_Canaries_Blueprints.md)」を参照してください。 Canary に独自のスクリプトを使用している場合は、CloudFormation を使用して Canary を作成することもできます。詳細については、*AWS CloudFormation ユーザーガイド*の [AWS::Synthetics::Canary](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-synthetics-canary.html) を参照してください。 独自のスクリプトを作成する場合は、CloudWatch Synthetics によってライブラリに組み込み済みの複数の関数を使用できます。詳細については、「[Synthetics のランタイムバージョン](CloudWatch_Synthetics_Canaries_Library.md)」を参照してください。 **注記** Canary を作成すると、作成されるレイヤーの 1 つは、先頭に ` Synthetics` の追加された Synthetics レイヤーになります。このレイヤーは Synthetics サービスアカウントが所有し、ランタイムコードを含みます。 **Canary を作成するには** 1. CloudWatch コンソールの [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) を開いてください。 1. ナビゲーションペインで、**[Application Signals]**、**[Synthetics Canary]** の順に選択します。 1. **[Canary を作成]** を選択します。 1. 次のいずれかを選択します。 + Canary を設計図スクリプトに基づいて作成するには、[**Use a blueprint**] を選択し、作成する Canary のタイプを選択します。設計図のタイプ別の詳細な動作については、「[Canary 設計図の使用](CloudWatch_Synthetics_Canaries_Blueprints.md)」を参照してください。 + 独自の Node.js スクリプトをアップロードしてカスタムの Canary を作成するには、[**Upload a script**] を選択します。 次に、スクリプトを [**Script**] 領域にドラッグするか、[**Browse files**] を選択してファイルシステム内のスクリプトに移動できます。 + S3 バケットからスクリプトをインポートするには、[**Import from S3**] を選択します。[**Source location**] で、Canary への完全なパスを入力するか、[**Browse S3**] を選択します。 使用する S3 バケットの `s3:GetObject` および `s3:GetObjectVersion` アクセス許可が必要です。バケットは、Canary を作成するのと同じ AWS リージョンに存在する必要があります。 1. [**名前**] に、Canary の名前を入力します。この名前は多くのページで使用されるため、他の Canary と区別できるわかりやすい名前を付けてください。 1. [**Application or endpoint URL**] に、Canary でテストする URL を入力します。この URL には、プロトコル (https:// など) を含める必要があります。 VPC のエンドポイントを Canary でテストする場合は、この手順の後半で VPC に関する情報も入力する必要があります。 1. Canary 用に独自のスクリプトを使用している場合は、**[Lambda handler]** に Canary を開始するエントリポイントを入力します。Lambda ハンドラー形式の詳細については、「[Synthetics のランタイムバージョン](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_Library.html)」を参照してください。 1. **[スクリプトエディタ]** の **[ランタイムバージョン]** で、Canary を実行する Synthetics ランタイムバージョンを選択します。Synthetics のランタイムバージョンの詳細については、「[Synthetics のランタイムバージョン](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_Library.html)」を参照してください。 **[ブラウザの設定]** で、ブラウザを有効にして Canary をテストできます。少なくとも 1 つのブラウザを選択する必要があります。 1. スクリプトで環境変数を使用している場合は、**[環境変数]** を選択し、スクリプトで定義されている各環境変数の値を指定します。詳細については、「[環境変数](CloudWatch_Synthetics_Canaries_WritingCanary_Nodejs_Pup.md#CloudWatch_Synthetics_Environment_Variables)」を参照してください。 1. [**スケジュール**] で、この Canary を 1 回だけ実行するか、レート式を使用して連続して実行するか、cron 式を使用してスケジュールするかを選択します。 + CloudWatch コンソールを使用して継続的に動作する Canary を作成する場合、1 分から 1 時間に 1 回までの任意の間でレートを選択できます。 + Canary スケジューリング用の cron 式の記述の詳細については、「[cron を使用して Canary 実行をスケジュールする](CloudWatch_Synthetics_Canaries_cron.md)」を参照してください。 1. (オプション) canary のタイムアウト値を設定するには、[**追加設定**] を選択してタイムアウト値を指定します。Lambda コールドスタートと canary インストルメンテーションの起動にかかる時間を許容するには、15 秒以上にします。 1. **[データ保持]** で、失敗した Canary の実行と成功した Canary の実行の両方に関する情報を保持する期間を指定します。指定できる範囲は 1～455 日です。 この設定は、[GetCanaryRuns](https://docs.aws.amazon.com/AmazonSynthetics/latest/APIReference/API_GetCanaryRuns.html) オペレーションによって返される情報の範囲と、Synthetics コンソールに表示される情報の範囲に影響します。 Amazon S3 バケットに保存されているデータ、canary によって公開されるログやメトリックスには影響しません。 Canary のデータ保持期間にかかわらず、コンソールに表示される情報の範囲には特定の制限があります。Synthetics コンソールのホームビューでは、相対時間範囲と絶対時間範囲が 7 日間に制限されています。特定の Canary の Synthetics コンソールビューでは、相対時間範囲は 7 日間に制限され、絶対時間範囲は 30 日間に制限されます。 1. **[データストレージ]** で、Canary の実行データを保存する先の Amazon S3 バケットを選択します。バケット名にピリオド (.) を含めることはできません。これを空白のままにすると、デフォルトの Amazon S3 バケットが使用または作成されます。 1. (オプション) Canary のデフォルトでは、そのアーティファクトが Amazon S3 に保存され、そのアーティファクトに対しては AWS 管理のAWS KMS キーにより保存時の暗号化が行われます。**[Data Storage]** (データストレージ) セクションの　**[Additional configuration]** (その他の設定) をクリックすることで、別の暗号化オプションを使用することも可能です。その後、暗号化に使用するキーのタイプを選択します。詳細については、「[Canary アーティファクトの暗号化](CloudWatch_Synthetics_artifact_encryption.md)」を参照してください。 1. **[アクセス許可]** で、Canary を実行するための IAM ロールを作成するか、既存のロールを使用するかを選択します。 CloudWatch Synthetics がロールを作成している場合、必要な許可がすべて自動的に含まれます。自らロールを作成する場合は、必要な許可に関する情報について、「[Canary に必要なロールとアクセス許可](CloudWatch_Synthetics_Canaries_CanaryPermissions.md)」を参照してください。 Canary の作成時に CloudWatch コンソールを使用して Canary 用のロールを作成する場合、他の Canary 用のロールは再利用できません。これらのロールは 1 つの Canary に固有です。複数の Canary 用のロールを手動で作成済みである場合は、その既存のロールを使用できます。 既存のロールを使用するには、そのロールを Synthetics および Lambda に渡すための `iam:PassRole` アクセス許可が必要です。また、`iam:GetRole` アクセス許可も必要です。 1. (オプション) [**Alarms**] で、この Canary 用にデフォルトの CloudWatch アラームを作成するかどうかを選択します。アラームの作成を選択すると、`Synthetics-Alarm-canaryName -index ` の名前規則で作成されます。 `index` は、この Canary 用に作成された異なる各アラームを表す数値です。最初のアラームのインデックスは 1、2 番目のアラームのインデックスは 2 です。 1. (オプション) この Canary で VPC のエンドポイントをテストするには、[**VPC settings**] を選択し、次の操作を行います。 1. エンドポイントをホストする VPC を選択します。 1. VPC 上の 1 つ以上のサブネットを選択します。実行中に IP アドレスを Lambda インスタンスに割り当てることができない場合は、Lambda インスタンスをパブリックサブネットで実行するように設定できないため、プライベートサブネットを選択する必要があります。詳細については、「[VPC 内のリソースにアクセスできるように Lambda 関数を設定する](https://docs.aws.amazon.com/lambda/latest/dg/configuration-vpc.html)」を参照してください。 1. VPC 上で 1 つ以上のセキュリティグループを選択します。 1. この Canary が IPv6 アドレス宛にトラフィックを送信できるようにするには、**[デュアルスタックサブネットの IPv6 トラフィックを許可]** を選択します。これにより、Canary は IPv6 のみ、およびデュアルスタックが有効なエンドポイントを IPv6 経由でモニタリングできます。 Canary にインターネットアクセスを許可し、VPC サブネットを適切に設定することで、VPC 外部のエンドポイントをモニタリングできるようになります。詳細については、「[VPC で Canary を実行する](CloudWatch_Synthetics_Canaries_VPC.md)」を参照してください。 エンドポイントが VPC 上にある場合は、Canary から CloudWatch と Amazon S3 に情報を送信できるようにする必要があります。詳細については、「[VPC で Canary を実行する](CloudWatch_Synthetics_Canaries_VPC.md)」を参照してください。 1. (オプション) [**Tags**] で、この Canary のタグとする 1 つ以上のキーと値のペアを追加します。タグを使用すると、AWS リソースを識別して整理したり、AWS コストを追跡したりしやすくなります。詳細については、「[Amazon CloudWatch リソースにタグを付ける](CloudWatch-Tagging.md)」を参照してください。 Canary に適用するタグを Canary が使用する Lambda 関数にも適用する場合は、**[タグレプリケーション]** で **[Lambda 関数]** を選択します。このオプションを選択すると、CloudWatch Synthetics は Canary と Lambda 関数のタグの同期を維持します。 + Synthetics は、ここで指定したのと同じタグを Canary と Lambda 関数の両方に適用します。 + このオプションを選択したまま、後で Canary のタグを更新すると、Synthetics は Lambda 関数のタグを変更して Canary との同期を維持します。 1. (オプション) **[アクティブトレース]** で、この Canary にアクティブな X-Ray トレースを有効にするかどうかを選択します。[アクティブトレース] は Puppeteer および Java ランタイムでのみ使用できます。詳細については、「[Canary と X-Ray のトレース](CloudWatch_Synthetics_Canaries_tracing.md)」を参照してください。 ## Canary 向けに作成されたリソース Canary を作成すると、次のリソースが作成されます。 + `CloudWatchSyntheticsRole-canary-name -uuid` という名前の IAM ロール (CloudWatch コンソールを使用して Canary を作成し、この Canary 用に新しいロールを作成することを指定した場合) + `CloudWatchSyntheticsPolicy- canary-name-uuid` という名前の IAM ポリシー + `cw-syn-results-accountID -region` という名前の S3 バケット + `Synthetics-Alarm-MyCanaryName` という名前のアラーム (Canary 用にアラームを作成した場合) + Lambda 関数とレイヤー (設計図を使用して Canary を作成した場合)。これらのリソースには、プレフィックスとして `cwsyn-MyCanaryName` が付きます。 + `/aws/lambda/cwsyn-MyCanaryName -randomId` という名前の CloudWatch Logs ロググループ。 # Canary 設計図の使用 このセクションでは、Canary の各設計図と、各設計図に最も適合するタスクについて詳しく説明します。設計図は、以下の Canary タイプのために提供されています: **Topics** + [ハートビートのモニターリング](#CloudWatch_Synthetics_Canaries_Blueprints_Heartbeat) + [API Canary](#CloudWatch_Synthetics_Canaries_Blueprints_API) + [リンク切れチェッカー](#CloudWatch_Synthetics_Canaries_Blueprints_Broken_Links) + [ビジュアルモニターリングの設計図](#CloudWatch_Synthetics_Canaries_Blueprints_VisualTesting) + [Canary Recorder](#CloudWatch_Synthetics_Canaries_Blueprints_Recorder) + [GUI ワークフロービルダー](#CloudWatch_Synthetics_Canaries_Blueprints_GUI_Workflow) + [マルチチェックのブループリント](#CloudWatch_Synthetics_Canaries_Blueprints_Multichecks_Blueprint) + [マルチチェックブループリント Canary の作成](CloudWatch_Synthetics_Canaries_MultiCheck_Blueprint.md) 設計図を使用して Canary を作成する場合、CloudWatch コンソールの各フィールドに入力するに従って、作成中の Canary がページの [**スクリプトエディタ**] 領域に Node.js スクリプトとして表示されます。この領域で Canary を編集し、さらにカスタマイズすることもできます。 ## ハートビートのモニターリング ハートビートスクリプトは、指定した URL をロードし、ページのスクリーンショットと HTTP アーカイブファイル (HAR ファイル) を保存します。また、アクセスした URL のログも保存します。 HAR ファイルを使用して、ウェブページに関する詳細なパフォーマンスデータを表示できます。ウェブリクエストのリストを分析し、項目の読み込み時間などのパフォーマンス問題を検出できます。 Canary が `syn-nodejs-puppeteer-3.1` 以降のランタイムバージョンを使用している場合、ハートビートモニターリングブループリントを使用して複数の URL をモニターリングし、Canary 実行レポートのステップの概要で各 URL のステータス、期間、関連付けられたスクリーンショット、失敗の理由を確認できます。 ## API Canary API Canary は、REST API の基本的な読み取り関数と書き込み関数をテストできます。RESTは *Representational State Transfer* の略であり、開発者が API を作成するときに従う一連のルールです。これらのルールの 1 つでは、特定の URL へのリンクがデータを返す必要があることを指定しています。 Canary は任意の API で動作し、すべてのタイプの機能をテストできます。各 Canary は複数の API 呼び出しを行うことができます。 ランタイムバージョン `syn-nodejs-2.2` 以降を使用する Canary では、API Canary ブループリントは、API を HTTP ステップとしてモニターリングする複数ステップの Canary をサポートします。1 つの Canary で複数の API をテストできます。各ステップは、異なる URL にアクセスしたり、異なるヘッダーを使用したり、ヘッダーとレスポンス本文を取得するかどうかについて異なるルールを使用したりできる個別のリクエストです。ヘッダーとレスポンス本文を取得しないことで、機密データが記録されないようにできます。 API Canary 内の各リクエストは、次の情報で構成されます。 + *エンドポイント*。リクエストする URL です。 + *メソッド*。サーバーに送信されるリクエストのタイプです。REST API は、GET (読み取り)、POST (書き込み)、PUT (更新)、PATCH (更新)、DELETE (削除) の各オペレーションをサポートしています。 + *ヘッダー*。クライアントとサーバーの両方に情報を提供します。これらは認証に使用され、本文の内容に関する情報を提供します。有効なヘッダーのリストについては、「[HTTPヘッダー](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers)」をご参照ください。 + *データ* (または*本文*)。サーバーに送信される情報を含みます。これは、POST、PUT、PATCH、または DELETE の各リクエストでのみ使用されます。 **注記** API Canary ブループリントは、Playwright ランタイムではサポートされていません。 API Canary ブループリントは、GET メソッドと POST メソッドをサポートしています。この設計図を使用する場合は、ヘッダーを指定する必要があります。例えば、**Authorization** を **[キー]** として指定し、必要な認可データを **[値]** として指定できます。 POST リクエストをテストする場合は、**[データ]** フィールドに書き込むコンテンツも指定します。 **API Gateway との統合** API ブループリントは Amazon API Gateway と統合されています。これにより、API Gateway API やステージを Canary と同じ AWS アカウントやリージョンから選択したり、API Gateway から Swagger テンプレートをアップロードして、クロスアカウントとクロスリージョン API のモニターリングを行ったりすることができます。その後、最初から入力するのではなく、コンソールで残りの詳細を選択して Canary を作成できます。API Gateway の詳細については、「[Amazon API Gateway とは](https://docs.aws.amazon.com/apigateway/latest/developerguide/welcome.html)」を参照してください。 **プライベート API の使用** Amazon API Gateway でプライベート API を使用する Canary を作成できます。詳細については、「[Amazon API Gateway でのプライベート API の作成](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-apis.html)」を参照してください。 ## リンク切れチェッカー リンク切れチェッカーは、`document.getElementsByTagName('a')` を使用して、テスト対象である URL 内のすべてのリンクを収集します。この際、ユーザーが指定したリンク数までがテストされ、また、URL 自体も最初のリンクとしてカウントされます。例えば、5 つのリンクが含まれているページのすべてのリンクをチェックする場合は、Canary が 6 つのリンクをたどるように指定する必要があります。 `syn-nodejs-2.0-beta` ランタイム以降を使用して作成されたリンク切れチェッカー Canary は、次の追加機能をサポートしています。 + チェックされたリンク、ステータスコード、エラーの理由 (存在する場合)、およびソースページとターゲットページのスクリーンショットを含むレポートを生成する。 + Canary の結果を表示するとき、フィルタリングしてリンク切れのみを表示し、エラーの理由に基づいてリンクを修正できます。 + このバージョンでは、各リンクの注釈付きソースページのスクリーンショットがキャプチャされ、リンクが見つかったアンカーが強調表示されます。非表示のコンポーネントには注釈が付けられません。 + キャプチャするスクリーンショットは、ソースおよびターゲットページの両方、ソースページのみ、またはターゲットページのみに設定できます。 + 最初のページから多くのリンクがスクレイプされた場合でも最初のリンク切れの後に Canary スクリプトが停止するという、以前のバージョンの問題は、このバージョンで修正されています。 **注記** 壊れたリンクチェッカーのブループリントは、Playwright ランタイムではサポートされていません。 新しいランタイムを導入するために、`syn-1.0` を使用している既存の Canary を更新する場合は、一度 Canary を削除した上で再作成する必要があります。既存の Canary を新しいランタイムに更新しても、これらの機能は利用可能になりません。 リンク切れチェッカー Canary は、次の種類のリンクエラーを検出します。 + 404 ページが見つからない。 + ホスト名が無効である。 + URL が正しくない。この例としては、URL から角括弧が抜けている、スラッシュが余分についている、プロトコルが間違っているなどが挙げられます。 + HTTP レスポンスコードが無効である。 + ホストサーバーが、コンテンツもなく、レスポンスコードもない、空のレスポンスを返す。 + HTTPリクエストが Canary の実行中に常にタイムアウトする。 + ホストが正しく設定されていないか、ビジーすぎるために接続が常に切断される。 ## ビジュアルモニターリングの設計図 ビジュアルモニターリングの設計図には、Canary 実行中に撮影されたスクリーンショットと、ベースライン Canary 実行中に撮影されたスクリーンショットを比較するコードが含まれています。2 つのスクリーンショット間の不一致がしきい値のパーセンテージを超えている場合、Canary は失敗します。ビジュアルモニターリングは、**syn-puppeteer-node-3.2** 以降で実行中の Canary でサポートされています。Python と Selenium を実行している Canary、または Playwright ランタイムを使用している Canary では現在サポートされていません。 ビジュアルモニターリングのブループリントには、デフォルトの Canary ブループリントスクリプトに次のコード行が含まれており、ビジュアルモニターリングが有効になります。 ``` syntheticsConfiguration.withVisualCompareWithBaseRun(true); ``` この行がスクリプトに追加された後に初めて Canary が正常に実行されると、その実行中に撮影されたスクリーンショットが比較のベースラインとして使用されます。最初に Canary を実行した後、CloudWatch コンソールを使用して Canary を編集して、次のいずれかの操作を行うことができます。 + Canary の次の実行を新しいベースラインとして設定する。 + 現在のベースラインスクリーンショットに境界を描画し、ビジュアル比較時に無視するスクリーンショットの領域を指定する。 + スクリーンショットをビジュアルモニターリングに使用しないようにする。 CloudWatch コンソールを使用して Canary を編集する方法の詳細については、 「[Canary を編集または削除する](synthetics_canaries_deletion.md)」を参照してください。 また、` nextrun` または `lastrun` パラメーターを指定するか、Canary 実行 ID を [UpdateCanary](https://docs.aws.amazon.com/AmazonSynthetics/latest/APIReference/API_UpdateCanary.html) API で指定することにより、ベースラインとして使用される Canary 実行を変更することもできます。 ビジュアルモニターリングの設計図を使用する場合は、スクリーンショットを撮影する URL を入力し、差分しきい値をパーセンテージで指定します。ベースライン実行後、そのしきい値よりも大きい視覚差を検出する Canary を今後実行すると、Canary 障害がトリガーされます。ベースライン実行後、Canary を編集して、ビジュアルモニターリング中に無視するベースラインスクリーンショットに境界線を「描画」することもできます。 ビジュアルモニターリング機能は、ImageMagick オープンソースソフトウェアツールキットによって機能します。詳細については、「[ImageMagick](https://imagemagick.org/index.php)」を参照してください。 ## Canary Recorder Canary レコーダーの設計図を使用すると、CloudWatch Synthetics Recorder を使用してウェブサイトでクリックおよび入力のアクションを記録し、同じステップに従う Canary を作成するために使用できる Node.js スクリプトを自動的に生成できます。CloudWatch Synthetics Recorder は、Amazon が提供する Google Chrome 拡張機能です。Canary レコーダーは、Playwright ランタイムを使用する Canary ではサポートされていません。 **クレジット**: CloudWatch Synthetics Recorder は、[Headless レコーダー](https://github.com/checkly/headless-recorder)に基づいています。 詳細については、「[Google Chrome の CloudWatch Synthetics Recorder を使用する](CloudWatch_Synthetics_Canaries_Recorder.md)」を参照してください。 ## GUI ワークフロービルダー GUI ワークフロービルダー設計図は、ウェブページに対してアクションを実行できることを検証します。例えば、ウェブページにログインフォームがある場合、Canary はユーザーフィールドとパスワードフィールドに入力し、このフォームを送信してウェブページが正しく動作していることを検証できます。 このタイプの Canary を設計図を従って作成する場合は、Canary がウェブページに対して実行するアクションを指定します。使用できるアクションは次のとおりです。 + **クリック** – 指定した要素を選択し、ユーザーによる要素のクリックまたは選択をシミュレートします。 Node.js スクリプトで要素を指定するには、`[id=]` または ` a[class=]` を使用します。 Python スクリプトで要素を指定するには、`xpath //*[@id=]` または ` //*[@class=]` を使用します。 + **セレクタの検証** – 指定した要素がウェブページに存在することを検証します。このテストは、以前のアクションによって正しい要素がページに入力されていることを検証するのに役立ちます。 Node.js スクリプトで検証する要素を指定するには、`[id=]` または ` a[class=]` を使用します。 Python スクリプトで検証する要素を指定するには、`xpath //*[@id=]` または `//*[class=]` を使用します。 + **テキストの検証** – 指定した文字列がターゲット要素内に含まれていることを検証します。このテストは、事前のアクションが正しいテキストを表示したかどうかを確認するのに役立ちます。 このアクションでは Puppeteer の ` div[@id=]//h1` 関数を使用するため、Node.js スクリプト内の要素を指定するには `waitForXPath` などの形式を使用します。 Python スクリプトで要素を指定するには、このアクションは Selenium で ` //*[@id=] ` 関数を使用するため、`implicitly_wait` または //\$1[@class=] などの xpath 形式を使用します。 + **テキストの入力** – 指定したテキストをターゲット要素に書き込みます。 Node.js スクリプトで検証する要素を指定するには、`[id=]` または ` a[class=]` を使用します。 Python スクリプトで検証する要素を指定するには、`xpath //*[@id=]` または `//*[@class=]` を使用します。 + **クリックして移動** – 指定した要素を選択した後で、ページ全体が読み込まれるまで待ちます。これは、ページを再度読み込む必要がある場合に最も役立ちます。 Node.js スクリプトで要素を指定するには、`[id=]` または ` a[class=]` を使用します。 Python スクリプトで要素を指定するには、`xpath //*[@id=]` または ` //*[@class=]` を使用します。 例えば、次のブループリントでは Node.js を使用しています。このスクリプトは指定した URL の **[firstButton]** をクリックし、想定したセレクタで想定されたテキストが表示されることを検証します。さらに、名前 `Test_Customer` を **[名前]** フィールドに入力して **[ログイン]** ボタンをクリックし、次のページに **[ようこそ]** テキストが表示されることを確認し、そのログインが成功したことを検証します。 ![\[コンソールの Canary の作成ページ。GUI ワークフロー設計図のフィールドが入力されています。\]](http://docs.aws.amazon.com/ja_jp/AmazonCloudWatch/latest/monitoring/images/canary_create_gui_workflow.PNG) 次のランタイムを使用する GUI ワークフロー Canary は、各 Canary 実行に対して実行されたステップの概要も提供します。各ステップに関連付けられたスクリーンショットおよびエラーメッセージを使用して、エラーの根本原因を見つけることができます。 + `syn-nodejs-2.0` 以降 + `syn-python-selenium-1.0` 以降 ## マルチチェックのブループリント マルチチェックブループリントで、Canary の作成が簡単になります。HTTP、DNS、SSL、TCP チェックを実行する、すぐに使用できる機能を提供するシンプルな JSON 設定を使用することで、コストを削減できます。最大 10 個のチェックを設定できます。各チェックを順番に実行される数値ステップとして設定し、Canary フローを明確に理解できるようにします。 マルチチェックブループリントは以下をサポートします。 + 基本的な HTTP リクエスト、TCP リクエスト、DNS レコードの検証、SSL 証明書のモニタリング + Secrets Manager と統合された Basic、API Key、OAuth、Sigv4 などの HTTP 認証方法 + 各チェックのアサーション 詳細については、「[Canary を作成する](CloudWatch_Synthetics_Canaries_Create.md)」を参照してください。 # マルチチェックブループリント Canary の作成 Amazon CloudWatch Synthetics マルチチェックブループリントは、シンプルな JSON 設定を提供することで Synthetics Canary を作成するのに役立ちます。ステップベースのシーケンシャル方式で最大 10 種類の HTTP/DNS/SSL/TCP チェックをバンドルすることで、コストを削減できます。各チェックには、チェック結果に対する基本的な検証を提供するアサーションが含まれます。 マルチチェック Canary は、ヘッドレスブラウザを使用しない基本チェックのみを必要とするシンプルなユースケース向けに設計されています。より複雑なユースケースについては、Amazon CloudWatch Synthetics が提供する他の Canary タイプを確認してください。 **Topics** + [前提条件](#CloudWatch_Synthetics_MultiCheck_Prerequisites) + [制限事項](#CloudWatch_Synthetics_MultiCheck_Limitations) + [パッケージ構造、JSON スキーマ、および設定](#CloudWatch_Synthetics_MultiCheck_Packaging) + [AWS マネジメントコンソール でのマルチチェック Canary の作成](#CloudWatch_Synthetics_MultiCheck_Console) + [AWS Synthetics API を使用したマルチチェック Canary の作成](#CloudWatch_Synthetics_MultiCheck_API) + [CloudFormation でのマルチチェック Canary の作成](#CloudWatch_Synthetics_MultiCheck_CloudFormation) + [認証の設定](#CloudWatch_Synthetics_MultiCheck_Authentication) + [トラブルシューティング](#CloudWatch_Synthetics_MultiCheck_Troubleshooting) ## 前提条件 + マルチチェック Canary を作成するには、syn-nodejs-3.0\$1 を使用している必要があります。 + Authentication and Secrets Manager 設定を使用する場合は、Canary [ExecutionRoleArn](https://docs.aws.amazon.com/AmazonSynthetics/latest/APIReference/API_CreateCanary.html) がこれらのシークレットへのアクセスを許可していることが必要です + Authentication for Sigv4 を使用する場合は、Canary [ExecutionRoleArn](https://docs.aws.amazon.com/AmazonSynthetics/latest/APIReference/API_CreateCanary.html) が関連するロールへのアクセスを許可していることが必要です ## 制限事項 + HTTP レスポンスサイズは 1 MB 以下 + 定義済み変数は最大 10 個。 + JSON RFC を使用する場合、Checks JSON には重複するフィールドが指定されている場合がありますが、最後のシーケンシャルフィールドのみが使用されます。 + AWS マネジメントコンソール では、マルチチェック Canary はデフォルトでマルチチェックステップメトリクスを表示して、各チェックが使用できるかどうかすぐに識別できるようにします。チェックが削除されても、メトリクスが少なくとも 3 時間アクティブでなくなるまで、このグラフの可用性グラフにチェックが表示されることがあります。 ## パッケージ構造、JSON スキーマ、および設定 Canary に使用される JSON Checks 設定には、` blueprint-config.json` という名前を付ける必要があります。設定は[スキーマ](https://github.com/aws-samples/synthetics-canary-local-debugging-sample/tree/main)に従い、「[Node.js マルチチェックブループリントの JSON 設定の記述](CloudWatch_Synthetics_WritingCanary_Multichecks.md)」の手順に従う必要があります。 `blueprint-config.json` を ZIP ファイルに圧縮し、次のいずれかの作成ワークフローで指定します。`synthetics.json` 設定がある場合、これも同じ ZIP ファイルで圧縮されます。以下は、`multi-checks.zip` という zip ファイルの例です。 ``` multi-checks.zip ├── blueprint-config.json └── synthetics.json ``` ## AWS マネジメントコンソール でのマルチチェック Canary の作成 1. Amazon CloudWatch Synthetics コンソールを開きます。 1. **[Canary を作成]** を選択します。 1. **[設計図を使用する]** で、**[マルチチェック]** を選択します。 **[チェックを設定]** に、**[チェック]** と **[Canary 設定]** の 2 つのタブが表示されます。 1. ランタイムバージョン **syn-nodejs-3.0** 以降を選択します。 1. [Node.js マルチチェックブループリントの JSON 設定の記述](CloudWatch_Synthetics_WritingCanary_Multichecks.md) にある手順に従って、実行するチェックを記述します。または、コンソールにデフォルトの JSON 設定が用意されているため、これに基づいて構築することもできます。 1. **[Canary を作成]** を選択します。 ## AWS Synthetics API を使用したマルチチェック Canary の作成 `Code` パラメータ内で `CreateCanary` API を使用し、` Handler` ではなくフィールド/値として `BlueprintTypes="multi-checks"` を指定します。`BlueprintTypes` と `Handler` の両方を指定すると、`ValidationException` が表示されます。提供されるランタイムバージョンは `syn-nodejs-3.0` 以降でなければなりません。 ``` aws synthetics create-canary \ --name my-multi-check-canary \ --code ZipFile="ZIP_BLOB",BlueprintTypes="multi-checks" \ --runtime-version syn-nodejs-3.0 \ ... // Or if you wanted to use S3 to provide your code. aws synthetics create-canary \ --name my-multi-check-canary \ --code S3Bucket="my-code-bucket",S3Key="my-zip-code-key",BlueprintTypes="multi-checks" \ ... ``` ## CloudFormation でのマルチチェック Canary の作成 マルチチェック Canary の CloudFormation テンプレートの `Code` パラメータ内で、` Handler` ではなくフィールド/値として `BlueprintTypes="multi-checks"` を指定します。`BlueprintTypes` と `Handler` の両方を指定すると、`ValidationException` が表示されます。提供されるランタイムバージョンは `syn-nodejs-3.0 or later` である必要があります。 テンプレートの例: ``` SyntheticsCanary: Type: 'AWS::Synthetics::Canary' Properties: Name: MyCanary RuntimeVersion: syn-nodejs-3.0 Schedule: {Expression: 'rate(5 minutes)', DurationInSeconds: 3600} ... Code: S3Bucket: "my-code-bucket" S3Key: "my-zip-code-key" BlueprintTypes: ["multi-checks"] ... ``` ## 認証の設定 認証されたエンドポイントに Canary が HTTP リクエストを行う場合、Basic、API キー、OAuth クライアント認証情報、SigV4 の 4 つの認証タイプのいずれかを使用するようにブループリント Canary の手順を設定できます。リクエストヘッダーを自分で設定するのではなく、ブループリント定義で認証タイプを指定できます。そうすると、Synthetics は指定された認証タイプに従って、HTTP リクエストのコンポーネントに提供された認証情報を入力します。 ブループリントステップの認証セクションで認証タイプを指定します。使用する認証スキーム、選択した認証スキームに必要なプロパティを指定します。そうすると、Synthetics は提供された情報を使用して HTTP リクエストの認証ヘッダーを作成します。 シークレット (パスワードや API キーなど) をプレーンテキストで保存するとセキュリティ上の懸念があるため、Synthetics は AWS Secrets Manager との統合をサポートしています。Synthetics ブループリント Canary で HTTP リクエストを認証する場合は、認証情報を保存するシークレットを参照すると、Synthetics はシークレットの取得と Canary でのキャッシュを処理します。このアプローチによって、ブループリント設定でシークレットをプレーンテキストで指定することなく、シークレットを安全に保存しながら Synthetics にシークレットが提供されます。 AWS Secrets Manager の詳細については、「[AWS Secrets Manager とは](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)」を参照してください。 ### 基本認証 Synthetics は、RFC 7617 で定義された Basic HTTP 認証スキームを実装します。このプロセスは次のように機能します。 + ユーザー名とパスワードのペアは、ブループリント設定から提供されます。 + ユーザーパスは、ユーザー名、単一コロン (":") 文字、パスワードを連結することによって作成されます。 + ユーザーパスは UTF-8 でエンコードされ、base64 でエンコードされた文字列に変換されます。 + この base64 でエンコードされたユーザーパスは、「Authorization」ヘッダーで次の形式で提供されます: Authorization: Basic \$1base64-encoded-user-pass\$1 例えば、ユーザーエージェントが user-id「Aladdin」とパスワード「open sesame」を送信する場合、次のヘッダーフィールドを使用します: Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== 設定例: ``` "Authentication": { "type": "BASIC", "username": MY_USERNAME, // Required "password": MY_PASSWORD // Required } ``` ### API キー認証 HTTP リクエストを認証するための API キーを指定できます。API キー認証を使用する場合、指定した API キーが「X-API-Key」HTTP ヘッダーに入ります。これ以外のヘッダーで API キーヘッダーを検索するカスタムリソースがある場合は、オプションで別のヘッダー名を指定して、Synthetics に API キーを入れさせることができます。 設定例: ``` "Authentication": { "type": "API_KEY", "apiKey": S0A1M2P3L4E5, // Required "header": X-Specific-Header // Optional, defaults to "X-API-Key" } ``` ### SigV4 認証 AWS SigV4 (Signature Version 4) は、AWS API リクエストに認証情報を追加するための AWS 署名プロトコルです。SigV4 で認証されたリクエストを行うには、リクエスト先のリージョンとサービス、および Canary が引き受ける IAM ロールを識別する ARN (AWS リソースネーム) を、この SigV4 リクエストを行うときに指定する必要があります。Synthetics は roleArn で指定された IAM ロールを引き受け、それを使用して AWS API リクエストを認証します。 設定例: ``` "Authentication": { "type": "SIGV4", "region": us-west-2, // Required "service": s3, // Required "roleArn": arn:AWS:iam:12345678912:role/SampleRole // Required } ``` #### SigV4 に関する考慮事項 Synthetics が SigV4 認証セクションで指定したロールを引き受けるには、そのロールにアタッチされた信頼ポリシーを設定して、指定された roleArn を Canary が引き受けられるようにする必要があります。信頼する必要がある AWS プリンシパルは、Canary が AWS STS を通じて引き受けたロールです。` aws:sts::{account_running_the_canary}:assumed-role//` arn: の形式を取ります。 例えば、アカウント 0123456789012 で test-canary という名前の Canary が実行されていて、引き受けたロールが canary-assume-role という名前だった場合、Canary が SigV4 認証用に roleArn を正しく引き受けるためには、信頼ポリシーに次のステートメントを含める必要があります。 ``` { "Effect": "Allow", "Principal": { "AWS": "arn:AWS:sts::123456789012:assumed-role/test-canary/" }, "Action": "sts:AssumeRole" } ``` ### OAuth クライアントの認証情報 Synthetics は、RFC 6479 セクション 4.4 で定義されている OAuth クライアント認証情報グラントタイプを実装します。OAuth トークンエンドポイントによって発行されたベアラートークンで認証されたエンドポイントに HTTP リクエストを行う場合、Synthetics はユーザーに代わってベアラートークンをリクエストおよび管理できます。OAuth スキームを使用する場合、Synthetics は次の手順を実行します。 + clientId と clientSecret で Basic 認証スキームを使用して、ベアラートークンを発行するエンドポイントである tokenUrl へのリクエストを認証する + オプションのスコープ、対象者、リソースパラメータを指定すると、トークンリクエストに含まれます。 + tokenUrl が返したアクセストークンを使用して HTTP リクエストを認証する + 将来のトークンリクエストのために tokenUrl から返された更新トークンを安全に保存する 設定例: ``` "Authentication": { "type": "OAUTH_CLIENT_CREDENTIALS", "tokenUrl": ..., // Required "clientId": ..., // Required "clientSecret": ..., // Required "scope": ..., // Optional "audience": ..., // Optional "resource": ..., // Optional } ``` #### OAuth に関する考慮事項 Synthetics は、401 または 407 の応答が返されたときに OAuth トークンを更新します。 ### AWS Secrets Manager の統合 シークレット値 (パスワードや API キーなど) をプレーンテキストで保存しないように、Synthetics では AWS Secrets Manager との統合ができます。ブループリント設定のシークレット値全体を ` ${aws_SECRET:}` 形式で参照することも、特定のキーを ` ${aws_SECRET::}` で参照することもできます。 例えば、login/basic-auth-credentials という名前のシークレットがある場合、ユーザー名とパスワードを次の JSON 構造で保存します。 ``` { "username": "Aladdin", "password": "open sesame" } ``` ブループリント設定でユーザー名とパスワードを次のように参照できます。そうすると、Synthetics はシークレット値を取得し、そのキーを使用してリクエストを認証します。 ``` "Authentication": { "type": "BASIC", "username": ${AWS_SECRET:login/basic-auth-credentials:username}, "password": ${AWS_SECRET:login/basic-auth-credentials:password} } ``` Synthetics が指定されたシークレットを取得できるようにするには、Canary が引き受けるロール ARN に secretsManager:GetSecretValue アクセス許可が必要です。シークレットが AWS マネージドキー AWS/secretsmanager ではなくカスタマーマネージドキーを使用して暗号化されている場合、そのキーに対する kms:Decrypt アクセス許可も必要です。 アクセス許可の例: ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "secretsmanager:GetSecretValue", "Resource": "arn:AWS:secretsmanager:us-east-1:123456789012:secret:secretName-AbCdEf" }, { "Effect": "Allow", "Action": "kms:Decrypt", "Resource": "arn:AWS:kms:us-east-1:123456789012:key/key-id" } ] } ``` ## トラブルシューティング ### 一般的な障害のトラブルシューティング マルチチェックブループリントの基盤となるコードは Typescript で記述されます。一般的な障害については、Canary のトラブルシューティングページ「[Canary の障害のトラブルシューティング](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_Troubleshoot.html)」を参照してください。 ### JSON チェック設定構文エラー Canary の JSON チェック設定に関連する構文エラーがある場合、AWS マネジメントコンソール では Canary を作成しようとするときに失敗の理由が表示されます。API または CloudFormation を使用して Canary を作成する場合、Canary が初めて実行されると失敗が表示されます。マルチチェック Canary には、安全な Canary 更新ワークフローを使用することをお勧めします。詳細については、「[安全な Canary 更新の実行](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/performing-safe-canary-upgrades.html)」を参照してください。 ### ネットワークまたはタイムアウトの障害 タイムアウトに関連する断続的または一貫した障害やネットワーク接続の障害 (ENOTFOUND、ECONNRESET など) では、次の実行でチェックが失敗する理由の詳細が表示されるように ` DEBUG` ログをオンにすることを検討してください。そのためには、環境変数 CW\$1SYNTHETICS\$1LOG\$1LEVEL: "DEBUG" を指定します。 それでもデバッグできない障害が発生した場合は、AWS サポートに問い合わせるか、CloudWatch Synthetics から提供されている他のいずれかの Canary タイプの方がユースケースにより適合するかどうかを確認することを検討してください。 # Google Chrome の CloudWatch Synthetics Recorder を使用する Amazon では、Canary をより簡単に作成できるように、CloudWatch Synthetics Recorder を提供しています。このレコーダーは Google Chrome の拡張機能です。 レコーダーは、ウェブサイト上のクリックと入力のアクションを記録し、同じステップに従う Canary を作成するために使用できる Node.js スクリプトを自動的に生成します。 記録を開始すると、CloudWatch Synthetics Recorder がブラウザーでのアクションを検出し、スクリプトに変換します。記録は、必要に応じて、一時停止および再開できます。記録を停止すると、レコーダーによってアクションの Node.js スクリプトが生成されます。このスクリプトは、[**Copy to Clipboard (クリップボードにコピー)**] ボタンで簡単にコピーできます。その後、このスクリプトを使用して、CloudWatch Synthetics で Canary を作成できます。 **クレジット**: CloudWatch Synthetics Recorder は、[Headless レコーダー](https://github.com/checkly/headless-recorder)に基づいています。 ## Google Chrome 用 CloudWatch Synthetics Recorder 拡張機能をインストールする CloudWatch Synthetics レコーダーを使用するには、Canary の作成を開始し、**Canary Recorder** のブループリントを選択します。レコーダーをまだダウンロードしていない場合は、CloudWatch Synthetics コンソールにダウンロードするためのリンクが表示されます。 または、以下のステップに従って、レコーダーを直接ダウンロードしてインストールすることもできます。 **CloudWatch Synthetics Recorder をインストールするには** 1. Google Chromeを使用して、ウェブサイト[ https://chrome.google.com/webstore/detail/cloudwatch-synthetics-rec/bhdnlmmgiplmbcdmkkdfplenecpegfno](https://chrome.google.com/webstore/detail/cloudwatch-synthetics-rec/bhdnlmmgiplmbcdmkkdfplenecpegfno) にアクセスします 1. [**Add to Chrome (Chrome に追加)**] を選択し、[**Add extension (拡張機能の追加)**] を選択します。 ## Google Chrome の CloudWatch Synthetics Recorder を使用する CloudWatch Synthetics Recorder を使用して Canary を作成する場合、CloudWatch コンソールで **[Canary を作成]** を選択してから、**[ブループリントの使用]**]、[**Canary Recorder**] を選択します。詳細については、「[Canary を作成する](CloudWatch_Synthetics_Canaries_Create.md)」を参照してください。 また、レコーダーを使用してステップを記録し、すぐに Canary の作成に使用しないこともできます。 **CloudWatch Synthetics Recorder を使用してウェブサイトでのアクションを記録するには** 1. モニターリングするページに移動します。 1. Chrome 拡張機能のアイコンを選択し、[**CloudWatch Synthetics Recorder**] を選択します。 1. [**Start Recording (記録の開始)**] を選択します。 1. 記録するステップを実行します。録音を一時停止するには、[**Pause (一時停止)**] を選択します。 1. ワークフローの記録が完了したら、[**Stop recording (記録の停止)**] を選択します。 1. [**Copy to clipboard (クリップボードにコピー)**] を選択して、生成されたスクリプトをクリップボードにコピーします。または、最初からやり直す場合は、[**New recording (新規録音)**] を選択します。 1. コピーしたスクリプトを使用して Canary を作成するには、コピーしたスクリプトをレコーダー設計図のインラインエディタに貼り付けるか、Amazon S3 バケットに保存してそこからインポートします。 1. Canary をすぐに作成しない場合は、記録したスクリプトをファイルに保存できます。 ## CloudWatch Synthetics Recorder の既知の制限事項 Google Chrome 用 CloudWatch Synthetics Recorder には、現在、以下の制限があります。 + ID を持たない HTML 要素は、CSS セレクターを使用します。これは、後でウェブページの構造が変更された場合、Canary を壊す可能性があります。将来のバージョンのレコーダーでは、これに関するいくつかの設定オプション (data-id の使用など) を提供する予定です。 + レコーダーは、ダブルクリックやコピー/貼り付けなどのアクションをサポートしておらず、また、CMD\$10 などのキーの組み合わせもサポートしていません。 + ページに要素またはテキストが存在することを確認するには、ユーザーがスクリプトの生成後にアサーションを追加する必要があります。レコーダーでは、その要素に対してアクションを実行しない要素の検証をサポートしていません。これは、Canary ワークフロービルダーの「テキストの確認」または「要素の確認」オプションと同様です。私たちは、レコーダーの将来のバージョンでいくつかのアサーションサポートを追加する予定です。 + レコーダーは、記録が開始されたタブ内のすべてのアクションを記録します。ポップアップ (位置情報の追跡を許可する場合など) やポップアップから別のページへのナビゲーションは記録されません。 # Synthetics のランタイムバージョン Canary を作成または更新する際に、Canary の Synthetics ランタイムバージョンを選択します。Synthetics ランタイムは、スクリプトハンドラーを呼び出す Synthetics コードと、バンドルされた依存関係の Lambda レイヤーを組み合わせたものです。 CloudWatch Synthetics が現在サポートしているのは、Node.js、Python、または Java 言語を使用するランタイムです。サポート対象のフレームワークは、Puppeteer、Playwright、および Selenium です。 Synthetics ライブラリの最新の機能や更新プログラムを使用できるように、Canary の最新のランタイムバージョンを常に使用することをお勧めします。 **注意**: Canary を実行して新しいバージョンの Synthetics ランタイムを使用するたびに、Canary で使用されるすべての Synthetics ライブラリ関数も、Synthetics ランタイムでサポートされているものと同じバージョンの NodeJS に自動的に移されます。 **Topics** + [Java を使用するランタイムバージョン](CloudWatch_Synthetics_Library_Java.md) + [Node.js と Playwright を使用するランタイムバージョン](CloudWatch_Synthetics_Library_nodejs_playwright.md) + [Node.js と Puppeteer を使用するランタイムバージョン](CloudWatch_Synthetics_Library_nodejs_puppeteer.md) + [Python と Selenium Webdriver を使用するランタイムバージョン](CloudWatch_Synthetics_Library_python_selenium.md) + [Node.js を使用するランタイムバージョン](CloudWatch_Synthetics_Library_Nodejs.md) + [ランタイムバージョンサポートポリシー](CloudWatch_Synthetics_Runtime_Support_Policy.md) + [ランタイムバージョンの更新](CloudWatch_Synthetics_Runtime_Version_Update.md) # Java を使用するランタイムバージョン 次のセクションには、Java 用の CloudWatch Synthetics ランタイムバージョンに関する情報が含まれています。このランタイムにはブラウザやフレームワークは含まれません。 これらのランタイムバージョンの命名規則は `syn-language -majorversion.minorversion` です。 ## syn-java-1.0 **主な依存関係**: + AWS Lambda ランタイム Java 21 **特徴** + *CloudWatch Logs の統合* – CloudWatch Synthetics コンソールを使用してログをクエリおよびフィルタリングできます。各ログメッセージには一意の ` canaryRunId` が含まれているため、特定の Canary 実行のログを簡単に検索できます。 + *メトリクス* – Canary の実行成功率と実行時間を CloudWatch のメトリクスでモニタリングできます。Canary で問題が検出された場合に警告を出すようにアラームを設定することもできます。 + *Canary アーティファクト* - Canary の実行ごとに、その実行と各ステップに対応する詳細なレポートがアップロードされます。レポートには Amazon S3 からアクセスできます。 + *トレースのサポート* - X-Ray を介して Canary によって行われたすべてのリクエストのトレースを出力できます。各 Canary 実行は、1 つのトレース ID に関連付けられます。 # Node.js と Playwright を使用するランタイムバージョン 次のセクションには、Node.js と Playwright のための CloudWatch Synthetics ランタイムバージョンに関する情報が含まれています。Playwright は、ブラウザテスト用のオープンソースの自動化ライブラリです。Playwright の詳細については、「[https://playwright.dev/](https://playwright.dev)」を参照してください これらのランタイムバージョンの命名規則は `syn-language -framework-majorversion. minorversion` です。 ## syn-nodejs-playwright-6.0 **重要** Synthetics `syn-nodejs-playwright-5.1` 以降では、Synthetics ランタイムは新しい名前空間を使用します。新しい名前空間を使用するには、Canary スクリプトを移行させてください。レガシーの名前空間は今後のリリースで廃止される予定です。 @amzn/synthetics-playwright → @aws/synthetics-playwright **主な依存関係**: + AWS Lambda ランタイム Node.JS 22.x + Playwright バージョン 1.58.2 + Playwright/test バージョン 1.58.2 + Chromium バージョン 145.0.7632.77 + Firefox バージョン 146.0.1 **syn-nodejs-playwright-6.0 の変更** + セキュリティパッチを適用し、Playwright とブラウザのバージョンを更新しました。 詳細については次を参照してください: + [Playwright 変更ログ](https://playwright.dev/docs/release-notes) + [Playwright API リファレンス](https://playwright.dev/docs/api/class-playwright) ## Node.js と Playwright を使用する以前のランタイムバージョン Node.js および Playwright では、次の以前のランタイムバージョンが引き続きサポートされています。 ### syn-nodejs-playwright-5.1 **主な依存関係**: + AWS Lambda ランタイム Node.JS 22.x + Playwright バージョン 1.57.0 + Playwright/test バージョン 1.57.0 + Chromium バージョン 143.0.7499.169 + Firefox バージョン 142.0.1 **syn-nodejs-playwright-5.1 の変更** + Synthetics ランタイム名前空間の移行。 + タイプ定義は [npm レジストリ](https://www.npmjs.com/package/@aws/synthetics-playwright)で使用できます。タイプ定義パッケージのバージョンが Canary のランタイムバージョンと一致していることを確認してください。 詳細については次を参照してください: + [Playwright 変更ログ](https://playwright.dev/docs/release-notes) + [Playwright API リファレンス](https://playwright.dev/docs/api/class-playwright) ### syn-nodejs-playwright-5.0 **主な依存関係**: + AWS Lambda ランタイム Node.JS 22.x + Playwright バージョン 1.57.0 + Playwright/test バージョン 1.57.0 + Chromium バージョン 143.0.7499.4 + Firefox バージョン 142.0.1 **syn-nodejs-playwright-5.0 の変更** + セキュリティパッチを適用し、Playwright とブラウザのバージョンを更新しました。 詳細については次を参照してください: + [Playwright 変更ログ](https://playwright.dev/docs/release-notes) + [Playwright API リファレンス](https://playwright.dev/docs/api/class-playwright) ### syn-nodejs-playwright-4.0 **主な依存関係**: + AWS Lambda ランタイム Node.JS 22.x + Playwright バージョン 1.55.0 + Playwright/test バージョン 1.55.0 + Chromium バージョン 140.0.7339.16 + Firefox バージョン 141.0 **syn-nodejs-playwright-4.0 の変更** + セキュリティパッチを適用し、Playwright とブラウザのバージョンを更新しました。 詳細については次を参照してください: + [Playwright 変更ログ](https://playwright.dev/docs/release-notes) + [Playwright API リファレンス](https://playwright.dev/docs/api/class-playwright) ### syn-nodejs-playwright-3.0 **主な依存関係**: + AWS Lambda ランタイム Node.JS 20.x + Playwright バージョン 1.53.0 + Playwright/test バージョン 1.53.0 + Chromium バージョン 138.0.7204.168 **syn-nodejs-playwright-3.0 の変更** + マルチブラウザのサポート – nodejs puppeteer Canary を Firefox または Chrome で実行できるようになりました + ビジュアルモニタリングのサポート 詳細については次を参照してください: + [Playwright 変更ログ](https://playwright.dev/docs/release-notes) + [Playwright API リファレンス](https://playwright.dev/docs/api/class-playwright) ### syn-nodejs-playwright-2.0 **主な依存関係**: + AWS Lambda ランタイム Node.JS 20.x + Playwright バージョン 1.49.1 + Playwright/test バージョン 1.49.1 + Chromium バージョン 131.0.6778.264 **syn-nodejs-playwright-2.0 の変更** + HAR ファイル内の特定のリクエストの合計期間とタイミングの合計の不一致が修正されました。 + Canary のドライランに対応しているため、アドホック実行や Canary の安全な更新が可能です。 詳細については次を参照してください: + [Playwright 変更ログ](https://playwright.dev/docs/release-notes) + [Playwright API リファレンス](https://playwright.dev/docs/api/class-playwright) ### syn-nodejs-playwright-1.0 **主な依存関係**: + AWS Lambda ランタイム Node.JS 20.x + Playwright バージョン 1.44.1 + Playwright/test バージョン 1.44.1 + Chromium バージョン 126.0.6478.126 **機能** + **PlayWright のサポート** – Playwright 自動化フレームワークを使用して Canary スクリプトを作成できます。既存の Playwright スクリプトを Canary として実行し、AWS モニタリング機能で強化できます。 + **CloudWatch Logs の統合** – CloudWatch Synthetics コンソールを使用してログをクエリおよびフィルタリングできます。各ログメッセージには一意の `canaryRunId` が含まれているため、特定の Canary 実行のログを簡単に検索できます。 + **メトリクスと Canary アーティファクト** – CloudWatch メトリクスを通じて Canary 実行パスレートをモニタリングし、Canary が問題を検出したときに警告するようにアラームを設定できます。 + **スクリーンショットとステップの関連付け** – ネイティブの Playwright 機能を使用してスクリーンショットをキャプチャし、実行ごとに Canary スクリプトのステージを視覚化できます。スクリーンショットは自動的に Canary ステップに関連付けられ、Amazon S3 バケットにアップロードされます。 + **複数のタブ** – 複数のブラウザタブを開く Canary を作成し、各タブからスクリーンショットにアクセスできます。Synthetics では、マルチタブおよびマルチステップのユーザーワークフローを作成できます。 # Node.js と Puppeteer を使用するランタイムバージョン Node.js と Puppeteer の最初のランタイムバージョンには、`syn-1.0` という名前が付けられました。後のランタイムバージョンには、命名規則 `syn-language -majorversion.minorversion` があります。`syn-nodejs-puppeteer-3.0` 以降の命名規則は `syn- language-framework-majorversion .minorversion` です 追加の `-beta` サフィックスは、ランタイムバージョンが現在ベータプレビューリリースであることを示しています。 同じメジャーバージョン番号を持つランタイムバージョンには下位互換性があります。 Canary 内の Lambda コードは、最大メモリが 1 GB になるように設定されています。Canary の各実行は、設定されたタイムアウト値が経過するとタイムアウトします。Canary のタイムアウト値を指定しないと、CloudWatch は Canary の更新頻度に基づいてタイムアウト値を選択します。タイムアウト値を設定する場合、Lambda コールドスタートと canary インストルメンテーションの起動にかかる時間を許容するために 15 秒以上にします。 ## syn-nodejs-puppeteer-15.0 `syn-nodejs-puppeteer-15.0` は、Node.js および Puppeteer 用の最新の Synthetics ランタイムです。 **重要** Synthetics `syn-nodejs-puppeteer-13.1` 以降では、Synthetics ランタイムは新しい名前空間を使用します。新しい名前空間を使用するには、Canary スクリプトを移行させてください。レガシーの名前空間は今後のリリースで廃止される予定です。 Synthetics → @aws/synthetics-puppeteer SyntheticsLink → @aws/synthetics-link SyntheticsLogger → @aws/synthetics-logger SyntheticsLogHelper → @aws/synthetics-log-helper BrokenLinkCheckerReport → @aws/synthetics-broken-link-checker-report **重要** Synthetics ランタイム `syn-nodejs-puppeteer-11.0` 以降のバージョンでは、以下のステップレベルの設定オーバーライドのみがサポートされています: `screenshotOnStepStart` `screenshotOnStepSuccess` `screenshotOnStepFailure` `stepSuccessMetric` `stepDurationMetric` `continueOnStepFailure/continueOnHttpStepFailure` `stepsReport` 詳細については次を参照してください: + [Puppeteer 変更ログ](https://pptr.dev/CHANGELOG#24375-2026-02-19) + [Puppeteer API リファレンス](https://github.com/puppeteer/puppeteer/blob/puppeteer-v24.37.5/docs/api/index.md) **主な依存関係**: + Lambda ランタイム Node.js 22.x + Puppeteer-core バージョン 24.37.5 + Chromium バージョン 145.0.7632.77 + Firefox バージョン 147.0.4 **syn-nodejs-puppeteer-15.0 の変更** + セキュリティパッチを適用し、Puppeteer とブラウザのバージョンを更新しました。 + continueOnHttpStepFailure が受け入れられず、HTTP ステップの失敗が発生しても Canary の実行が誤って成功とマークされるバグを修正しました。 ## Node.js と Puppeteer を使用する以前のランタイムバージョン Node.js および Puppeteer では、次の以前のランタイムバージョンが引き続きサポートされています。 ### syn-nodejs-puppeteer-14.0 詳細については次を参照してください: + [Puppeteer 変更ログ](https://pptr.dev/CHANGELOG#24340-2025-12-19) + [Puppeteer API リファレンス](https://github.com/puppeteer/puppeteer/blob/puppeteer-v24.34.0/docs/api/index.md) **主な依存関係**: + Lambda ランタイム Node.js 22.x + Puppeteer-core バージョン 24.34.0 + Chromium バージョン 143.0.7499.169 + Firefox バージョン 146.x **syn-nodejs-puppeteer-14.0 の変更** + セキュリティパッチを適用し、Puppeteer とブラウザのバージョンを更新しました。 ### syn-nodejs-puppeteer-13.1 `syn-nodejs-puppeteer-13.1` は、Node.js および Puppeteer 用の最新の Synthetics ランタイムです。 詳細については次を参照してください: + [Puppeteer 変更ログ](https://pptr.dev/CHANGELOG#24250-2025-10-15) + [Puppeteer API リファレンス](https://github.com/puppeteer/puppeteer/blob/puppeteer-v24.2.0/docs/api/index.md) **主な依存関係**: + Lambda ランタイム Node.js 22.x + Puppeteer-core バージョン 24.25.0 + Chromium バージョン 142.0.7444.175 + Firefox バージョン 145.x **syn-nodejs-puppeteer-13.1 の変更** + Synthetics ランタイム名前空間の移行。 + タイプ定義は npm レジストリで使用できます。タイプ定義パッケージのバージョンが Canary のランタイムバージョンと一致していることを確認してください。 + [@aws/synthetics-puppeteer](https://www.npmjs.com/package/@aws/synthetics-puppeteer) + [@aws/synthetics-link](https://www.npmjs.com/package/@aws/synthetics-link) + [@aws/synthetics-broken-link-checker-report](https://www.npmjs.com/package/@aws/synthetics-broken-link-checker-report) + [@aws/synthetics-log-helper](https://www.npmjs.com/package/@aws/synthetics-log-helper) + [@aws/synthetics-logger](https://www.npmjs.com/package/@aws/synthetics-logger) ### syn-nodejs-puppeteer-13.0 詳細については次を参照してください: + [Puppeteer 変更ログ](https://pptr.dev/CHANGELOG#24250-2025-10-15) + [Puppeteer API リファレンス](https://github.com/puppeteer/puppeteer/blob/puppeteer-v24.2.0/docs/api/index.md) **主な依存関係**: + Lambda ランタイム Node.js 22.x + Puppeteer-core バージョン 24.25.0 + Chromium バージョン 142.0.7444.175 + Firefox バージョン 145.x **syn-nodejs-puppeteer-13.0 の変更** + セキュリティパッチを適用し、Puppeteer とブラウザのバージョンを更新しました。 + バグ修正 – 同時マップアクセスによる断続的なランタイム拡張機能のクラッシュの問題を修正 ### syn-nodejs-puppeteer-12.0 詳細については次を参照してください: + [Puppeteer 変更ログ](https://pptr.dev/CHANGELOG#24221-2025-09-23) + [Puppeteer API リファレンス](https://github.com/puppeteer/puppeteer/blob/puppeteer-v24.22.1/docs/api/index.md) **主な依存関係**: + Lambda ランタイム Node.js 22.x + Puppeteer-core バージョン 24.22.1 + Chromium バージョン 140.0.7339.185 + Firefox バージョン 143.0.1 **syn-nodejs-puppeteer-12.0 の変更** + セキュリティパッチを適用し、Puppeteer とブラウザのバージョンを更新しました。 + 制限付きヘッダー秘匿化のバグ修正 – 状況によっては、制限付きヘッダーが executeHttpStep() で秘匿化されない問題を修正しました。動作が Puppeteer 10.0 と整合するようになりました。 + includeResponseBody 設定のバグ修正 – HAR ファイル生成が特定の状況で includeResponseBody 設定を誤って適用する問題を修正しました。HAR では、設定時にレスポンス本文が確実に除外されるようになりました。 + リクエストキャプチャライフサイクルの修正 – 状況によっては、HTTP リクエストをキャプチャすることが原因で、リクエストが継続的に集約されることがある問題を修正しました。各ステップの実行後にレコーディングが正しく終了するようになりました。 ### syn-nodejs-puppeteer-11.0 詳細については次を参照してください: + [Puppeteer 変更ログ](https://pptr.dev/CHANGELOG) + [Puppeteer API リファレンス](https://github.com/puppeteer/puppeteer/blob/puppeteer-v24.2.0/docs/api/index.md) **主な依存関係**: + Lambda ランタイム Node.js 20.x + Puppeteer-core バージョン 24.15.0 + Chromium バージョン 138.0.7204.168 **syn-nodejs-puppeteer-11.0 の変更** + マルチブラウザのサポート – Node.js Puppeteer Canary を Firefox または Chrome で実行できるようになりました + パッケージ化の簡素化 – Node.js/node\$1modules ディレクトリ構造を使用せずに、スクリプトをルートに直接パッケージ化 + スクリーンショットの統合 – ネイティブの Puppeteer 関数を使用してスクリーンショットをキャプチャし、Canary スクリプトステージを視覚化します。Synthetics は、スクリーンショットを Canary ステップに自動的に関連付け、Amazon S3 にアップロードします。 + ログクエリの強化 – CloudWatch Insights コンソールを使用してログをクエリおよびフィルタリングします。各ログメッセージには、検索しやすい一意の `canaryRunId` が含まれています。 + 設定ファイルのサポート – synthetics.json ファイルを使用して Synthetics 設定を定義および更新します。スクリプトロジックから設定を分離することで、メンテナンスと再利用性が向上します + 複数のタブのサポート - 複数のブラウザタブを開き、各タブからスクリーンショットにアクセスする Canary を作成します。Synthetics でマルチタブとマルチステップのユーザーワークフローを構築する + セキュリティの修正内容 + ビジュアルモニタリングのバグ修正 + 設定可能なログレベルで構造化された JSON ログ記録のサポートを追加 – CloudWatch での解析とクエリを容易にするために、ログが JSON 形式で出力されるようになりました。ログレベルは、環境変数を通じて設定可能 (DEBUG、INFO、TRACE など) で、ユーザーはニーズに基づいて詳細を制御できます + ES 構文のサポート ### syn-nodejs-puppeteer-10.0 詳細については次を参照してください: + [Puppeteer 変更ログ](https://pptr.dev/CHANGELOG) + [Puppeteer API リファレンス](https://github.com/puppeteer/puppeteer/blob/puppeteer-v24.2.0/docs/api/index.md) **主な依存関係**: + Lambda ランタイム Node.js 20.x + Puppeteer-core バージョン 24.2.0 + Chromium バージョン 131.0.6778.264 **syn-nodejs-puppeteer-10.0 の変更** + ブラウザを閉じるのに時間がかかりすぎる問題に関連するバグを修正しました。 + Canary のドライランに対応しているため、アドホック実行や Canary の安全な更新が可能です。 ### syn-nodejs-puppeteer-9.1 **主な依存関係**: + Lambda ランタイム Node.js 20.x + Puppeteer-core バージョン 22.12.1 + Chromium バージョン 126.0.6478.126 **syn-nodejs-puppeteer-9.1 の変更** – HAR ファイル内の日付範囲と保留中のリクエストに関連するバグ修正を行いました。 ### syn-nodejs-puppeteer-9.0 **主な依存関係**: + Lambda ランタイム Node.js 20.x + Puppeteer-core バージョン 22.12.1 + Chromium バージョン 126.0.6478.126 **syn-nodejs-puppeteer-9.0 の変更** – ビジュアルモニタリング機能を有効にするバグ修正を行いました。 ### syn-nodejs-puppeteer-8.0 **警告** バグの影響で、`syn-nodejs-puppeteer-8.0` ランタイムは canary でのビジュアルモニタリングをサポートしていません。ビジュアルモニタリングを有効にするには、[syn-nodejs-puppeteer-9.0](#CloudWatch_Synthetics_runtimeversion-nodejs-puppeteer-9.0) へのアップグレードを行い、バグを修正します。 **重要** Lambda Node.js 18 以降のランタイムは AWS SDK for JavaScript V3 を使用しています。以前のランタイムから Canary を移行する必要がある場合は、GitHub の「[aws-sdk-js-v3 Migration Workshop](https://github.com/aws-samples/aws-sdk-js-v3-workshop)」の手順に従ってください。AWS SDK for JavaScript バージョン 3 の詳細については、[このブログ記事](https://aws.amazon.com/blogs/developer/modular-aws-sdk-for-javascript-is-now-generally-available/)を参照してください。 **主な依存関係**: + Lambda ランタイム Node.js 20.x + Puppeteer-core バージョン 22.10.0 + Chromium バージョン 125.0.6422.112 **syn-nodejs-puppeteer-8.0 の更新**: + **2 要素認証のサポート** + 一部のサービスクライアントが Node.js SDK V3 レスポンスでデータを失う問題に関連する**バグ修正**を行いました。 ## Node.js と Puppeteer の非推奨のランタイムバーション Node.js と Puppeteer では、次のランタイムが廃止されました。ランタイムの廃止日については、「[CloudWatch Synthetics ランタイムの廃止日](CloudWatch_Synthetics_Runtime_Support_Policy.md#runtime_deprecation_dates)」を参照してください。 ### syn-nodejs-puppeteer-7.0 **主な依存関係**: + Lambda ランタイム Node.js 18.x + Puppeteer-core バージョン 21.9.0 + Chromium バージョン 121.0.6167.139 **コードサイズ** このランタイムにパッケージ化できるコードと依存関係のサイズは 80 MB です。 **syn-nodejs-puppeteer-7.0 の更新**: + **Puppeteer と Chromium のバンドルされたライブラリのバージョンを更新** — Puppeteer と Chromium の依存関係が新しいバージョンに更新されました。 **重要** Puppeteer 19.7.0 から Puppeteer 21.9.0 に移行すると、テストとフィルターに関する重大な変更が導入されます。詳細については、「[puppeteer: v20.0.0](https://github.com/puppeteer/puppeteer/releases/tag/puppeteer-v20.0.0)」および「[puppeteer-core: v21.0.0](https://github.com/puppeteer/puppeteer/releases/tag/puppeteer-core-v21.0.0)」の「**BREAKING CHANGES**」セクションを参照してください。 **AWS SDK v3 への推奨アップグレード** Lambda nodejs18.x ランタイムは AWS SDK v2 をサポートしていません。AWS SDK v3 に移行することを強くお勧めします。 ### syn-nodejs-puppeteer-6.2 **主な依存関係**: + Lambda ランタイム Node.js 18.x + Puppeteer-core バージョン 19.7.0 + Chromium バージョン 111.0.5563.146 **syn-nodejs-puppeteer-6.2 の変更**: + **Chromium でバンドルされたライブラリの最新バージョン** + **エフェメラルストレージモニタリング** — このランタイムは、カスタマーアカウントにエフェメラルストレージモニタリングを追加します。 + **バグ修正** ### syn-nodejs-puppeteer-6.1 **主な依存関係**: + Lambda ランタイム Node.js 18.x + Puppeteer-core バージョン 19.7.0 + Chromium バージョン 111.0.5563.146 **syn-nodejs-puppeteer-6.1 の更新**: + **安定性の向上** - 自動再試行ロジックを追加し、断続的な Puppeteer 起動エラーに対処しました。 + **依存関係のアップグレード** – サードパーティ製の依存関係パッケージを一部アップグレードしました。 + **Amazon S3 へのアクセス権限のない canary** — Amazon S3 へのアクセス権限がなくても canary を実行可能といったバグを修正しました。Amazon S3 へのアクセス権限のないこうした canary では、スクリーンショットなどのアーティファクトを Amazon S3 にアップロードできなくなりました。canary のアクセス権限については、「[Canary に必要なロールとアクセス許可](CloudWatch_Synthetics_Canaries_CanaryPermissions.md)」で詳しく確認できます。 **重要** 重要: 付属する AWS SDK for JavaScript v2 の依存関係は削除され、将来のランタイムリリースでは AWS SDK for JavaScript v3 を使用するように更新されます。その場合は、canary コードリファレンスを更新します。または、付属する AWS SDK for JavaScript v2 依存関係をソースコードの zip ファイルに依存関係として追加することで、引き続き参照して使用することもできます。 ### syn-nodejs-puppeteer-6.0 **主な依存関係**: + Lambda ランタイム Node.js 18.x + Puppeteer-core バージョン 19.7.0 + Chromium バージョン 111.0.5563.146 **syn-nodejs-puppeteer-6.0 の更新**: + **依存関係のアップグレード** – Node.js の依存関係が 18.x にアップグレードされました。 + **インターセプトモードのサポート** – Puppeteer の協調インターセプトモードのサポートが、Synthetics Canary ランタイムライブラリに追加されました。 + **トレーシング動作の変更** – fetch と xhr リクエストのみをトレースし、リソースリクエストはトレースしないようにデフォルトの動作を変更しました。リソースリクエストのトレースは、`traceResourceRequests` オプションを設定することで有効化できます。 + **期間メトリクスの改良** – 今後 ` Duration` メトリクスでは、Canary でのアーティファクトのアップロード、スクリーンショットの撮影、CloudWatch メトリクスの生成に要する操作時間が除外されます。 `Duration` メトリクスの値は CloudWatch にレポートされ、Synthetics コンソールで確認することもできます。 + **バグ修正:** – Canary の実行中に Chromium がクラッシュした場合に生成されるコアダンプをクリーンアップしました。 **重要** 重要: 付属する AWS SDK for JavaScript v2 の依存関係は削除され、将来のランタイムリリースでは AWS SDK for JavaScript v3 を使用するように更新されます。その場合は、canary コードリファレンスを更新します。または、付属する AWS SDK for JavaScript v2 依存関係をソースコードの zip ファイルに依存関係として追加することで、引き続き参照して使用することもできます。 ### syn-nodejs-puppeteer-5.2 **主な依存関係**: + Lambda ランタイム Node.js 16.x + Puppeteer-core バージョン 19.7.0 + Chromium バージョン 111.0.5563.146 **syn-nodejs-puppeteer-5.2 の更新**: + **Chromium でバンドルされたライブラリの最新バージョン** + **バグ修正** ### syn-nodejs-puppeteer-5.1 **主な依存関係**: + Lambda ランタイム Node.js 16.x + Puppeteer-core バージョン 19.7.0 + Chromium バージョン 111.0.5563.146 **syn-nodejs-puppeteer-5.1 のバグ修正:** + **バグ修正** - このランタイムは、canary によって作成された HAR ファイルにリクエストヘッダーが欠落していた ` syn-nodejs-puppeteer-5.0` のバグを修正するものです。 ### syn-nodejs-puppeteer-5.0 **主な依存関係**: + Lambda ランタイム Node.js 16.x + Puppeteer-core バージョン 19.7.0 + Chromium バージョン 111.0.5563.146 **syn-nodejs-puppeteer-5.0 の更新**: + **依存関係のアップグレード** — Puppeteer-Core バージョンが 19.7.0 に更新されました。Chromium バージョンは 111.0.5563.146 にアップグレードされました。 **重要** 新しい Puppeteer-Core バージョンは、以前のバージョンのPuppeteerと完全に下位互換性があるわけではありません。このバージョンの変更の一部により、廃止された Puppeteer 関数を使用する既存の canary が機能しなくなる可能性があります。詳細については、[Puppeteer の変更ログ](https://github.com/puppeteer/puppeteer/releases?q=breaking&expanded=true)にある Puppeteer Core バージョン 19.7.0 から 6.0 の変更ログの重大な変更点をご覧ください。 ### syn-nodejs-puppeteer-4.0 **主な依存関係**: + Lambda ランタイム Node.js 16.x + Puppeteer-core バージョン 5.5.0 + Chromium バージョン 92.0.4512 **syn-nodejs-puppeteer-4.0 の更新**: + **依存関係のアップグレード** — Node.js の依存関係が 16.x にアップデートされました。 ### syn-nodejs-puppeteer-3.9 **重要** このランタイムバージョンは 2024 年 1 月 8 日に廃止されました。詳細については、「[ランタイムバージョンサポートポリシー](CloudWatch_Synthetics_Runtime_Support_Policy.md)」を参照してください。 **主な依存関係**: + Lambda ランタイム Node.js 14.x + Puppeteer-core バージョン 5.5.0 + Chromium バージョン 92.0.4512 **syn-nodejs-puppeteer-3.9 の更新**: + **依存関係のアップグレード** – 一部のサードパーティ依存関係パッケージをアップグレードします。 ### syn-nodejs-puppeteer-3.8 **重要** このランタイムバージョンは 2024 年 1 月 8 日に廃止されました。詳細については、「[ランタイムバージョンサポートポリシー](CloudWatch_Synthetics_Runtime_Support_Policy.md)」を参照してください。 **主な依存関係**: + Lambda ランタイム Node.js 14.x + Puppeteer-core バージョン 5.5.0 + Chromium バージョン 92.0.4512 **syn-nodejs-puppeteer-3.8 の更新**: + **プロファイルのクリーンアップ** — Chromium プロファイルが Canary を実行するたびにクリーンアップされるようになりました。 **syn-nodejs-puppeteer-3.8 のバグ修正:** + **バグ修正** — 以前は、ビジュアルモニターリングの Canary がスクリーンショットがない状態で実行すると誤動作することがありました。この問題が修正されました。 ### syn-nodejs-puppeteer-3.7 **重要** このランタイムバージョンは 2024 年 1 月 8 日に廃止されました。詳細については、「[ランタイムバージョンサポートポリシー](CloudWatch_Synthetics_Runtime_Support_Policy.md)」を参照してください。 **主な依存関係**: + Lambda ランタイム Node.js 14.x + Puppeteer-core バージョン 5.5.0 + Chromium バージョン 92.0.4512 **syn-nodejs-puppeteer-3.7 の更新**: + **ログ機能の機能強化** — タイムアウトやクラッシュした場合でも、Canary が Amazon S3 にログをアップロードします。 + **Lambda レイヤーのサイズを縮小** — Canary に使用される Lambda レイヤーのサイズが 34% 縮小されます。 **syn-nodejs-puppeteer-3.7 のバグ修正:** + **バグ修正** — 日本語、簡体字中国語、繁体字中国語のフォントが正しくレンダリングされます。 ### syn-nodejs-puppeteer-3.6 **重要** このランタイムバージョンは 2024 年 1 月 8 日に廃止されました。詳細については、「[ランタイムバージョンサポートポリシー](CloudWatch_Synthetics_Runtime_Support_Policy.md)」を参照してください。 **主な依存関係**: + Lambda ランタイム Node.js 14.x + Puppeteer-core バージョン 5.5.0 + Chromium バージョン 92.0.4512 **syn-nodejs-puppeteer-3.6 の更新**: + **より正確なタイムスタンプ** – canary 実行の開始時刻と終了時刻がミリ秒単位まで正確になりました。 ### syn-nodejs-puppeteer-3.5 **重要** このランタイムバージョンは 2024 年 1 月 8 日に廃止されました。詳細については、「[ランタイムバージョンサポートポリシー](CloudWatch_Synthetics_Runtime_Support_Policy.md)」を参照してください。 **主な依存関係**: + Lambda ランタイム Node.js 14.x + Puppeteer-core バージョン 5.5.0 + Chromium バージョン 92.0.4512 **syn-nodejs-puppeteer-3.5 の更新**: + **依存関係の更新** - このランタイムの新機能は、更新された依存関係のみです。 ### syn-nodejs-puppeteer-3.4 **重要** このランタイムバージョンは 2022 年 11 月 13 日に廃止されました。詳細については、「[ランタイムバージョンサポートポリシー](CloudWatch_Synthetics_Runtime_Support_Policy.md)」を参照してください。 **主な依存関係**: + Lambda ランタイム Node.js 12.x + Puppeteer-core バージョン 5.5.0 + Chromium バージョン 88.0.4298.0 **syn-nodejs-puppeteer-3.4 の更新**: + **カスタムハンドラー関数** — Canary スクリプトのためにカスタムハンドラー関数を使用できるようになりました。以前のランタイムでは、スクリプトエントリポイントに `.handler` が含まれている必要がありました。 Canary スクリプトを任意のフォルダに配置し、ハンドラーの一部としてフォルダ名を渡すこともできます。例えば、`MyFolder/MyScriptFile.functionname` はエントリポイントとして使用できます。 + **拡張された HAR ファイル情報** — Canary によって生成された HAR ファイルに、不正なリクエスト、保留中のリクエスト、および不完全なリクエストが表示されるようになりました。 ### syn-nodejs-puppeteer-3.3 **重要** このランタイムバージョンは 2022 年 11 月 13 日に廃止されました。詳細については、「[ランタイムバージョンサポートポリシー](CloudWatch_Synthetics_Runtime_Support_Policy.md)」を参照してください。 **主な依存関係**: + Lambda ランタイム Node.js 12.x + Puppeteer-core バージョン 5.5.0 + Chromium バージョン 88.0.4298.0 **syn-nodejs-puppeteer-3.3 の更新**: + **アーティファクト暗号化のその他のオプション**– Canary では、Amazon S3 に保存したアーティファクトの暗号化に AWS 管理キーを使用する代わりに、このバージョン以降のランタイムを使用します。使用するキーは、AWS KMS カスタマー管理のキーまたは Amazon S3 が管理するキーから選択できます。詳細については、「[Canary アーティファクトの暗号化](CloudWatch_Synthetics_artifact_encryption.md)」を参照してください。 ### syn-nodejs-puppeteer-3.2 **重要** このランタイムバージョンは 2022 年 11 月 13 日に廃止されました。詳細については、「[ランタイムバージョンサポートポリシー](CloudWatch_Synthetics_Runtime_Support_Policy.md)」を参照してください。 **主な依存関係**: + Lambda ランタイム Node.js 12.x + Puppeteer-core バージョン 5.5.0 + Chromium バージョン 88.0.4298.0 **syn-nodejs-puppeteer-3.2 の更新**: + **スクリーンショットによるビジュアルモニターリング**— これ以降のランタイムを使用する Canary は、実行中に撮影されたスクリーンショットと、同じスクリーンショットのベースラインバージョンを比較できます。スクリーンショットが指定されたパーセンテージのしきい値よりも大きく異なる場合、Canary は失敗します。詳細については、「[ビジュアルモニターリング](CloudWatch_Synthetics_Canaries_Library_Nodejs.md#CloudWatch_Synthetics_Library_SyntheticsLogger_VisualTesting)」または「[ビジュアルモニターリングの設計図](CloudWatch_Synthetics_Canaries_Blueprints.md#CloudWatch_Synthetics_Canaries_Blueprints_VisualTesting)」を参照してください。 + **機密データに関する新機能** Canary ログやレポートに機密データが表示されないようにすることができます。詳細については、「[SyntheticsLogHelper クラス](CloudWatch_Synthetics_Canaries_Library_Nodejs.md#CloudWatch_Synthetics_Library_SyntheticsLogHelper)」を参照してください。 + **廃止される関数** ` RequestResponseLogHelper`クラスは廃止され、他の新しい設定オプションに置き換えられます。詳細については、「[RequestResponseLogHelper クラス](CloudWatch_Synthetics_Canaries_Library_Nodejs.md#CloudWatch_Synthetics_Library_RequestResponseLogHelper)」を参照してください。 ### syn-nodejs-puppeteer-3.1 **重要** このランタイムバージョンは 2022 年 11 月 13 日に廃止されました。詳細については、「[ランタイムバージョンサポートポリシー](CloudWatch_Synthetics_Runtime_Support_Policy.md)」を参照してください。 **主な依存関係**: + Lambda ランタイム Node.js 12.x + Puppeteer-core バージョン 5.5.0 + Chromium バージョン 88.0.4298.0 **syn-nodejs-puppeteer-3.1 の更新**: + **CloudWatch メトリクスの設定機能** – このランタイムでは、不要なメトリクスを無効にできます。それ以外の場合、Canary は Canary 実行ごとにさまざまな CloudWatch メトリクスを発行します。 + **スクリーンショットリンク** – ステップの完了後に、スクリーンショットを Canary ステップにリンクできます。これを行うには、スクリーンショットを関連付けるステップの名前を使用して、**takeScreenshot** メソッドでスクリーンショットを作成します。例えば、ステップを実行し、待機時間を追加して、スクリーンショットを作成できます。 + **ハートビートモニターリングブループリントは複数の URL のモニターリングが可能** – CloudWatch コンソールでハートビートモニターリングブループリントを使用して複数の URL をモニターリングし、Canary 実行レポートのステップの概要で各 URL のステータス、期間、関連付けられたスクリーンショット、失敗の理由を確認できます。 ### syn-nodejs-puppeteer-3.0 **重要** このランタイムバージョンは 2022 年 11 月 13 日に廃止されました。詳細については、「[ランタイムバージョンサポートポリシー](CloudWatch_Synthetics_Runtime_Support_Policy.md)」を参照してください。 **主な依存関係**: + Lambda ランタイム Node.js 12.x + Puppeteer-core バージョン 5.5.0 + Chromium バージョン 88.0.4298.0 **syn-nodejs-puppeteer-3.0 の更新**: + **アップグレードされた依存関係** – このバージョンは Puppeteer バージョン 5.5.0、Node.js 12.x、および Chromium 88.0.4298.0 を使用します。 + **クロスリージョンバケットアクセス** – Canary がログファイル、スクリーンショット、HAR ファイルを保存するバケットとして、別のリージョンの S3 バケットを指定できるようになりました。 + **新しい関数が利用可能** – このバージョンでは、Canary 名と Syntheticsのランタイムバージョンを取得するためのライブラリ関数を追加します。 詳細については、「[Synthetics クラス](CloudWatch_Synthetics_Canaries_Library_Nodejs.md#CloudWatch_Synthetics_Library_Synthetics_Class_all)」を参照してください。 ### syn-nodejs-2.2 このセクションでは、`syn-nodejs-2.2` ランタイムバージョンについて説明します。 **重要** このランタイムバージョンは 2021 年 5 月 28 日に廃止されました。詳細については、「[ランタイムバージョンサポートポリシー](CloudWatch_Synthetics_Runtime_Support_Policy.md)」を参照してください。 **主な依存関係**: + Lambda ランタイム Node.js 10.x + Puppeteer-core バージョン 3.3.0 + Chromium バージョン 83.0.4103.0 **syn-nodejs-2.2 の変更**: + **HTTP ステップとして Canary をモニターリングする** – 単一の Canary で複数の API をテストできるようになりました。各 API は個別の HTTP ステップとしてテストされ、CloudWatch Synthetics はステップメトリクスと CloudWatch Synthetics のステップレポートを使用して各ステップのステータスをモニターリングします。CloudWatch Synthetics では、HTTP ステップごとに ` SuccessPercent` および `Duration` メトリクスが作成されます。 この機能は、**executeHttpStep(stepName, requestOptions, callback, stepConfig)** 関数によって実装されます。詳細については、「[executeHttpStep(stepName, requestOptions, [callback], [stepConfig])](CloudWatch_Synthetics_Canaries_Library_Nodejs.md#CloudWatch_Synthetics_Library_executeHttpStep)」を参照してください。 API Canary ブループリントは、この新しい機能を使用するように更新されました。 + **HTTP リクエストレポート** – リクエスト/レスポンスヘッダー、レスポンス本文、ステータスコード、エラーとパフォーマンスのタイミング、TCP 接続時間、TLS ハンドシェイク時間、最初のバイト時間、コンテンツ転送時間などの詳細を取得する HTTP リクエストレポートを表示できるようになりました。HTTP/HTTPS モジュールを内部で使用するすべての HTTP リクエストは、ここで取得されます。ヘッダーとレスポンス本文はデフォルトでは取得されませんが、設定オプションを設定することで有効にできます。 + **グローバルおよびステップレベルの設定** – CloudWatch Synthetics 設定は、Canary のすべてのステップに適用されるグローバルレベルで設定できます。特定のオプションを有効または無効にするために、設定キーと値のペアを渡して、これらの設定をステップレベルで上書きすることもできます。 詳細については、「[SyntheticsConfiguration クラス](CloudWatch_Synthetics_Canaries_Library_Nodejs.md#CloudWatch_Synthetics_Library_SyntheticsConfiguration)」を参照してください。 + **ステップ失敗時に続行する設定** – ステップが失敗した場合に、Canary の実行を続行できます。` executeHttpStep` 関数では、これはデフォルトでオンになっています。このオプションは、グローバルレベルで一度設定することも、ステップごとに個別に設定することもできます。 ### syn-nodejs-2.1 **重要** このランタイムバージョンは 2021 年 5 月 28 日に廃止されました。詳細については、「[ランタイムバージョンサポートポリシー](CloudWatch_Synthetics_Runtime_Support_Policy.md)」を参照してください。 **主な依存関係**: + Lambda ランタイム Node.js 10.x + Puppeteer-core バージョン 3.3.0 + Chromium バージョン 83.0.4103.0 **syn-nodejs-2.1 の更新**: + **設定可能なスクリーンショットの動作** – UI Canary によるスクリーンショットのキャプチャをオフにする機能を提供します。以前のバージョンのランタイムを使用する Canary の場合、UI Canary は常に各ステップの前後にスクリーンショットをキャプチャします。`syn-nodejs-2.1` の場合、これは設定可能です。スクリーンショットをオフにすると、Amazon S3 のストレージコストが削減され、HIPAA 規制に準拠しやすくなります。詳細については、「[SyntheticsConfiguration クラス](CloudWatch_Synthetics_Canaries_Library_Nodejs.md#CloudWatch_Synthetics_Library_SyntheticsConfiguration)」を参照してください。 + **Google Chrome 起動パラメータのカスタマイズ** Canary が Google Chrome ブラウザウィンドウを起動するときに使用する引数を設定できるようになりました。詳細については、「[launch(options)](CloudWatch_Synthetics_Canaries_Library_Nodejs.md#CloudWatch_Synthetics_Library_LaunchOptions)」を参照してください。 以前のバージョンの Canary ランタイムと比べて、syn-nodejs-2.0 以降を使用した場合の Canary の実行時間は少し増えることがあります。 ### syn-nodejs-2.0 **重要** このランタイムバージョンは 2021 年 5 月 28 日に廃止されました。詳細については、「[ランタイムバージョンサポートポリシー](CloudWatch_Synthetics_Runtime_Support_Policy.md)」を参照してください。 **主な依存関係**: + Lambda ランタイム Node.js 10.x + Puppeteer-core バージョン 3.3.0 + Chromium バージョン 83.0.4103.0 **syn-nodejs-2.0 の更新**: + **アップグレードされた依存関係** – このランタイムバージョンでは、Puppeteer-core バージョン 3.3.0 と Chromium バージョン 83.0.4103.0 を使用します + **X-RAY アクティブトレースのサポート。**Canary でトレースが有効になっている場合、ブラウザ、AWS SDK、または HTTP または HTTPS モジュールを使用するCanary によって行われたすべての呼び出しに対して Xx-Ray トレースが送信されます。トレースが有効になっている canary は、トレースが有効になっている他のサービスやアプリケーションにリクエストを送信していない場合でも、X-Ray トレースマップに表示されます。詳細については、「[Canary と X-Ray のトレース](CloudWatch_Synthetics_Canaries_tracing.md)」を参照してください。 + **Synthetics レポート** – Canary 実行ごとに、` SyntheticsReport-PASSED.json` または ` SyntheticsReport-FAILED.json` という名前のレポートが CloudWatch Synthetics により作成され、開始時刻、終了時刻、ステータス、エラーなどのデータが記録されます。また、Canary スクリプトの各ステップの PASSED/FAILED ステータス、および各ステップでキャプチャされたエラーとスクリーンショットも記録されます。 + **リンク切れチェッカーレポート** – このランタイムに含まれるリンク切れチェッカーの新しいバージョンでは、チェックされたリンク、ステータスコード、エラーの理由 (ある場合)、およびソースページとターゲットページのスクリーンショットを含むレポートが作成されます。 + **新しい CloudWatch メトリクス** – Synthetics は、`2xx`、`4xx`、`5xx`、および `RequestFailed` という名前のメトリクスを `CloudWatchSynthetics` 名前空間で公開します。これらのメトリクスには、Canary 実行の 200 番台、400 番台、500 番台、およびリクエストのエラー数が示されます。このランタイムバージョンでは、これらのメトリクスは UI Canary に対してのみレポートされ、API Canary に対してはレポートされません。また、ランタイムバージョン ` syn-nodejs-puppeteeer-2.2` で開始される API Canary についても報告されます。 + **ソート可能な HAR ファイル** – ステータスコード、リクエストサイズ、期間によって HAR ファイルをソートできるようになりました。 + **メトリクスのタイムスタンプ** – CloudWatch メトリクスは、Canary 実行終了時刻ではなく、Lambda 呼び出し時刻に基づいて報告されるようになりました。 **syn-nodejs-2.0 のバグ修正:** + Canary アーティファクトアップロードエラーが報告されない問題を修正しました。このようなエラーは、実行エラーとして表示されます。 + リダイレクトされたリクエスト (3xx) が誤ってエラーとして記録される問題を修正しました。 + スクリーンショットの番号が 0 から始まる問題を修正しました。今後は 1 から始まります。 + 中国語と日本語のフォントでスクリーンショットが文字化けする問題を修正しました。 以前のバージョンの Canary ランタイムと比べて、syn-nodejs-2.0 以降を使用した場合の Canary の実行時間は少し増えることがあります。 ### syn-nodejs-2.0-beta **重要** このランタイムバージョンは 2021 年 2 月 8 日に非推奨となりました。詳細については、「[ランタイムバージョンサポートポリシー](CloudWatch_Synthetics_Runtime_Support_Policy.md)」を参照してください。 **主な依存関係**: + Lambda ランタイム Node.js 10.x + Puppeteer-core バージョン 3.3.0 + Chromium バージョン 83.0.4103.0 **syn-nodejs-2.0-beta の変更**: + **アップグレードされた依存関係** – このランタイムバージョンでは、Puppeteer-core バージョン 3.3.0 と Chromium バージョン 83.0.4103.0 を使用します + **Synthetics レポート** – Canary 実行ごとに、` SyntheticsReport-PASSED.json` または ` SyntheticsReport-FAILED.json` という名前のレポートが CloudWatch Synthetics により作成され、開始時刻、終了時刻、ステータス、エラーなどのデータが記録されます。また、Canary スクリプトの各ステップの PASSED/FAILED ステータス、および各ステップでキャプチャされたエラーとスクリーンショットも記録されます。 + **リンク切れチェッカーレポート** – このランタイムに含まれるリンク切れチェッカーの新しいバージョンでは、チェックされたリンク、ステータスコード、エラーの理由 (ある場合)、およびソースページとターゲットページのスクリーンショットを含むレポートが作成されます。 + **新しい CloudWatch メトリクス** – Synthetics は、`2xx`、`4xx`、`5xx`、および `RequestFailed` という名前のメトリクスを `CloudWatchSynthetics` 名前空間で公開します。これらのメトリクスには、Canary 実行の 200 番台、400 番台、500 番台、およびリクエストのエラー数が示されます。これらのメトリクスは UI Canary に対してのみレポートされ、API Canary に対してはレポートされません。 + **ソート可能な HAR ファイル** – ステータスコード、リクエストサイズ、期間によって HAR ファイルをソートできるようになりました。 + **メトリクスのタイムスタンプ** – CloudWatch メトリクスは、Canary 実行終了時刻ではなく、Lambda 呼び出し時刻に基づいて報告されるようになりました。 **syn-nodejs-2.0-beta のバグ修正**: + Canary アーティファクトアップロードエラーが報告されない問題を修正しました。このようなエラーは、実行エラーとして表示されます。 + リダイレクトされたリクエスト (3xx) が誤ってエラーとして記録される問題を修正しました。 + スクリーンショットの番号が 0 から始まる問題を修正しました。今後は 1 から始まります。 + 中国語と日本語のフォントでスクリーンショットが文字化けする問題を修正しました。 ### syn-1.0 最初の Synthetics ランタイムバージョンは `syn-1.0` です。 **主な依存関係**: + Lambda ランタイム Node.js 10.x + Puppeteer-core バージョン 1.14.0 + Puppeteer-core 1.14.0 と一致する Chromium バージョン # Python と Selenium Webdriver を使用するランタイムバージョン 次のセクションには、Python と Selenium Webdriver のための CloudWatch Synthetics ランタイムバージョンに関する情報が含まれています。Selenium は、オープンソースのブラウザ自動化ツールです。Selenium の詳細については、[www.selenium.dev/](https://www.selenium.dev) をご参照ください Selenium フレームワーク上の Synthetics ランタイムでサポートされている機能とメソッドについては、「[UI Canary のみに適用される Python および Selenium ライブラリクラスおよび関数](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_Library_Python.html#CloudWatch_Synthetics_Library_Python_UIcanaries)」および「[Selenium API リファレンス](https://www.selenium.dev/selenium/docs/api/py/api.html)」を参照してください。 これらのランタイムバージョンの命名規則は `syn-language -framework-majorversion. minorversion` です。 ## syn-python-selenium-10.0 バージョン 10.0 は Python および Selenium 用の最新の CloudWatch Synthetics ランタイムです。 **主な依存関係**: + Python 3.11 + Selenium 4.32.0 + Chromium バージョン 145.0.7632.77 **syn-python-selenium-10.0 の変更** + セキュリティパッチを適用し、ブラウザのバージョンを更新しました。 詳細については次を参照してください: + [Selenium 変更ログ](https://www.selenium.dev/blog/2025/selenium-4-32-released) + [Selenium ドキュメント](https://www.selenium.dev/selenium/docs/api/py/api.html) ## Python および Selenium の以前のランタイムバージョン Python および Selenium では、次の以前のランタイムバージョンが引き続きサポートされています。 ### syn-python-selenium-9.0 **主な依存関係**: + Python 3.11 + Selenium 4.32.0 + Chromium バージョン 143.0.7499.169 **syn-python-selenium-9.0 の変更** + セキュリティパッチを適用し、ブラウザのバージョンを更新しました。 詳細については次を参照してください: + [Selenium 変更ログ](https://www.selenium.dev/blog/2025/selenium-4-32-released) + [Selenium ドキュメント](https://www.selenium.dev/selenium/docs/api/py/api.html) ### syn-python-selenium-8.0 バージョン 8.0 は Python および Selenium 用の最新の CloudWatch Synthetics ランタイムです。 **主な依存関係**: + Python 3.11 + Selenium 4.32.0 + Chromium バージョン 142.0.7444.175 **syn-python-selenium-8.0 の変更** + セキュリティパッチを適用し、Selenium とブラウザのバージョンを更新しました。 + HAR ネットワークリクエストの障害のログレベルを ERROR から INFO に変更しました。 詳細については次を参照してください: + [Selenium 変更ログ](https://www.selenium.dev/blog/2025/selenium-4-32-released) + [Selenium ドキュメント](https://www.selenium.dev/selenium/docs/api/py/api.html) ### syn-python-selenium-7.0 **主な依存関係**: + Python 3.11 + Selenium 4.32.0 + Chromium バージョン 138.0.7204.168 **syn-python-selenium-7.0 の変更** + セキュリティパッチを適用し、Selenium とブラウザのバージョンを更新しました。 詳細については次を参照してください: + [Selenium 変更ログ](https://www.selenium.dev/blog/2025/selenium-4-32-released) + [Selenium ドキュメント](https://www.selenium.dev/selenium/docs/api/py/api.html) ### syn-python-selenium-6.0 **主な依存関係**: + Python 3.11 + Selenium 4.21.0 + Chromium バージョン 131.0.6778.264 **syn-python-selenium-6.0 の変更** + Python 3.9 から Python 3.11 にアップグレード 詳細については次を参照してください: + [Selenium 変更ログ](https://www.selenium.dev/blog/2024/selenium-4-21-released/) + [Selenium ドキュメント](https://www.selenium.dev/selenium/docs/api/py/api.html) ### syn-python-selenium-5.1 **主な依存関係**: + Python 3.9 + Selenium 4.21.0 + Chromium バージョン 131.0.6778.264 **syn-python-selenium-5.1 の変更** + メトリクスの出力に関する軽微な更新。 + Canary のドライランに対応しているため、アドホック実行や Canary の安全な更新が可能です。 ### syn-python-selenium-5.0 **主な依存関係**: + Python 3.9 + Selenium 4.21.0 + Chromium バージョン 131.0.6778.264 **syn-python-selenium-5.0 の変更**: + ブラウザの起動に失敗した場合の自動再試行。 ### syn-python-selenium-4.1 **主な依存関係**: + Python 3.9 + Selenium 4.15.1 + Chromium バージョン 126.0.6478.126 **syn-python-selenium-4.1 の変更**: + **セキュリティの脆弱性に対処する** – このランタイムには、[CVE-2024-39689](https://nvd.nist.gov/vuln/detail/CVE-2024-39689) の脆弱性に対処するための更新があります。 ### syn-python-selenium-4.0 **主な依存関係**: + Python 3.9 + Selenium 4.15.1 + Chromium バージョン 126.0.6478.126 **syn-python-selenium-4.0 の変更**: + HAR パーサーにおけるログ記録のエラーの**バグ修正**。 ## Python および Selenium の非推奨のランタイムバージョン Python および Selenium では、次の以前のランタイムバージョンが廃止されました。ランタイムの廃止日については、「[CloudWatch Synthetics ランタイムの廃止日](CloudWatch_Synthetics_Runtime_Support_Policy.md#runtime_deprecation_dates)」を参照してください。 ### syn-python-selenium-3.0 **主な依存関係**: + Python 3.8 + Selenium 4.15.1 + Chromium バージョン 121.0.6167.139 **syn-python-selenium-3.0 の変更**: + **Chromium でバンドルされたライブラリのバージョンを更新** — Chromium の依存関係が新しいバージョンに更新されました。 ### syn-python-selenium-2.1 **主な依存関係**: + Python 3.8 + Selenium 4.15.1 + Chromium バージョン 111.0.5563.146 **syn-python-selenium-2.1 の変更**: + **Chromium でバンドルされたライブラリのバージョンを更新** — Chromium と Selenium の依存関係が新しいバージョンに更新されました。 ### syn-python-selenium-2.0 **主な依存関係**: + Python 3.8 + Selenium 4.10.0 + Chromium バージョン 111.0.5563.146 **syn-python-selenium-2.0 の変更**: + **依存関係を更新 — Chromium と Selenium の依存関係が新しいバージョンに更新されました**。 **syn-python-selenium-2.0 のバグ修正**: + タイムスタンプの追加 — **Canary ログにタイムスタンプが追加されました**。 + **セッションの再利用** — バグが修正され、Canary が前回実行したセッションを再利用できなくなりました。 ### syn-python-selenium-1.3 **主な依存関係**: + Python 3.8 + Selenium 3.141.0 + Chromium バージョン 92.0.4512.0 **syn-python-selenium-1.3 の変更**: + **より正確なタイムスタンプ** – canary 実行の開始時刻と終了時刻がミリ秒単位まで正確になりました。 ### syn-python-selenium-1.2 **主な依存関係**: + Python 3.8 + Selenium 3.141.0 + Chromium バージョン 92.0.4512.0 + **依存関係の更新** – このランタイムの新機能は、更新された依存関係のみです。 ### syn-python-selenium-1.1 **主な依存関係**: + Python 3.8 + Selenium 3.141.0 + Chromium バージョン 83.0.4103.0 **機能**: + **カスタムハンドラー関数** — Canary スクリプトのためにカスタムハンドラー関数を使用できるようになりました。以前のランタイムでは、スクリプトエントリポイントに `.handler` が含まれている必要がありました。 Canary スクリプトを任意のフォルダに配置し、ハンドラーの一部としてフォルダ名を渡すこともできます。例えば、`MyFolder/MyScriptFile.functionname` はエントリポイントとして使用できます。 + **メトリクスとステップ障害の設定を追加するための設定オプション** — これらのオプションは、Node.js Canary のランタイムで既に使用可能となっていました。詳細については、「[SyntheticsConfiguration クラス](CloudWatch_Synthetics_Canaries_Library_Python.md#CloudWatch_Synthetics_Library_SyntheticsConfiguration_Python)」を参照してください。 + **Chrome のカスタム引数** — ブラウザをシークレットモードで開くか、プロキシサーバー設定を渡すことができるようになりました。詳細については、「[Chrome()](CloudWatch_Synthetics_Canaries_Library_Python.md#CloudWatch_Synthetics_Library_Python_Chrome)」を参照してください。 + **クロスリージョンアーティファクトバケット** - Canary は、アーティファクトを別のリージョンの Amazon S3 バケットに保存できます。 + **`index.py` の問題の修正を含むバグ修正** — 以前のランタイムでは、` index.py` という名前の付いた Canary ファイルがライブラリファイルの名前と競合していたため、例外が発生していました。この問題は修正されました。 ### syn-python-selenium-1.0 **主な依存関係**: + Python 3.8 + Selenium 3.141.0 + Chromium バージョン 83.0.4103.0 **機能**: + **Selenium サポート** – Selenium テストフレームワークを使用して Canary スクリプトを記述できます。Selenium スクリプトを他の場所から CloudWatch Synthetics に最小限の変更で持ち込むことができ、AWS のサービスで動作します。 # Node.js を使用するランタイムバージョン 次のセクションには、Node.js 用の CloudWatch Synthetics ランタイムバージョンに関する情報が含まれています。このランタイムにはブラウザやフレームワークは含まれません。 これらのランタイムバージョンの命名規則は `syn-language -majorversion.minorversion` です。 ## syn-nodejs-4.1 **重要** Synthetics `syn-nodejs-3.1` 以降では、Synthetics ランタイムは新しい名前空間を使用します。新しい名前空間を使用するには、Canary スクリプトを移行させてください。レガシーの名前空間は今後のリリースで廃止される予定です。 @amzn/synthetics-core → @aws/synthetics-core **主な依存関係**: + AWS Lambda ランタイム Node.JS 22.x **syn-nodejs-4.1 の変更点** + `fast-xml-parser` を 5.5.7 にアップグレードして、次の CVE に対処します: + CVE-2026-25128 + CVE-2026-25896 + CVE-2026-26278 + CVE-2026-27942 + CVE-2026-33036 ## Node.js に対する過去のランタイムバージョン Node.js では、次の過去のランタイムバージョンが引き続きサポートされています。 ### syn-nodejs-4.0 **主な依存関係**: + AWS Lambda ランタイム Node.JS 22.x **syn-nodejs-4.0 の変更点** + セキュリティパッチを適用しました。 ### syn-nodejs-3.1 **重要** Synthetics `syn-nodejs-3.1` 以降では、Synthetics ランタイムは新しい名前空間を使用します。新しい名前空間を使用するには、Canary スクリプトを移行させてください。レガシーの名前空間は今後のリリースで廃止される予定です。 @amzn/synthetics-core → @aws/synthetics-core **主な依存関係**: + AWS Lambda ランタイム Node.JS 20.x **syn-nodejs-3.1 の変更点** + Synthetics ランタイム名前空間の移行。 + タイプ定義は [npm レジストリ](https://www.npmjs.com/package/@aws/synthetics-core)で使用できます。タイプ定義パッケージのバージョンが Canary のランタイムバージョンと一致していることを確認してください。 ### syn-nodejs-3.0 **主な依存関係**: + AWS Lambda ランタイム Node.JS 20.x **syn-nodejs-3.0 の変更点** + マルチチェックブループリントについては以下をサポートします。 # ランタイムバージョンサポートポリシー Synthetics ランタイムバージョンは、メンテナンスおよびセキュリティ更新プログラムに依存します。ランタイムバージョンのいずれかのコンポーネントがサポートされなくなると、その Synthetics ランタイムバージョンは非推奨となります。 非推奨のランタイムバージョンを使用して Canary を作成することはできません。非推奨のランタイムを使用する Canary が引き続き実行されます。これらの Canary は、停止、開始、削除することができます。サポートされているランタイムバージョンを使用するように Canary を更新することで、非推奨のランタイムバージョンを使用する既存の Canary を更新できます。 60 日以内に非推奨となる予定のランタイムを使用している Canary がある場合、CloudWatch Synthetics は通知メールをユーザーに送信します。最新のリリースに含まれる新しい機能、セキュリティ、および強化されたパフォーマンスを活用するために、Canary のランタイムは、サポートされているバージョンに更新することをお勧めします。 ## CloudWatch Synthetics ランタイムの廃止日 次の表に、非推奨の各 CloudWatch Synthetics ランタイムの廃止日を示します。 | ランタイムバージョン | 廃止日 | | --- | --- | | `syn-python-selenium-5.1` | 2026 年 2 月 3 日 | | `syn-python-selenium-5.0` | 2026 年 2 月 3 日 | | `syn-python-selenium-4.1` | 2026 年 2 月 3 日 | | `syn-python-selenium-4.0` | 2026 年 2 月 3 日 | | `syn-nodejs-puppeteer-7.0` | 2026 年 1 月 22 日 | | `syn-nodejs-puppeteer-6.2` | 2026 年 1 月 22 日 | | `syn-nodejs-puppeteer-5.2` | 2026 年 1 月 22 日 | | `syn-python-selenium-3.0` | 2026 年 1 月 22 日 | | `syn-python-selenium-2.1` | 2026 年 1 月 22 日 | | `syn-nodejs-puppeteer-6.1` | 2024 年 3 月 8 日 | | `syn-nodejs-puppeteer-6.0` | 2024 年 3 月 8 日 | | `syn-nodejs-puppeteer-5.1` | 2024 年 3 月 8 日 | | `syn-nodejs-puppeteer-5.0` | 2024 年 3 月 8 日 | | `syn-nodejs-puppeteer-4.0` | 2024 年 3 月 8 日 | | `syn-nodejs-puppeteer-3.9` | 2024 年 1 月 8 日 | | `syn-nodejs-puppeteer-3.8` | 2024 年 1 月 8 日 | | `syn-python-selenium-2.0` | 2024 年 3 月 8 日 | | `syn-python-selenium-1.3` | 2024 年 3 月 8 日 | | `syn-python-selenium-1.2` | 2024 年 3 月 8 日 | | `syn-python-selenium-1.1` | 2024 年 3 月 8 日 | | `syn-python-selenium-1.0` | 2024 年 3 月 8 日 | | `syn-nodejs-puppeteer-3.7` | 2024 年 1 月 8 日 | | `syn-nodejs-puppeteer-3.6` | 2024 年 1 月 8 日 | | `syn-nodejs-puppeteer-3.5` | 2024 年 1 月 8 日 | | `syn-nodejs-puppeteer-3.4` | 2022 年 11 月 13 日 | | `syn-nodejs-puppeteer-3.3` | 2022 年 11 月 13 日 | | `syn-nodejs-puppeteer-3.2` | 2022 年 11 月 13 日 | | `syn-nodejs-puppeteer-3.1` | 2022 年 11 月 13 日 | | `syn-nodejs-puppeteer-3.0` | 2022 年 11 月 13 日 | | `syn-nodejs-2.2` | 2021 年 5 月 28 日 | | `syn-nodejs-2.1` | 2021 年 5 月 28 日 | | `syn-nodejs-2.0` | 2021 年 5 月 28 日 | | `syn-nodejs-2.0-beta` | 2021 年 2 月 8 日 | | `syn-1.0` | 2021 年 5 月 28 日 | # ランタイムバージョンの更新 CloudWatch コンソールから、AWS CloudFormation、AWS CLI、または AWS SDK を使用して、Canary のランタイムバージョンを更新できます。CloudWatch コンソールを使用する場合であれば、一度に最大 5 つの Canary を更新できます。これには、一覧ページから対象の Canary を選択した上で、**[アクション]**、**[ランタイムの更新]** の順にクリックします。 更新を検証するには、更新をテストしてからランタイムの更新をコミットします。ランタイムのバージョンを更新する場合は、CloudWatch コンソールで **[ドライランを開始]** または **[検証して結果を保存]** オプションを選択して、設定の変更と併せて元の Canary のドライランを作成します。ドライランによってランタイム更新後に Canary が実行され、この更新が Canary にとって安全かどうかが検証されます。新しいランタイムバージョンの Canary を検証し終えたら、Canary のランタイムバージョンを更新します。詳細については、「[安全な Canary 更新の実行](performing-safe-canary-upgrades.md)」を参照してください。 CloudWatch コンソールを使用して Canary をクローンしてからランタイムバージョンを更新する方法で、更新を検証することもできます。これにより、元の Canary のクローンである別の Canary が作成されます。新しいランタイムバージョンの Canary を検証し終えたら、元の Canary のランタイムバージョンを更新した後で、クローンの Canary を削除します。 アップグレード用のスクリプトを使用すると、複数の Canary を更新することもできます。詳細については、「[Canary ランタイムアップグレード用スクリプト](#CloudWatch_Synthetics_Canaries_upgrade_script)」を参照してください。 Canary のアップグレードに失敗した場合は、「[失敗した Canary のトラブルシューティング](CloudWatch_Synthetics_Canaries_Troubleshoot.md)」を参照してください。 ## Canary ランタイムアップグレード用スクリプト Canary スクリプトを、サポートされているランタイムバージョンにアップグレードするには、次のスクリプトを使用します。 ``` const AWS = require('aws-sdk'); // You need to configure your AWS credentials and Region. // https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html // https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-region.html const synthetics = new AWS.Synthetics(); const DEFAULT_OPTIONS = { /** * The number of canaries to upgrade during a single run of this script. */ count: 10, /** * No canaries are upgraded unless force is specified. */ force: false }; /** * The number of milliseconds to sleep between GetCanary calls when * verifying that an update succeeded. */ const SLEEP_TIME = 5000; (async () => { try { const options = getOptions(); const versions = await getRuntimeVersions(); const canaries = await getAllCanaries(); const upgrades = canaries .filter(canary => !versions.isLatestVersion(canary.RuntimeVersion)) .map(canary => { return { Name: canary.Name, FromVersion: canary.RuntimeVersion, ToVersion: versions.getLatestVersion(canary.RuntimeVersion) }; }); if (options.force) { const promises = []; for (const upgrade of upgrades.slice(0, options.count)) { const promise = upgradeCanary(upgrade); promises.push(promise); // Sleep for 100 milliseconds to avoid throttling. await usleep(100); } const succeeded = []; const failed = []; for (let i = 0; i < upgrades.slice(0, options.count).length; i++) { const upgrade = upgrades[i]; const promise = promises[i]; try { await promise; console.log(`The update of ${upgrade.Name} succeeded.`); succeeded.push(upgrade.Name); } catch (e) { console.log(`The update of ${upgrade.Name} failed with error: ${e}`); failed.push({ Name: upgrade.Name, Reason: e }); } } if (succeeded.length) { console.group('The following canaries were upgraded successfully.'); for (const name of succeeded) { console.log(name); } console.groupEnd() } else { console.log('No canaries were upgraded successfully.'); } if (failed.length) { console.group('The following canaries were not upgraded successfully.'); for (const failure of failed) { console.log('\x1b[31m', `${failure.Name}: ${failure.Reason}`, '\x1b[0m'); } console.groupEnd(); } } else { console.log('Run with --force [--count ] to perform the first upgrades shown. The default value of is 10.') console.table(upgrades); } } catch (e) { console.error(e); } })(); function getOptions() { const force = getFlag('--force', DEFAULT_OPTIONS.force); const count = getOption('--count', DEFAULT_OPTIONS.count); return { force, count }; function getFlag(key, defaultValue) { return process.argv.includes(key) || defaultValue; } function getOption(key, defaultValue) { const index = process.argv.indexOf(key); if (index < 0) { return defaultValue; } const value = process.argv[index + 1]; if (typeof value === 'undefined' || value.startsWith('-')) { throw `The ${key} option requires a value.`; } return value; } } function getAllCanaries() { return new Promise((resolve, reject) => { const canaries = []; synthetics.describeCanaries().eachPage((err, data) => { if (err) { reject(err); } else { if (data === null) { resolve(canaries); } else { canaries.push(...data.Canaries); } } }); }); } function getRuntimeVersions() { return new Promise((resolve, reject) => { const jsVersions = []; const pythonVersions = []; synthetics.describeRuntimeVersions().eachPage((err, data) => { if (err) { reject(err); } else { if (data === null) { jsVersions.sort((a, b) => a.ReleaseDate - b.ReleaseDate); pythonVersions.sort((a, b) => a.ReleaseDate - b.ReleaseDate); resolve({ isLatestVersion(version) { const latest = this.getLatestVersion(version); return latest === version; }, getLatestVersion(version) { if (jsVersions.some(v => v.VersionName === version)) { return jsVersions[jsVersions.length - 1].VersionName; } else if (pythonVersions.some(v => v.VersionName === version)) { return pythonVersions[pythonVersions.length - 1].VersionName; } else { throw Error(`Unknown version ${version}`); } } }); } else { for (const version of data.RuntimeVersions) { if (version.VersionName === 'syn-1.0') { jsVersions.push(version); } else if (version.VersionName.startsWith('syn-nodejs-2.')) { jsVersions.push(version); } else if (version.VersionName.startsWith('syn-nodejs-puppeteer-')) { jsVersions.push(version); } else if (version.VersionName.startsWith('syn-python-selenium-')) { pythonVersions.push(version); } else { throw Error(`Unknown version ${version.VersionName}`); } } } } }); }); } async function upgradeCanary(upgrade) { console.log(`Upgrading canary ${upgrade.Name} from ${upgrade.FromVersion} to ${upgrade.ToVersion}`); await synthetics.updateCanary({ Name: upgrade.Name, RuntimeVersion: upgrade.ToVersion }).promise(); while (true) { await usleep(SLEEP_TIME); console.log(`Getting the state of canary ${upgrade.Name}`); const response = await synthetics.getCanary({ Name: upgrade.Name }).promise(); const state = response.Canary.Status.State; console.log(`The state of canary ${upgrade.Name} is ${state}`); if (state === 'ERROR' || response.Canary.Status.StateReason) { throw response.Canary.Status.StateReason; } if (state !== 'UPDATING') { return; } } } function usleep(ms) { return new Promise(resolve => setTimeout(resolve, ms)); } ``` # Canary スクリプトの作成 次のセクションでは、Canary スクリプトの作成方法と、Canary を他の AWS のサービス、外部依存関係、ライブラリと統合する方法について説明します。 **Topics** + [Java ランタイムを使用した Canary スクリプトの記述](Synthetics_WritingCanary_Java.md) + [Playwright ランタイムを使用した Node.js Canary スクリプトの記述](Synthetics_WritingCanary_Nodejs_Playwright.md) + [Puppeteer ランタイムを使用した Node.js Canary スクリプトの記述](CloudWatch_Synthetics_Canaries_WritingCanary_Nodejs_Pup.md) + [Python Canary スクリプトの記述](CloudWatch_Synthetics_Canaries_WritingCanary_Python.md) + [Node.js マルチチェックブループリントの JSON 設定の記述](CloudWatch_Synthetics_WritingCanary_Multichecks.md) # Java ランタイムを使用した Canary スクリプトの記述 **Topics** + [Canary の Java プロジェクトの構造](#Synthetics_canary_Java_package) + [Canary プロジェクトのパッケージ化](#Synthetics_canary_Java_package_canary) + [ハンドラー名](#Synthetics_canary_Java_handler) + [CloudWatch Synthetics の設定](#Synthetics_canary_Java_config) + [CloudWatch Synthetics 環境変数](#Synthetics_canary_Java_variables) ## Canary の Java プロジェクトの構造 Java で Canary を作成するには、記述したコードをコンパイルし、コンパイル後のアーティファクトを Synthetics にデプロイする必要があります。Java Lambda プロジェクトはさまざまな方法で初期化できます。例えば、IntelliJ IDEA や Visual Studio Code といった任意の IDE での標準 Java プロジェクト設定などを使用できます。または、必要なファイル構造を手動で作成することもできます。 Synthetics Java プロジェクトの一般的な構造は、次のとおりです。 ``` /project-root └ src └ main └ java └ canarypackage // name of package | └ ExampleCanary.java // Canary code file | └ other_supporting_classes - resources └ synthetics.json // Synthetics configuration file └ build.gradle OR pom.xml ``` Maven または Gradle を使用してプロジェクトを構築し、依存関係を管理できます。 上記の構造の `ExampleCanary` クラスは、Canary のエントリポイントまたはハンドラーです。 **Java Canary クラスの例** この例では、Canary が Lambda 環境変数 *TESTING\$1URL* に格納されている URL に対して、get リクエストを実行しています。Canary は Synthetics ランタイムのメソッドは使用しません。 ``` package canarypackage; import java.net.HttpURLConnection; import java.net.URL; // Handler value: canary.ExampleCanary::canaryCode public class ExampleCanary { public void canaryCode() throws Exception{ URL url = new URL(System.getenv("TESTING_URL")); HttpURLConnection con=(HttpURLConnection)url.openConnection(); con.setRequestMethod("GET"); con.setConnectTimeout(5000); con.setReadTimeout(5000); int status=con.getResponseCode(); if(status!=200){ throw new Exception("Failed to load " + url + ", status code: " + status); } } } ``` Synthetics のライブラリ関数 `executeStep` を使用して、Canary をモジュール化することを強くお勧めします。Canary は環境変数 URL1 および URL2 から取得した 2 つの URL に対して `get` 呼び出しを実行します。 **注記** `executeStep` の機能を使用するには、Canary のハンドラーメソッドで、次に示すようにタイプ Synthetics のパラメータを使用する必要があります。 ``` package canarypackage; import com.amazonaws.synthetics.Synthetics; import java.net.HttpURLConnection; import java.net.URL; // Handler value: canary.ExampleCanary::canaryCode public class ExampleCanary { public void canaryCode(Synthetics synthetics) throws Exception { createStep("Step1", synthetics, System.getenv("URL1")); createStep("Step2", synthetics, System.getenv("URL2")); return; } private void createStep(String stepName, Synthetics synthetics, String url) throws Exception{ synthetics.executeStep(stepName,()->{ URL obj=new URL(url); HttpURLConnection con=(HttpURLConnection)obj.openConnection(); con.setRequestMethod("GET"); con.setConnectTimeout(5000); con.setReadTimeout(5000); int status=con.getResponseCode(); if(status!=200){ throw new Exception("Failed to load" + url + "status code:" + status); } return null; }).get(); } } ``` ## Canary プロジェクトのパッケージ化 Synthetics は Java Canary のコードを *zip* 形式で受け入れます。Canary コードの zip は、Canary コード用のクラスファイル、サードパーティーの依存関係用の jar ファイル、Synthetics の設定ファイルで構成されます。 Synthetics Java の zip ファイルの一般的な構造は、次のとおりです。 ``` example-canary └ lib | └ //third party dependency jars └ java-canary.jar └ synthetics.json ``` 上記のプロジェクト構造からこの zip をビルドするには、gradle (build.gradle) または maven (pom.xml) を使用します。以下はその例です。 Synthetics ライブラリのコンパイル時の依存関係やインターフェイスについては、[aws-cloudwatch-synthetics-sdk-java](https://github.com/aws/aws-cloudwatch-synthetics-sdk-java/tree/main) の README を参照してください。 ``` plugins { id 'java' } repositories { mavenCentral() } dependencies { // Third party dependencies // example: implementation 'software.amazon.awssdk:s3:2.31.9' // Declares dependency on Synthetics interfaces for compiling only // Refer https://github.com/aws/aws-cloudwatch-synthetics-sdk-java for building from source. compileOnly 'software.amazon.synthetics:aws-cloudwatch-synthetics-sdk-java:1.0.0'} test { useJUnitPlatform() } // Build the zip to be used as Canary code. task buildZip(type: Zip) { archiveFileName.set("example-canary.zip") destinationDirectory.set(file("$buildDir")) from processResources into('lib') { from configurations.runtimeClasspath from(tasks.named("jar")) } from "src/main/java/resources/synthetics.json" doLast { println "Artifact written to: ${archiveFile.get().asFile.absolutePath}" } } java { toolchain { languageVersion = JavaLanguageVersion.of(21) } } tasks.named("build") { dependsOn "buildZip" } ``` ## ハンドラー名 ハンドラー名は Canary のエントリポイントです。Java ランタイムの場合、ハンドラーは次の形式になります。 ``` <>::<> // for above code: canarypackage.ExampleCanary::canaryCode ``` ## CloudWatch Synthetics の設定 Synthetics Java ランタイムの動作を設定するには、`synthetics.json` という名前のオプション JSON 設定ファイルを指定します。このファイルは、パッケージ化して zip パッケージのルートディレクトリに配置する必要があります。設定ファイルはオプションですが、設定ファイルを指定しない場合、または設定キーがない場合、CloudWatch はデフォルトを使用します。 サポートされている設定値とそのデフォルト値を次に示します。 ``` { "step": { "stepSuccessMetric": true, "stepDurationMetric": true, "continueOnStepFailure": false, "stepsReport": true }, "logging": { "logRequest": false, "logResponse": false }, "httpMetrics": { "metric_2xx": true, "metric_4xx": true, "metric_5xx": true, "aggregated2xxMetric": true, "aggregated4xxMetric": true, "aggregated5xxMetric": true }, "canaryMetrics": { "failedCanaryMetric": true, "aggregatedFailedCanaryMetric": true } } ``` **ステップ設定** + *continueOnStepFailure* – ステップが失敗した後もスクリプトを続行するかどうかを決定します。デフォルトは False です。 + *stepSuccessMetric* – ステップの ` SuccessPercent` メトリクスが出力されるかどうかを決定します。ステップの `SuccessPercent` メトリクスは、ステップが成功した場合は Canary 実行の値が *100* になり、ステップが失敗した場合は *0* になります。デフォルトは *True* です。 + *stepDurationMetric* – ステップの *Duration* メトリクスが出力されるかどうかを決定します。出力される *Duration* メトリクスは、ミリ秒単位でステップの経過時間を表します。デフォルトは *true* です。 **ロギング設定** CloudWatch Synthetics によって生成されたログに適用されます。リクエストログとレスポンスログの詳細度を制御します。 + *logRequest* - すべてのリクエストを Canary ログに記録するかどうかを指定します。デフォルトは False です。 + *logResponse* - すべてのレスポンスを Canary ログに記録するかどうかを指定します。デフォルトは False です。 **HTTP メトリクス設定** この Canary の CloudWatch Synthetics によって出力される、異なる HTTP ステータスコードを持つネットワークリクエストの数に関連するメトリクスの設定。 + *metric\$12xx* – この Canary の *2xx* メトリクスを (canaryName ディメンションと一緒に) 出力するかどうかを指定します。デフォルトは *True* です。 + *metric\$14xx* – この Canary の *4xx* メトリクスを (canaryName ディメンションと一緒に) 出力するかどうかを指定します。デフォルトは *True* です。 + *metric\$15xx* – この Canary の *5xx* メトリクスを (canaryName ディメンションと一緒に) 出力するかどうかを指定します。デフォルトは *True* です。 + *aggregated2xxMetric* – この Canary の *2xx* メトリクスを (canaryName ディメンションは出力せずに) 出力するかどうかを指定します。デフォルトは *True* です。 + *aggregated4xxMetric* – この Canary の *4xx* メトリクスを (canaryName ディメンションは出力せずに) 出力するかどうかを指定します。デフォルトは *True* です。 + *aggregated5xxMetric* – この Canary の *5xx* メトリクスを (canaryName ディメンションは出力せずに) 出力するかどうかを指定します。デフォルトは *True* です。 **Canary メトリクス設定** CloudWatch Synthetics によって出力される他のメトリクスの設定。 + *failedCanaryMetric* Network Access Analyzer でこの Canary の *Failed* メトリクスを (canaryName ディメンションと一緒に) 出力するかどうかを指定します。デフォルトは *True* です。 + *aggregatedFailedCanaryMetric* – この Canary の *Failed* メトリクスを (CanaryName ディメンションは出力せずに) 出力するかどうかを指定します。デフォルトは *True* です。 ## CloudWatch Synthetics 環境変数 環境変数を使用してログ記録レベルと形式を設定できます。 **ログ形式** CloudWatch Synthetics Java ランタイムは、Canary の実行ごとに CloudWatch ログを作成します。ログは、クエリしやすいように JSON 形式で書き込まれます。必要に応じて、ログ形式を *TEXT* に変更できます。 + *環境変数名* – CW\$1SYNTHETICS\$1LOG\$1FORMAT + *サポートされる値* – JSON、TEXT + *デフォルト* – JSON **ログレベル** + *環境変数名* – CW\$1SYNTHETICS\$1LOG\$1LEVEL + *サポートされる値* – TRACE、DEBUG、INFO、WARN、ERROR、FATAL + *デフォルト* – INFO 上記の環境変数以外に、Java ランタイム用のデフォルトの環境変数、`AWS_LAMBDA-EXEC_WRAPPER` 環境変数が関数に追加され、その値が `/opt/synthetics-otel-instrument` に設定されます。この環境変数によりテレメトリの関数の起動時動作が変更されます。この環境変数が既に存在する場合は、必要な値に設定されていることを確認してください。 # Playwright ランタイムを使用した Node.js Canary スクリプトの記述 **Topics** + [Playwright ランタイム用の Node.js Canary ファイルのパッケージ化](#Synthetics_canary_Nodejs_Playwright_package) + [既存の Playwright スクリプトを変更して CloudWatch Synthetics の Canary として使用する](#CloudWatch_Synthetics_canary_edit_Playwright_script) + [CloudWatch Synthetics の設定](#Synthetics_canary_configure_Playwright_script) ## Playwright ランタイム用の Node.js Canary ファイルのパッケージ化 Canary スクリプトは、Synthetics ハンドラーコードを含む `.js` (CommonJS 構文) または `.mjs` (ES 構文) ファイルと、コードが依存する追加のパッケージやモジュールで構成されます。ES (ECMAScript) 形式で作成されたスクリプトは、拡張子として .mjs を使用するか、"type": "module" フィールドが設定された package.json ファイルを含める必要があります。Node.js Puppeteer などの他のランタイムとは異なり、スクリプトを特定のフォルダ構造に保存する必要はありません。スクリプトを直接パッケージ化できます。任意の `zip` ユーティリティを使用して、ハンドラーファイルをルートに置く `.zip` ファイルを作成します。Canary スクリプトが Synthetics ランタイムに含まれていない追加のパッケージまたはモジュールに依存している場合は、これらの依存関係を `.zip` ファイルに追加できます。そのためには、`npm install` コマンドを実行して、関数に必要なライブラリを `node_modules` ディレクトリにインストールします。次の CLI コマンドの例では、`index.js` または `index.mjs` ファイル (Synthetics ハンドラー) とその依存関係を含む `my_deployment_package.zip` という名前の `.zip` ファイルを作成します。この例では、`npm` パッケージマネージャーを使用して依存関係をインストールします。 ``` ~/my_function ├── index.mjs ├── synthetics.json ├── myhelper-util.mjs └── node_modules ├── mydependency ``` プロジェクトフォルダの内容を含む `.zip` ファイルをルートに作成します。次の例で示すように `r` (再帰的) オプションを使用して、`zip` がサブフォルダを確実に圧縮するようにします。 ``` zip -r my_deployment_package.zip . ``` Synthetics 設定ファイルを追加して、CloudWatch Synthetics の動作を設定します。`synthetics.json` ファイルを作成し、エントリポイントまたはハンドラーファイルと同じパスに保存できます。 オプションで、選択したフォルダ構造にエントリポイントファイルを保存することもできます。ただし、フォルダパスがハンドラー名で指定されていることを確認してください。 **ハンドラー名** スクリプトのエントリポイント (ハンドラー) のファイル名に一致するように、Canary のスクリプトのエントリポイントを ` myCanaryFilename.functionName` として設定します。オプションで Canary を ` myFolder/my_canary_filename.mjs` などの別のフォルダに保存できます。別のフォルダに保存する場合は、スクリプトエントリポイントでそのパスを指定します (` myFolder/my_canary_filename.functionName` など)。 ## 既存の Playwright スクリプトを変更して CloudWatch Synthetics の Canary として使用する Node.js と Playwright の既存のスクリプトを編集して Canary として使用できます。Playwright の詳細については、「[Playwright ライブラリ](https://playwright.dev/docs/api/class-playwright)」のドキュメントを参照してください。 ファイル ` exampleCanary.mjs` に保存されている次の Playwright スクリプトを使用できます。 ``` import { chromium } from 'playwright'; import { expect } from '@playwright/test'; const browser = await chromium.launch(); const page = await browser.newPage(); await page.goto('https://example.com', {timeout: 30000}); await page.screenshot({path: 'example-home.png'}); const title = await page.title(); expect(title).toEqual("Example Domain"); await browser.close(); ``` 次のステップを実行してスクリプトを変換します。 1. `handler` 関数を作成してエクスポートします。このハンドラーは、スクリプトのエントリポイント関数です。ハンドラー関数には任意の名前を選択できますが、スクリプトで使用される関数は Canary ハンドラーと同じである必要があります。スクリプト名が `exampleCanary.mjs` で、ハンドラ関数名が `myhandler` の場合、Canary ハンドラの名前は `exampleCanary.myhandler` になります。次の例では、ハンドラー関数名は `handler` です。 ``` exports.handler = async () => { // Your script here }; ``` 1. `Synthetics Playwright module` を依存関係としてインポートします。 ``` import { synthetics } from '@aws/synthetics-playwright'; ``` 1. Synthetics `Launch` 関数を使用してブラウザを起動します。 ``` const browser = await synthetics.launch(); ``` 1. Synthetics `newPage` 関数を使用して新しい Playwright ページを作成します。 ``` const page = await synthetics.newPage(); ``` これで、スクリプトを Synthetics の Canary として実行できるようになりました。更新されたスクリプトは次のとおりです。 **ES6 形式で更新されたスクリプト** `.mjs` 拡張子を付けて保存されたスクリプトファイル。 ``` import { synthetics } from '@aws/synthetics-playwright'; import { expect } from '@playwright/test'; export const handler = async (event, context) => { try { // Launch a browser const browser = await synthetics.launch(); // Create a new page const page = await synthetics.newPage(browser); // Navigate to a website await page.goto('https://www.example.com', {timeout: 30000}); // Take screenshot await page.screenshot({ path: '/tmp/example.png' }); // Verify the page title const title = await page.title(); expect(title).toEqual("Example Domain"); } finally { // Ensure browser is closed await synthetics.close(); } }; ``` **CommonJS 形式で更新されたスクリプト** `.js` 拡張子を付けて保存されたスクリプトファイル。 ``` const { synthetics } = require('@aws/synthetics-playwright'); const { expect } = require('@playwright/test'); exports.handler = async (event) => { try { const browser = await synthetics.launch(); const page = await synthetics.newPage(browser); await page.goto('https://www.example.com', {timeout: 30000}); await page.screenshot({ path: '/tmp/example.png' }); const title = await page.title(); expect(title).toEqual("Example Domain"); } finally { await synthetics.close(); } }; ``` ## CloudWatch Synthetics の設定 Synthetics Playwright ランタイムの動作を設定するには、`synthetics.json` という名前のオプション JSON 設定ファイルを指定します。このファイルは、ハンドラーファイルと同じ場所にパッケージ化する必要があります。設定ファイルはオプションですが、設定ファイルを指定しない場合、または設定キーがない場合、CloudWatch はデフォルトを引き受けます。 **設定ファイルのパッケージ化** サポートされている設定値とそのデフォルト値を次に示します。 ``` { "step": { "screenshotOnStepStart": false, "screenshotOnStepSuccess": false, "screenshotOnStepFailure": false, "stepSuccessMetric": true, "stepDurationMetric": true, "continueOnStepFailure": true, "stepsReport": true }, "report": { "includeRequestHeaders": true, "includeResponseHeaders": true, "includeUrlPassword": false, "includeRequestBody": true, "includeResponseBody": true, "restrictedHeaders": ['x-amz-security-token', 'Authorization'], // Value of these headers is redacted from logs and reports "restrictedUrlParameters": ['Session', 'SigninToken'] // Values of these url parameters are redacted from logs and reports }, "logging": { "logRequest": false, "logResponse": false, "logResponseBody": false, "logRequestBody": false, "logRequestHeaders": false, "logResponseHeaders": false }, "httpMetrics": { "metric_2xx": true, "metric_4xx": true, "metric_5xx": true, "failedRequestsMetric": true, "aggregatedFailedRequestsMetric": true, "aggregated2xxMetric": true, "aggregated4xxMetric": true, "aggregated5xxMetric": true }, "canaryMetrics": { "failedCanaryMetric": true, "aggregatedFailedCanaryMetric": true }, "userAgent": "", "har": true } ``` **ステップ設定** + `screenshotOnStepStart` – ステップの開始前に Synthetics がスクリーンショットをキャプチャするかどうかを決定します。デフォルトは `true` です。 + `screenshotOnStepSuccess` – ステップが成功した後に Synthetics がスクリーンショットをキャプチャするかどうかを決定します。デフォルトは `true` です。 + `screenshotOnStepFailure` – ステップが失敗した後に Synthetics がスクリーンショットをキャプチャするかどうかを決定します。デフォルトは `true` です。 + `continueOnStepFailure` – ステップが失敗した後もスクリプトを続行するかどうかを決定します。デフォルトは `false` です。 + `stepSuccessMetric` - ステップの ` SuccessPercent` メトリクスが出力されるかどうかを決定します。ステップの `SuccessPercent` メトリクスは、ステップが成功した場合は Canary 実行の `100` となり、ステップが失敗した場合は `0` となります。デフォルトは `true` です。 + `stepDurationMetric` – ステップの `Duration` メトリクスが出力されるかどうかを決定します。`Duration` メトリクスは、ステップの実行時間としてミリ秒単位で出力されます。デフォルトは `true` です。 **レポート設定** HAR ファイルや Synthetics ステップレポートなど、CloudWatch Synthetics によって生成されたすべてのレポートが含まれます。機密データの編集フィールド `restrictedHeaders` と `restrictedUrlParameters` は、Synthetics によって生成されたログにも適用されます。 + `includeRequestHeaders` – レポートにリクエストヘッダーを含めるかどうか。デフォルトは `false` です。 + `includeResponseHeaders` – レポートにレスポンスヘッダーを含めるかどうか。デフォルトは `false` です。 + `includeUrlPassword` — URL に表示されるパスワードを含めるかどうか。デフォルトでは、機密データの開示を防ぐために、URL に表示されるパスワードはログとレポートで墨消しされます。デフォルトは `false` です。 + `includeRequestBody` – レポートにリクエスト本文を含めるかどうか。デフォルトは `false` です。 + `includeResponseBody` – レポートにレスポンス本文を含めるかどうか。デフォルトは `false` です。 + `restrictedHeaders` – ヘッダーが含まれている場合に無視するヘッダー値のリスト。これは、リクエストヘッダーとレスポンスヘッダーの両方に適用されます。例えば、`includeRequestHeaders` を true として、`restrictedHeaders` を `['Authorization']` として渡すことで、認証情報を非表示にできます。 + `restrictedUrlParameters` — 編集する URL パスまたはクエリパラメータのリスト。これは、ログ、レポート、エラーに表示される URL に適用されます。パラメータ名では大文字と小文字が区別されます。アスタリスク (`*`) を値として渡すと、すべての URL パスおよびクエリパラメータ値を墨消しできます。デフォルトは、空白の配列です。 + `har` – HTTP アーカイブ (HAR) を生成するかどうかを決定します。デフォルトは `true` です。 以下はレポート設定ファイルの例です。 ``` "includeRequestHeaders": true, "includeResponseHeaders": true, "includeUrlPassword": false, "includeRequestBody": true, "includeResponseBody": true, "restrictedHeaders": ['x-amz-security-token', 'Authorization'], // Value of these headers is redacted from logs and reports "restrictedUrlParameters": ['Session', 'SigninToken'] // Values of these URL parameters are redacted from logs and reports ``` **ロギング設定** CloudWatch Synthetics によって生成されたログに適用されます。リクエストログとレスポンスログの詳細度を制御します。 + `logRequest` - すべてのリクエストを Canary ログに記録するかどうか。UI Canary の場合、ブラウザから送信された各リクエストがログに記録されます。デフォルトは ` false` です。 + `logResponse` - すべてのレスポンスを Canary ログに記録するかどうか。UI Canary の場合、ブラウザが受信したすべてのレスポンスをログに記録します。デフォルトは ` false` です。 + `logRequestBody` -リクエスト本文を Canary ログのリクエストとともに記録するかどうか。この設定は、`logRequest` が true である場合にのみ適用されます。デフォルトは `false` です。 + `logResponseBody` -リクエスト本文を Canary ログのリクエストとともに記録するかどうか。この設定は、`logResponse` が true である場合にのみ適用されます。デフォルトは `false` です。 + `logRequestHeaders` -リクエストヘッダーを Canary ログのリクエストとともに記録するかどうか。この設定は、` logRequest` が true である場合にのみ適用されます。デフォルトは `false` です。 + `logResponseHeaders` -レスポンスヘッダーを Canary ログのレスポンスとともに記録するかどうか。この設定は、` logResponse` が true である場合にのみ適用されます。デフォルトは `false` です。 **HTTP メトリクス設定** この Canary の CloudWatch Synthetics によって出力される、異なる HTTP ステータスコードを持つネットワークリクエストの数に関連するメトリクスの設定。 + `metric_2xx` – この Canary の `2xx` メトリクス (`CanaryName` ディメンションを含む) を出力するかどうか。デフォルトは ` true` です。 + `metric_4xx` – この Canary の `4xx` メトリクス (`CanaryName` ディメンションを含む) を出力するかどうか。デフォルトは ` true` です。 + `metric_5xx` – この Canary の `5xx` メトリクス (`CanaryName` ディメンションを含む) を出力するかどうか。デフォルトは ` true` です。 + `failedRequestsMetric` – この Canary の ` failedRequests` メトリクス (`CanaryName` ディメンションを含む) を出力するかどうか。デフォルトは `true` です。 + `aggregatedFailedRequestsMetric` – この Canary の ` failedRequests` メトリクス (`CanaryName` ディメンションを含まない) を出力するかどうか。デフォルトは `true` です。 + `aggregated2xxMetric` – この Canary の `2xx` メトリクス (`CanaryName` ディメンションを含まない) を出力するかどうか。デフォルトは `true` です。 + `aggregated4xxMetric` – この Canary の `4xx` メトリクス (`CanaryName` ディメンションを含まない) を出力するかどうか。デフォルトは `true` です。 + `aggregated5xxMetric` – この Canary の `5xx` メトリクス (`CanaryName` ディメンションを含まない) を出力するかどうか。デフォルトは `true` です。 **Canary メトリクス設定** CloudWatch Synthetics によって出力される他のメトリクスの設定。 + `failedCanaryMetric` – この Canary の `Failed` メトリクス (`CanaryName` ディメンションを含む) を出力するかどうか。デフォルトは ` true` です。 + `aggregatedFailedCanaryMetric` – この Canary の ` Failed` メトリクス (`CanaryName` ディメンションを含まない) を出力するかどうか。デフォルトは `true` です。 **その他の設定** + `userAgent` – ユーザーエージェントに追加する文字列。ユーザーエージェントは、リクエストヘッダーに含まれる文字列であり、ヘッドレスブラウザの使用時にアクセスしたウェブサイトに対してブラウザを識別します。CloudWatch Synthetics は `CloudWatchSynthetics/canary-arn to the user agent` を自動的に追加します。指定された設定は、生成されたユーザーエージェントに追加されます。追加するデフォルトのユーザーエージェント値は空の文字列 (`""`) です。 ### CloudWatch Synthetics 環境変数 環境変数を使用してログ記録レベルと形式を設定します。 **ログ形式** CloudWatch Synthetics Playwright ランタイムは、Canary の実行ごとに CloudWatch ログを作成します。ログは、クエリしやすいように JSON 形式で書き込まれます。必要に応じて、ログ形式を `TEXT` に変更できます。 + `Environment variable name` – CW\$1SYNTHETICS\$1LOG\$1FORMAT + `Supported values` – JSON、テキスト + `Default` – JSON **ログレベル** `Debug` モードを有効にすると詳細度は高くなりますが、トラブルシューティングに役立ちます。 + `Environment variable name` – CW\$1SYNTHETICS\$1LOG\$1LEVEL + `Supported values` – TRACE、DEBUG、INFO、WARN、ERROR、FATAL + `Default` – INFO # Puppeteer ランタイムを使用した Node.js Canary スクリプトの記述 **Topics** + [CloudWatch Synthetics Canary を最初から作成する](#CloudWatch_Synthetics_Canaries_write_from_scratch) + [Node.js Canary ファイルのパッケージング](#CloudWatch_Synthetics_Canaries_package) + [既存の Puppeteer スクリプトを変更して Synthetics の Canary として使用する](#CloudWatch_Synthetics_Canaries_modify_puppeteer_script) + [環境変数](#CloudWatch_Synthetics_Environment_Variables) + [Canary と他の AWS のサービスとの統合](#CloudWatch_Synthetics_Canaries_AWS_integrate) + [Canary に静的 IP アドレスの使用を強制する](#CloudWatch_Synthetics_Canaries_staticIP) ## CloudWatch Synthetics Canary を最初から作成する 次の例は、Synthetics の最小の Canary スクリプトを示しています。このスクリプトは、合格して正常な実行となり、文字列を返します。不合格となる Canary の例を確認するには、`let fail = false;` を `let fail = true;` に変更します。 Canary スクリプトのエントリポイント関数を定義する必要があります。Canary の `ArtifactS3Location` として指定した先の Amazon S3 にファイルがアップロードされる方法を確認するには、これらのファイルを `/tmp` フォルダに作成します。Canary アーティファクトは書き込み可能な唯一のディレクトリであるため、すべて `/tmp` に保存する必要があります。スクリプトによって作成されたスクリーンショットやその他のファイルについては、スクリーンショットパスが `/tmp` に設定されていることを確認してください。Synthetics は、` /tmp` のファイルを S3 バケットに自動的にアップロードします。 ``` /tmp/ ``` スクリプトを実行すると、合格/不合格のステータスと所要時間のメトリクスが CloudWatch に発行され、`/tmp` の下のファイルが S3 にアップロードされます。 ``` const basicCustomEntryPoint = async function () { // Insert your code here // Perform multi-step pass/fail check // Log decisions made and results to /tmp // Be sure to wait for all your code paths to complete // before returning control back to Synthetics. // In that way, your canary will not finish and report success // before your code has finished executing // Throw to fail, return to succeed let fail = false; if (fail) { throw "Failed basicCanary check."; } return "Successfully completed basicCanary checks."; }; exports.handler = async () => { return await basicCustomEntryPoint(); }; ``` 次に、AWS SDK を使用して、Synthetics のログ記録を使用して呼び出しを行うようにスクリプトが拡張されます。デモのために、このスクリプトは Amazon DynamoDB クライアントを作成し、DynamoDB listTables API を呼び出します。リクエストに対するレスポンスを記録し、リクエストが成功したかどうかに応じて合格または不合格を記録します。 ``` const log = require('@aws/synthetics-logger'); const AWS = require('aws-sdk'); // Require any dependencies that your script needs // Bundle additional files and dependencies into a .zip file with folder structure // nodejs/node_modules/additional files and folders const basicCustomEntryPoint = async function () { log.info("Starting DynamoDB:listTables canary."); let dynamodb = new AWS.DynamoDB(); var params = {}; let request = await dynamodb.listTables(params); try { let response = await request.promise(); log.info("listTables response: " + JSON.stringify(response)); } catch (err) { log.error("listTables error: " + JSON.stringify(err), err.stack); throw err; } return "Successfully completed DynamoDB:listTables canary."; }; exports.handler = async () => { return await basicCustomEntryPoint(); }; ``` ## Node.js Canary ファイルのパッケージング **syn-nodejs-puppeteer-11.0 以降の場合** 古いパッケージング構造 (syn-nodejs-puppeteer-10.0 以前) は、新しいバージョンでも引き続きサポートされています。 以下のいずれかのオプションを使用してスクリプトを作成します。 + .js ファイル (CommonJS 構文) + .mjs ファイル (ES モジュール構文) ES モジュールの場合は、以下のいずれかのオプションを使用します。 + .js ファイル (CommonJS 構文) + .mjs ファイル (ES モジュール構文) パッケージ構造は以下のとおりです。 + ルートレベルのハンドラーファイル (index.js/index.mjs) + オプションの設定ファイル (synthetics.json) + node\$1modules の追加依存関係 (必要な場合) パッケージング構造の例: ``` my_function/ ├── index.mjs ├── synthetics.json ├── helper-utils.mjs └── node_modules/ └── dependencies ``` パッケージ化するには、以下のステップに従います。 1. 依存関係 (存在する場合) をインストールします。 ``` npm install ``` 1. .zip パッケージを作成します。 ``` zip -r my_deployment_package.zip ``` **syn-nodejs-puppeteer-11.0 以下の場合** Amazon S3 を使用する場合は、以下の構造が必要です。 ``` nodejs/ └── node_modules/ └── myCanaryFilename.js ``` **syn-nodejs-puppeteer-3.4\$1 でオプションのサブフォルダサポートを追加するには:** ``` nodejs/ └── node_modules/ └── myFolder/ └── myCanaryFilename.js ``` **注記** 設定のハンドラーパスは、ファイルの場所と一致する必要があります。 **ハンドラー名** スクリプトのエントリポイント (ハンドラー) のファイル名に一致するように、Canary のスクリプトのエントリポイントを ` myCanaryFilename.functionName` として設定します。`syn-nodejs-puppeteer-3.4` より前のランタイムを使用している場合は、`functionName` は `handler` である必要があります。` syn-nodejs-puppeteer-3.4` 以降を使用している場合、ハンドラーとして任意の関数名を選択できます。`syn-nodejs-puppeteer-3.4` 以降を使用している場合、オプションで Canary を ` nodejs/node_modules/myFolder/my_canary_filename` などの別のフォルダに保存することもできます。別のフォルダに保存する場合は、スクリプトエントリポイントでそのパスを指定します (` myFolder/my_canary_filename.functionName` など)。 ## 既存の Puppeteer スクリプトを変更して Synthetics の Canary として使用する このセクションでは、Puppeteer スクリプトを変更して Synthetics の Canary スクリプトとして実行する方法について説明します。Puppeteer の詳細については、「[Puppeteer API v1.14.0](https://github.com/puppeteer/puppeteer/blob/v1.14.0/docs/api.md)」を参照してください。 まず、次の Puppeteer スクリプトの例から始めます。 ``` const puppeteer = require('puppeteer'); (async () => { const browser = await puppeteer.launch(); const page = await browser.newPage(); await page.goto('https://example.com'); await page.screenshot({path: 'example.png'}); await browser.close(); })(); ``` 変更の手順は次のとおりです。 + `handler` 関数を作成してエクスポートします。このハンドラーは、スクリプトのエントリポイント関数です。` syn-nodejs-puppeteer-3.4` より前のランタイムを使用している場合、ハンドラー関数には `handler` という名前を付ける必要があります。`syn-nodejs-puppeteer-3.4` 以降を使用している場合、関数には任意の名前を付けることができますが、スクリプトで使用されている名前と同じである必要があります。また、`syn-nodejs-puppeteer-3.4` 以降を使用している場合は、スクリプトを任意のフォルダに保存し、そのフォルダをハンドラー名の一部として指定できます。 ``` const basicPuppeteerExample = async function () {}; exports.handler = async () => { return await basicPuppeteerExample(); }; ``` + `Synthetics` 依存関係を使用します。 ``` var synthetics = require('@aws/synthetics-puppeteer'); ``` + Puppeteer の `Page` オブジェクトを取得するには、`Synthetics.getPage` 関数を使用します。 ``` const page = await synthetics.getPage(); ``` Synthetics.getPage 関数から返されるページオブジェクトには、ログ記録用にインストルメント化された **page.on**、`request`、`response`、および ` requestfailed` の各イベントがあります。また、Synthetics は、ページのリクエストおよびレスポンス用の HAR ファイルの生成を設定し、ページの送信リクエストのユーザーエージェントヘッダーに Canary ARN を追加します。 これで、スクリプトを Synthetics の Canary として実行できるようになりました。更新されたスクリプトは次のとおりです。 ``` var synthetics = require('@aws/synthetics-puppeteer'); // Synthetics dependency const basicPuppeteerExample = async function () { const page = await synthetics.getPage(); // Get instrumented page from Synthetics await page.goto('https://example.com'); await page.screenshot({path: '/tmp/example.png'}); // Write screenshot to /tmp folder }; exports.handler = async () => { // Exported handler function return await basicPuppeteerExample(); }; ``` ## 環境変数 Canary を作成する際に環境変数を使用できます。これにより、単一の Canary スクリプトを記述し、そのスクリプトを異なる値で使用して、同様のタスクを持つ複数の Canary をすばやく作成できます。 例えば、組織が、ソフトウェア開発のさまざまな段階向けに `prod`、` dev`、`pre-release` などのエンドポイントを有しており、これらの各エンドポイントをテストするために Canary を作成する必要があるとします。ソフトウェアをテストする 1 つの Canary スクリプトを記述し、3 つの Canary をそれぞれ作成するときに、エンドポイント環境変数に異なる値を指定できます。その後、Canary を作成するときに、環境変数に使用するスクリプトと値を指定します。 環境変数の名前には、文字、数字、およびアンダースコアを使用できます。文字で始まり、少なくとも 2 文字である必要があります。環境変数の合計サイズは 4 KB を超えることはできません。Lambda の予約済み環境変数を環境変数の名前として指定することはできません。予約済み環境変数の詳細については、「[ランタイム環境変数](https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html#configuration-envvars-runtime)」をご参照ください。 **重要** 環境変数のキーと値は、保管時に AWS が所有する AWS KMS キーを使用して暗号化されます。ただし、クライアント側で環境変数が暗号化されます。機密情報は保存しないでください。 次のスクリプト例では、2 つの環境変数を使用しています。このスクリプトは、ウェブページが利用可能かどうかをチェックする Canary 用です。環境変数を使用して、チェックする URL と、使用する CloudWatch Synthetics ログレベルの両方をパラメータ化します。 次の関数は、`LogLevel` を ` LOG_LEVEL` 環境変数の値に設定します。 ``` synthetics.setLogLevel(process.env.LOG_LEVEL); ``` この関数は、`URL` を `URL` 環境変数の値に設定します。 ``` const URL = process.env.URL; ``` これは完全なスクリプトです。このスクリプトを使用して Canary を作成するときは、`LOG_LEVEL` および `URL` 環境変数の値を指定します。 ``` var synthetics = require('@aws/synthetics-puppeteer'); const log = require('@aws/synthetics-logger'); const pageLoadEnvironmentVariable = async function () { // Setting the log level (0-3) synthetics.setLogLevel(process.env.LOG_LEVEL); // INSERT URL here const URL = process.env.URL; let page = await synthetics.getPage(); //You can customize the wait condition here. For instance, //using 'networkidle2' may be less restrictive. const response = await page.goto(URL, {waitUntil: 'domcontentloaded', timeout: 30000}); if (!response) { throw "Failed to load page!"; } //Wait for page to render. //Increase or decrease wait time based on endpoint being monitored. await page.waitFor(15000); await synthetics.takeScreenshot('loaded', 'loaded'); let pageTitle = await page.title(); log.info('Page title: ' + pageTitle); log.debug('Environment variable:' + process.env.URL); //If the response status code is not a 2xx success code if (response.status() < 200 || response.status() > 299) { throw "Failed to load page!"; } }; exports.handler = async () => { return await pageLoadEnvironmentVariable(); }; ``` ### 環境変数をスクリプトに渡す コンソールで Canary を作成するときに環境変数をスクリプトに渡すには、コンソールの [**Environment variables**] (環境変数) セクションで環境変数のキーと値を指定します。詳細については、「[Canary を作成する](CloudWatch_Synthetics_Canaries_Create.md)」を参照してください。 API または AWS CLI を介して環境変数を渡すには、`RunConfig` セクションの ` EnvironmentVariables` パラメータを使用します。以下は、キー `Environment` とキー `Region` を持つ 2 つの環境変数を使用する Canary を作成する AWS CLI コマンドの例です。 ``` aws synthetics create-canary --cli-input-json '{ "Name":"nameofCanary", "ExecutionRoleArn":"roleArn", "ArtifactS3Location":"s3://amzn-s3-demo-bucket-123456789012-us-west-2", "Schedule":{ "Expression":"rate(0 minute)", "DurationInSeconds":604800 }, "Code":{ "S3Bucket": "canarycreation", "S3Key": "cwsyn-mycanaryheartbeat-12345678-d1bd-1234-abcd-123456789012-12345678-6a1f-47c3-b291-123456789012.zip", "Handler":"pageLoadBlueprint.handler" }, "RunConfig": { "TimeoutInSeconds":60, "EnvironmentVariables": { "Environment":"Production", "Region": "us-west-1" } }, "SuccessRetentionPeriodInDays":13, "FailureRetentionPeriodInDays":13, "RuntimeVersion":"syn-nodejs-2.0" }' ``` ## Canary と他の AWS のサービスとの統合 すべての Canary では AWS SDK ライブラリを使用できます。このライブラリを Canary の作成時に使用すると、Canary を他の AWS のサービスと統合できます。 これを行うには、Canary に次のコードを追加する必要があります。これらの例では、Canary に統合されているサービスとして AWS Secrets Manager が使用されます。 + AWS SDK をインポートします。 ``` const AWS = require('aws-sdk'); ``` + 統合する AWS のサービスのクライアントを作成します。 ``` const secretsManager = new AWS.SecretsManager(); ``` + このクライアントを使用して、サービスへの API コールを行います。 ``` var params = { SecretId: secretName }; return await secretsManager.getSecretValue(params).promise(); ``` 次の Canary スクリプトのコードスニペットは、Secrets Manager との統合例をより詳細に示しています。 ``` var synthetics = require('@aws/synthetics-puppeteer'); const log = require('@aws/synthetics-logger'); const AWS = require('aws-sdk'); const secretsManager = new AWS.SecretsManager(); const getSecrets = async (secretName) => { var params = { SecretId: secretName }; return await secretsManager.getSecretValue(params).promise(); } const secretsExample = async function () { let URL = ""; let page = await synthetics.getPage(); log.info(`Navigating to URL: ${URL}`); const response = await page.goto(URL, {waitUntil: 'domcontentloaded', timeout: 30000}); // Fetch secrets let secrets = await getSecrets("secretname") /** * Use secrets to login. * * Assuming secrets are stored in a JSON format like: * { * "username": "", * "password": "" * } **/ let secretsObj = JSON.parse(secrets.SecretString); await synthetics.executeStep('login', async function () { await page.type(">USERNAME-INPUT-SELECTOR<", secretsObj.username); await page.type(">PASSWORD-INPUT-SELECTOR<", secretsObj.password); await Promise.all([ page.waitForNavigation({ timeout: 30000 }), await page.click(">SUBMIT-BUTTON-SELECTOR<") ]); }); // Verify login was successful await synthetics.executeStep('verify', async function () { await page.waitForXPath(">SELECTOR<", { timeout: 30000 }); }); }; exports.handler = async () => { return await secretsExample(); }; ``` ## Canary に静的 IP アドレスの使用を強制する 静的 IP アドレスを使用するように Canary を設定できます。 **Canary に静的 IP アドレスの使用を強制するには** 1. 新しい VPC を作成します。詳細については、「[VPC での DNS の使用](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html)」を参照してください。 1. 新しいインターネットゲートウェイを作成します。詳細については、「[インターネットゲートウェイを VPC に追加する](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Internet_Gateway.html#working-with-igw)」を参照してください。 1. 新しい VPC 内にパブリックサブネットを作成します。 1. 新しいルートテーブルを VPC に追加します。 1. `0.0.0.0/0` からインターネットゲートウェイに向かうルートを、新しいルートテーブルに追加します。 1. 新しいルートテーブルをパブリックサブネットに関連付けます。 1. Elastic IP アドレスを作成します。詳細については、「[Elastic IP アドレス](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html)」を参照してください。 1. 新しい NAT ゲートウェイを作成し、パブリックサブネットと Elastic IP アドレスに割り当てます。 1. VPC の内部にプライベートサブネットを作成します。 1. `0.0.0.0/0` から NAT ゲートウェイへのルートを VPC デフォルトルートテーブルに追加する 1. Canary を作成します。 # Python Canary スクリプトの記述 このスクリプトは、合格して正常な実行となり、文字列を返します。失敗した Canary がどのように見えるかを確認するには、fail = False を fail = True に変更します ``` def basic_custom_script(): # Insert your code here # Perform multi-step pass/fail check # Log decisions made and results to /tmp # Be sure to wait for all your code paths to complete # before returning control back to Synthetics. # In that way, your canary will not finish and report success # before your code has finished executing fail = False if fail: raise Exception("Failed basicCanary check.") return "Successfully completed basicCanary checks." def handler(event, context): return basic_custom_script() ``` ## Python Canary ファイルのパッケージング 複数の .py ファイルがある場合、またはスクリプトに依存関係がある場合は、それらすべてを単一の ZIP ファイルにバンドルできます。`syn-python-selenium-1.1` ランタイムを使用する場合、ZIP ファイルには、`python/my_canary_filename.py` などの `python` フォルダ内にメインの Canary .py ファイルが含まれている必要があります。` syn-python-selenium-1.1` 以降を使用する場合は、オプションで、`python/myFolder/my_canary_filename.py` などの別のフォルダを使用できます。 この ZIP ファイルには、必要なすべてのフォルダとファイルが含まれている必要がありますが、他のファイルは `python` フォルダ内にある必要はありません。 スクリプトのエントリポイントのファイル名および関数名に一致するように、Canary のスクリプトのエントリポイントを ` my_canary_filename.functionName` として設定します。`syn-python-selenium-1.0` ランタイムを使用している場合は、`functionName` は `handler` である必要があります。` syn-python-selenium-1.1` 以降を使用している場合、このハンドラー名の制限は適用されません。また、オプションで Canary を ` python/myFolder/my_canary_filename.py` などの別のフォルダに保存することもできます。別のフォルダに保存する場合は、スクリプトエントリポイントでそのパスを指定します (` myFolder/my_canary_filename.functionName` など)。 ## Synthetics Canary を使用するようにするための既存の Selenium の変更 Canary として使用するために、Python と Selenium の既存のスクリプトをすばやく変更できます。Selenium の詳細については、[www.selenium.dev/](https://www.selenium.dev/) をご参照ください。 この例では、次の Selenium スクリプトから始めます。 ``` from selenium import webdriver def basic_selenium_script(): browser = webdriver.Chrome() browser.get('https://example.com') browser.save_screenshot('loaded.png') basic_selenium_script() ``` 変更の手順は次のとおりです。 **Selenium スクリプトを Canary として使用するように変換するには** 1. ` aws_synthetics` モジュールから Selenium を使用するように `import` ステートメントを変更します。 ``` from aws_synthetics.selenium import synthetics_webdriver as webdriver ``` `aws_synthetics` の Selenium モジュールは、Canary がメトリクスとログを出力し、HAR ファイルを生成し、他の CloudWatch Synthetics 機能で動作することを保証します。 1. ハンドラ関数を作成し、Selenium メソッドを呼び出します。このハンドラーは、スクリプトのエントリポイント関数です。 `syn-python-selenium-1.0` を使用している場合、ハンドラー関数には `handler` という名前を付ける必要があります。`syn-python-selenium-1.1` 以降を使用している場合、関数には任意の名前を付けることができますが、スクリプトで使用されている名前と同じである必要があります。また、`syn-python-selenium-1.1` 以降を使用している場合は、スクリプトを任意のフォルダに保存し、そのフォルダをハンドラー名の一部として指定できます。 ``` def handler(event, context): basic_selenium_script() ``` これで、スクリプトが CloudWatch Synthetics Canary に更新されました。更新されたスクリプトは次のとおりです。 `webdriver` は [SyntheticsWebDriver](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_Library_Python.html#CloudWatch_Synthetics_Library_Python_SyntheticsWebDriver) クラスのインスタンスであり、`webdriver.Chrome()` によって返されるブラウザは [SyntheticsBrowser](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_Library_Python.html#CloudWatch_Synthetics_Library_Python_SyntheticsBrowser) のインスタンスです。 ``` from aws_synthetics.selenium import synthetics_webdriver as webdriver def basic_selenium_script(): browser = webdriver.Chrome() browser.get('https://example.com') browser.save_screenshot('loaded.png') def handler(event, context): basic_selenium_script() ``` ## 既存の Puppeteer Synthetics スクリプトを変更して非標準の証明書を認証する Synthetics Canaries の重要なユースケースの 1 つは、独自のエンドポイントをモニタリングすることです。外部トラフィックに対応していないエンドポイントをモニタリングする場合、信頼できるサードパーティーの認証局によって署名された適切な証明書が存在しない可能性があります。 このシナリオで考えられる解決策は、次の 2 つです。 + クライアント証明書を認証するには、「[How to validate authentication using Amazon CloudWatch Synthetics – Part 2](https://aws.amazon.com/blogs/mt/how-to-validate-authentication-using-amazon-cloudwatch-synthetics-part-2/)」を参照してください。 + 自己署名証明書を認証するには、「[How to validate authentication with self-signed certificates in Amazon CloudWatch Synthetics](https://aws.amazon.com/blogs/mt/how-to-validate-authentication-with-self-signed-certificates-in-amazon-cloudwatch-synthetics/)」を参照してください。 CloudWatch Synthetics Canary を使用する場合は、これら 2 つのオプションに限定されません。Canary コードを拡張することで、これらの機能を拡張し、ビジネスロジックを追加できます。 **注記** Python ランタイムで実行される Synthetics Canary は、もともと ` --ignore-certificate-errors` フラグが有効になっているため、これらの Canary が非標準の証明書構成のサイトに到達しても問題ないはずです。 # Node.js マルチチェックブループリントの JSON 設定の記述 Node.js マルチチェックブループリントを使用すると、1 回の Canary 実行内で複数の検証チェックを実行する Canary を作成できます。このブループリントは、複数のエンドポイントをテストしたり、アプリケーションのさまざまな側面を検証したり、関連する一連のチェックを順番に実行したりする場合に便利です。 **Topics** + [ルート設定構造](#root-configuration-structure) + [[Global settings] (グローバル設定)](#global-settings) + [変数とデータ管理](#variables-data-management) + [ステップの定義](#step-definitions) + [チェックタイプ](#check-types) + [認証方法](#authentication-methods) + [アサーションと検証](#assertions-validation) + [データ抽出](#data-extraction) ## ルート設定構造 ルート設定は、高度な API ブループリント Canary の全体的な構造を定義します。 **スキーマプロパティ** | プロパティ | タイプ | 必須 | 説明 | | --- | --- | --- | --- | | globalSettings | オブジェクト | いいえ | すべてのステップに適用されるデフォルト設定 | | variables | オブジェクト | いいえ | ステップ間で再利用可能な値 (最大 10) | | steps | オブジェクト | あり | モニタリングステップのコレクション (1～10 ステップ) | **例** ``` { "globalSettings": { "stepTimeout": 30000, "userAgent": "CloudWatch-Synthetics-Advanced/1.0" }, "variables": { "baseUrl": "https://api.example.com", "apiVersion": "v1" }, "steps": { "1": { "stepName": "healthCheck", "checkerType": "HTTP", "url": "${baseUrl}/health", "httpMethod": "GET" } } } ``` **検証ルール** + 少なくとも 1 つのステップを含める必要があります + 最大 10 ステップまで可能 + `globalSettings`、` variables`、`steps` 以外の追加プロパティは不可 ## [Global settings] (グローバル設定) グローバル設定は、ステップレベルで上書きされない限り、すべてのステップに適用されるデフォルト設定を指定します。 **プロパティ** **グローバル設定のプロパティ** | プロパティ | タイプ | デフォルト | Range | 説明 | | --- | --- | --- | --- | --- | | stepTimeout | integer | 30000 | 5000～300000 | すべてのステップのデフォルトのタイムアウト (ミリ秒) | **例** ``` { "globalSettings": { "stepTimeout": 60000, } } ``` ## 変数とデータ管理 変数を使用すると、`${variableName}` 構文を使用して設定全体で参照できる再利用可能な値を定義できます。 **変数プロパティ** | プロパティ | 型 | 説明 | | --- | --- | --- | | 変数名 | string | パターン ^[a-zA-Z][a-zA-Z0-9\$1]\$1\$1 と一致する必要があります | | 変数値 | string | 任意の文字列値 | **制限事項** + 設定ごとに最大 10 個の変数 + 変数名は英字で始まる必要があります + 名前には、英字、数字、下線のみを含めることができます + スキーマで指定されていない最大長 **例** ``` { "variables": { "baseUrl": "https://api.example.com", "apiKey": "${AWS_SECRET:my-api-key}", "timeout": "30000", "userEmail": "test@example.com" } } ``` **設定の使用方法** ``` { "steps": { "1": { "url": "${baseUrl}/users", "timeout": "${timeout}", "headers": { "Authorization": "Bearer ${apiKey}" } } } } ``` ## ステップの定義 ステップは、個々のモニタリングオペレーションを定義します。各ステップには 1～10 の番号が付けられ、特定のタイプのチェックが含まれます。 *一般的なステップのプロパティ* | プロパティ | タイプ | 必須 | 説明 | | --- | --- | --- | --- | | stepName | 文字列 | あり | ステップの一意の識別子 | | checkerType | string | あり | チェックのタイプ: HTTP、DNS、SSL、 TCP | | extractors | array | いいえ | データ抽出設定 | *ステップ名の検証* + パターン - ^[a-zA-Z][a-zA-Z0-9\$1-]\$1\$1 + 最大文字数 - 64 文字 + 英字で始まっている必要があります *ステップの番号付け* + ステップには、文字列キーとして「1」、「2」、...、「10」という番号が付けられます。 + パターン: ^([1-9]\$110)\$1 + 最低 1 ステップが必要 + 最大 10 ステップまで可能 *例* ``` { "steps": { "1": { "stepName": "loginAPI", "checkerType": "HTTP", "url": "https://api.example.com/login", "httpMethod": "POST" }, "2": { "stepName": "dnsCheck", "checkerType": "DNS", "domain": "example.com" } } } ``` ## チェックタイプ ### HTTP チェック 包括的なリクエストとレスポンスの検証を使用して、ウェブエンドポイントと API をモニタリングします。 **必要なプロパティ** | プロパティ | 型 | 説明 | | --- | --- | --- | | url | string | ターゲット URL (有効な URI 形式である必要があります) | | httpMethod | string | HTTP method: GET、POST、PUT、 PATCH、DELETE、HEAD、OPTIONS | **オプションのプロパティ** | プロパティ | タイプ | デフォルト | Range | 説明 | | --- | --- | --- | --- | --- | | timeout | integer | 30000 | 5000～300000 | リクエストタイムアウト (ミリ秒) | | waitTime | integer | 0 | 0-60 | リクエスト前の遅延 (秒) | | headers | オブジェクト | - | - | カスタム HTTP ヘッダー | | body | string | - | - | POST/PUT オペレーションのリクエスト本文 | | authentication | オブジェクト | - | - | 認証の設定 | | assertions | array | - | - | レスポンス検証ルール | **例** ``` { "stepName": "createUser", "checkerType": "HTTP", "url": "https://api.example.com/users", "httpMethod": "POST", "timeout": 15000, "headers": { "Content-Type": "application/json", "X-API-Version": "v1" }, "body": "{\"name\":\"John Doe\",\"email\":\"john@example.com\"}", "authentication": { "type": "API_KEY", "apiKey": "${AWS_SECRET:api-credentials}", "headerName": "X-API-Key" }, "assertions": [ { "type": "STATUS_CODE", "operator": "EQUALS", "value": 201 } ] } ``` ### DNS チェック DNS 解決を検証し、情報を記録します。 **必要なプロパティ** | プロパティ | 型 | 説明 | | --- | --- | --- | | domain | string | クエリするドメイン名 (ホスト名形式) | **オプションのプロパティ** | プロパティ | タイプ | デフォルト | 説明 | | --- | --- | --- | --- | | recordType | string | 「A」 | DNS レコードタイプ: A、CNAME、MX、 TXT、NS | | nameserver | string | - | クエリする特定の DNS サーバー | | timeout | integer | 30000 | クエリタイムアウト (5000～300000 ms) | | port | integer | 53 | DNS サーバーポート (1～65535) | | protocol | string | 「UDP」 | プロトコル: UDP または TCP | | assertions | array | - | DNS レスポンス検証ルール | **例** ``` { "stepName": "dnsResolution", "checkerType": "DNS", "domain": "example.com", "recordType": "A", "nameserver": "8.8.8.8", "timeout": 10000, "assertions": [ { "type": "RECORD_VALUE", "operator": "CONTAINS", "value": "192.168" } ] } ``` ### SSL チェック SSL 証明書のヘルスと設定をモニタリングします。 **必要なプロパティ** | プロパティ | 型 | 説明 | | --- | --- | --- | | hostname | string | ターゲットホスト名 (ホスト名形式) | **オプションのプロパティ** | プロパティ | タイプ | デフォルト | 説明 | | --- | --- | --- | --- | | port | integer | 443 | SSL ポート (1～65535) | | timeout | integer | 30000 | 接続タイムアウト (5000～300000 ms) | | sni | boolean | TRUE | サーバー名の表示 | | verifyHostname | boolean | TRUE | ホスト名の検証 | | allowSelfSigned | ブール値 | FALSE | 自己署名証明書の受け入れ | | assertions | array | - | 証明書検証ルール | **例** ``` { "stepName": "sslCertCheck", "checkerType": "SSL", "hostname": "secure.example.com", "port": 443, "sni": true, "verifyHostname": true, "assertions": [ { "type": "CERTIFICATE_EXPIRY", "operator": "GREATER_THAN", "value": 30, "unit": "DAYS" } ] } ``` ### TCP チェック TCP ポートの接続とレスポンス検証をテストします。 **必要なプロパティ** | プロパティ | 型 | 説明 | | --- | --- | --- | | hostname | string | ターゲットホスト名 (ホスト名形式) | | port | integer | ターゲットポート (1～65535) | **オプションのプロパティ** | プロパティ | タイプ | デフォルト | 説明 | | --- | --- | --- | --- | | timeout | integer | 30000 | 全体的なタイムアウト (5000～300000 ms) | | connectionTimeout | integer | 3000 | 接続タイムアウト (5000～300000 ms) | | readTimeout | integer | 2000 | データ読み取りタイムアウト (5000～300000 ms) | | sendData | string | - | 接続後に送信するデータ | | expectedResponse | string | - | 予想されるレスポンスデータ | | encoding | string | 「UTF-8」 | データエンコーディング: UTF-8、ASCII、HEX | | assertions | array | - | 接続とレスポンスの検証 | **例** ``` { "stepName": "databaseConnection", "checkerType": "TCP", "hostname": "db.example.com", "port": 3306, "connectionTimeout": 5000, "sendData": "SELECT 1", "expectedResponse": "1", "assertions": [ { "type": "CONNECTION_SUCCESSFUL", "value": true } ] } ``` ## 認証方法 **認証なし** ``` { "type": "NONE" } ``` **基本認証** | プロパティ | タイプ | 必須 | 説明 | | --- | --- | --- | --- | | type | 文字列 | あり | "BASIC" を指定してください | | username | string | あり | 認証用のユーザー名 | | password | string | あり | 認証用のパスワード | **例** ``` { "type": "BASIC", "username": "admin", "password": "${AWS_SECRET:basic-auth:password}" } ``` **API キー認証** | プロパティ | タイプ | 必須 | デフォルト | 説明 | | --- | --- | --- | --- | --- | | type | 文字列 | あり | - | "API\$1KEY" を指定してください | | apiKey | string | あり | - | API キー値 | | headerName | string | いいえ | 「X-API-Key」 | API キーのヘッダー名 | **例** ``` { "type": "API_KEY", "apiKey": "${AWS_SECRET:api-credentials}", "headerName": "Authorization" } ``` **OAuth クライアントの認証情報** | プロパティ | タイプ | 必須 | デフォルト | 説明 | | --- | --- | --- | --- | --- | | type | 文字列 | あり | - | "OAUTH\$1CLIENT\$1CREDENTIALS" を指定してください | | tokenUrl | string | あり | - | OAuth トークンエンドポイント URL | | clientId | string | あり | - | OAuth クライアント ID | | clientSecret | string | あり | - | OAuth クライアントシークレット | | scope | string | いいえ | - | OAuth スコープ | | audience | string | いいえ | - | OAuth 対象者 | | resource | string | いいえ | - | OAuth リソース | | tokenApiAuth | array | いいえ | - | トークン API 認証メソッド: BASIC\$1AUTH\$1HEADER、REQUEST\$1BODY | | tokenCacheTtl | integer | いいえ | 3600 | トークンキャッシュ TTL (60 秒以上) | **例** ``` { "type": "OAUTH_CLIENT_CREDENTIALS", "tokenUrl": "https://auth.example.com/oauth/token", "clientId": "${AWS_SECRET:oauth-creds:client_id}", "clientSecret": "${AWS_SECRET:oauth-creds:client_secret}", "scope": "read write", "tokenCacheTtl": 7200 } ``` **AWS Signature (バージョン 4)** | プロパティ | タイプ | 必須 | 説明 | | --- | --- | --- | --- | | type | 文字列 | あり | "SIGV4" を指定してください | | service | string | あり | AWS サービスの名前 (「execute-api」など) | | region | string | あり | AWS リージョン | | roleArn | string | あり | 署名用の IAM ロール ARN | **例** ``` { "type": "SIGV4", "service": "execute-api", "region": "us-east-1", "roleArn": "arn:aws:iam::123456789012:role/SyntheticsRole" } ``` ## アサーションと検証 ### HTTP アサーション **ステータスコードアサーション** | プロパティ | タイプ | 必須 | 説明 | | --- | --- | --- | --- | | type | 文字列 | あり | "STATUS\$1CODE" を指定してください | | operator | string | あり | EQUALS, NOT\$1EQUALS, GREATER\$1THAN, LESS\$1THAN, IN\$1RANGE | | value | 整数 | 条件付き | HTTP ステータスコード (100～599) | | rangeMin | 整数 | 条件付き | 最小範囲値 (IN\$1RANGE の場合) | | rangeMax | 整数 | 条件付き | 最大範囲値 (IN\$1RANGE の場合) | ``` { "type": "STATUS_CODE", "operator": "EQUALS", "value": 200 } ``` **応答時間のアサーション** | プロパティ | タイプ | 必須 | デフォルト | 説明 | | --- | --- | --- | --- | --- | | type | 文字列 | あり | - | "RESPONSE\$1TIME" を指定してください | | operator | string | あり | - | LESS\$1THAN, GREATER\$1THAN, EQUALS | | value | 数値 | あり | - | 時間値 (最小 0) | | unit | string | いいえ | 「MILLISECONDS」 | "MILLISECONDS" を指定してください | ``` { "type": "RESPONSE_TIME", "operator": "LESS_THAN", "value": 500, "unit": "MILLISECONDS" } ``` **ヘッダーアサーション** | プロパティ | タイプ | 必須 | 説明 | | --- | --- | --- | --- | | type | 文字列 | あり | "HEADER" を指定してください | | headerName | string | あり | 検証するヘッダーの名前 | | operator | string | あり | EQUALS, NOT\$1EQUALS, CONTAINS, NOT\$1CONTAINS, REGEX\$1MATCH, EXIST | | value | 文字列/ブール型 | 条件付き | 予想される値 (EXIST 演算子のブール値) | ``` { "type": "HEADER", "headerName": "Content-Type", "operator": "CONTAINS", "value": "application/json" } ``` **本文アサーション** | プロパティ | タイプ | 必須 | デフォルト | 説明 | | --- | --- | --- | --- | --- | | type | 文字列 | あり | - | "BODY" を指定してください | | target | string | いいえ | 「JSON」 | JSON、または TEXT | | path | string | 条件付き | - | JSONPath (JSON ターゲットに必須) | | operator | string | あり | - | CONTAINS, NOT\$1CONTAINS, EQUALS, NOT\$1EQUALS, EXISTS | | value | 文字列/ブール型 | あり | - | 予想される値 (EXISTS 演算子のブール値) | ``` { "type": "BODY", "target": "JSON", "path": "$.users[0].name", "operator": "EQUALS", "value": "John Doe" } ``` ### DNS アサーション **レコード値のアサーション** | プロパティ | タイプ | 必須 | Range | 説明 | | --- | --- | --- | --- | --- | | type | 文字列 | あり | - | "RECORD\$1VALUE" を指定してください | | operator | string | あり | - | EQUALS, NOT\$1EQUALS, CONTAINS, NOT\$1CONTAINS, REGEX\$1MATCH | | value | string | あり | - | 予想されるレコード値 | **レコード数のアサーション** | プロパティ | タイプ | 必須 | Range | 説明 | | --- | --- | --- | --- | --- | | type | 文字列 | あり | - | "RECORD\$1COUNT" を指定してください | | operator | string | あり | - | EQUALS, GREATER\$1THAN, LESS\$1THAN | | value | integer | あり | ≥ 0 | 予想される個数 (最小 0) | **認可アサーション** | プロパティ | タイプ | 必須 | Range | 説明 | | --- | --- | --- | --- | --- | | type | 文字列 | あり | - | "AUTHORITATIVE" を指定してください | | value | boolean | あり | - | 想定される認可ステータス | **TTL アサーション** | プロパティ | タイプ | 必須 | Range | 説明 | | --- | --- | --- | --- | --- | | type | 文字列 | あり | - | "TTL" を指定してください | | operator | string | あり | - | EQUALS, GREATER\$1THAN, LESS\$1THAN | | value | integer | あり | ≥ 0 | 予想される TTL (最小 0) | ### SSL アサーション **証明書の有効期限のアサーション** | プロパティ | タイプ | 必須 | デフォルト | 説明 | | --- | --- | --- | --- | --- | | type | 文字列 | あり | - | "CERTIFICATE\$1EXPIRY" を指定してください | | operator | string | あり | - | GREATER\$1THAN, LESS\$1THAN | | value | integer | あり | - | 時間値 (最小 0) | | unit | string | いいえ | 「DAYS」 | DAYS, HOURS | **証明書のサブジェクトのアサーション** | プロパティ | タイプ | 必須 | デフォルト | 説明 | | --- | --- | --- | --- | --- | | type | 文字列 | あり | - | "CERTIFICATE\$1SUBJECT" を指定してください | | field | string | あり | - | サブジェクトフィールド: CN、O、OU、C、ST、L | | operator | string | あり | - | CONTAINS, EQUALS, REGEX\$1MATCH | | value | string | あり | - | 予想されるフィールド値 | **証明書発行者のアサーション** | プロパティ | タイプ | 必須 | デフォルト | 説明 | | --- | --- | --- | --- | --- | | type | 文字列 | あり | - | "CERTIFICATE\$1ISSUER" を指定してください | | field | string | あり | - | 発行者フィールド: CN、O | | operator | string | あり | - | CONTAINS, EQUALS | | value | string | あり | - | 予想されるフィールド値 | ### TCP アサーション **接続成功アサーション** | プロパティ | タイプ | 必須 | デフォルト | 説明 | | --- | --- | --- | --- | --- | | type | 文字列 | あり | - | "CONNECTION\$1SUCCESSFUL" を指定してください | | value | boolean | あり | - | 予想される接続ステータス | **レスポンスデータのアサーション** | プロパティ | タイプ | 必須 | デフォルト | 説明 | | --- | --- | --- | --- | --- | | type | 文字列 | あり | - | "RESPONSE\$1DATA" を指定してください | | operator | string | あり | - | CONTAINS, EQUALS, NOT\$1CONTAINS, REGEX\$1MATCH, STARTS\$1WITH, ENDS\$1WITH | | value | string | あり | - | 予想されるレスポンスデータ | | encoding | string | いいえ | 「UTF-8」 | UTF-8, ASCII, HEX | ## データ抽出 エクストラクターを使用すると、後続のステップでの使用やレポートのために、レスポンスからデータをキャプチャできます。 **抽出プロパティ** | プロパティ | タイプ | 必須 | デフォルト | 説明 | | --- | --- | --- | --- | --- | | name | 文字列 | あり | - | 抽出されたデータの変数名 | | type | string | あり | - | 抽出タイプ: BODY | | path | string | いいえ | - | 本文抽出用の JSONPath | | regex | string | いいえ | - | 正規表現パターン | | regexGroup | integer | いいえ | 0 | 正規表現キャプチャグループ (最小 0) | **抽出名の検証** + パターン: `^[a-zA-Z][a-zA-Z0-9_]*$` + 英字で始まっている必要があります + 英字、数字、下線のみを含めることができます **制限** – 置換は、特定の ENUM 値を持つスキーマのフィールドには適用されません。 **抽出タイプ** ``` { "name": "userId", "type": "BODY", "path": "$.user.id" } ``` ``` { "stepName": "loginAndExtract", "checkerType": "HTTP", "url": "https://api.example.com/login", "httpMethod": "POST", "body": "{\"username\":\"test\",\"password\":\"pass\"}", "extractors": [ { "name": "textVariable", "type": "BODY", "path": "$.myvalue" } ] }, { "stepName": "substituteVariable", "checkerType": "HTTP", "url": "https://api.example.com/get/${textVariable}", "httpMethod": "GET", "assertions": [ { "type": "BODY", "target": "JSON", "path": "$.users[0].name", "operator": "EQUALS", "value": "${textVariable}" } ] } ``` # Canary スクリプト用のライブラリ関数 CloudWatch Synthetics には複数の組み込みクラスおよび関数が用意されており、これらを Node.js スクリプトの作成時に呼び出して Canary として使用できます。 UI Canary と API Canary の両方に適用されるものもあります。他の関数は UI Canary にのみ適用されます。UI Canary は `getPage()` 関数を使用する Canary であり、Puppeteer をウェブドライバーとして使用することで、ウェブページをナビゲートしたり操作したりします。 **注記** Canary をアップグレードして新しいバージョンの Synthetics ランタイムを使用するたびに、Canary が使用するすべての Synthetics ライブラリ関数も Synthetics ランタイムがサポートするのと同じバージョンの NodeJS に自動的にアップグレードされます。 **Topics** + [Node.js Canary 用のライブラリ関数](Library_function_Nodejs.md) + [Java Canary 用のライブラリ関数](CloudWatch_Synthetics_Canaries_Java.md) + [Playwright を使用する Node.js Canary スクリプトに利用可能なライブラリ関数](CloudWatch_Synthetics_Canaries_Nodejs_Playwright.md) + [Puppeteer を使用した Node.js Canary スクリプト用のライブラリ関数](CloudWatch_Synthetics_Canaries_Library_Nodejs.md) + [Selenium を使用する Python Canary スクリプトで利用可能なライブラリ関数](CloudWatch_Synthetics_Canaries_Library_Python.md) # Node.js Canary 用のライブラリ関数 このセクションでは、Node.js ランタイムを使用して Canary スクリプトで使用できるライブラリ関数について説明します。 **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); `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 ライブラリの現在のログレベルを取得します。取り得る値には以下のものがあります。 + `0` – デバッグ + `1` – 情報 + `2` – 警告 + `3` – エラー 例: ``` let logLevel = synthetics.getLogLevel(); ``` ## setLogLevel(); Synthetics ライブラリのログレベルを設定します。取り得る値には以下のものがあります。 + `0` – デバッグ + `1` – 情報 + `2` – 警告 + `3` – エラー 例: ``` synthetics.setLogLevel(0); ``` ## executeStep(stepName, functionToExecute, [stepConfig]) 指定されたステップを実行します。ステップは、開始/成功/失敗のログ記録、成功/失敗と所要時間のメトリクスでラップされます。 `executeStep` 関数は、次のことも行います。 + ステップの開始をログに記録 + タイマーを開始 + 指定された関数を実行 + 関数が正常に戻ると、成功としてカウント。関数がスローされると、失敗としてカウント + タイマーを終了 + ステップが合格したか失敗したかをログに記録します。 + `stepName SuccessPercent` メトリクスを出力。合格の場合は 100、不合格の場合は 0 + `stepName Duration metric` メトリクスを出力。値は、ステップの開始時刻と終了時刻に基づきます + functionToExecute が返した内容を返すか、` functionToExecute` がスローした内容を再スロー + Canary のレポートにステップ実行の概要を追加 **例** ``` 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 リクエストの詳細が含まれます。 + 開始時間 + 終了時間 + ステータス (PASSED/FAILED) + 失敗の理由 (失敗した場合) + リクエスト/レスポンスヘッダー、本文、ステータスコード、ステータスメッセージ、パフォーマンスタイミングなどの HTTP 呼び出しの詳細。 **Topics** + [パラメータ](#Library_function_Nodejs_executeHttpStep_parameters_Nodecanary) + [executeHttpStep の使用例](#Library_function_Nodejs_executeHttpStep_examples_Nodecanary) ### パラメータ **stepName(*文字列*)** ステップの名前を指定します。この名前は、このステップの CloudWatch メトリクスを発行する場合にも使用されます。 **requestOptions(*オブジェクトまたは文字列*)** このパラメータの値には、URL、URL 文字列、またはオブジェクトを指定できます。オブジェクトの場合、HTTP リクエストを行うために設定可能なオプションのセットである必要があります。Node.js ドキュメントの [http.request(options[, callback])](https://nodejs.org/api/http.html#http_http_request_options_callback) のすべてのオプションをサポートしています。 これらの Node.js オプションに加えて、**requestOptions** では、追加のパラメータ `body` がサポートされます。`body` パラメータを使用して、データをリクエスト本文として渡すことができます。 **callback(*レスポンス*)** (オプション) これは HTTP レスポンスで呼び出されるユーザー関数です。レスポンスは、[Class: http.IncomingMessage](https://nodejs.org/api/http.html#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](CloudWatch_Synthetics_Canaries_Samples.md#CloudWatch_Synthetics_Canaries_Samples_APIsteps)」を参照してください。 # Java Canary 用のライブラリ関数 `executeStep` 関数は、Canary コードをモジュール化してステップで実行するために使用されます。CloudWatch Synthetics では、Synthetics ステップは、Canary スクリプトを一連の明確に定義されたアクションに分割する方法であり、アプリケーションジャーニーのさまざまな部分を個別にモニタリングできます。CloudWatch Synthetics は、ステップごとに以下を実行します。 + ステップの期間、*合格* または *失敗* ステータスなど、ステップ実行の詳細の概要を含むレポートが Canary 実行ごとに作成されます。CloudWatch Synthetics コンソールで実行を選択すると、**[ステップ]** タブで各ステップの実行の詳細を表示できます。 + *SuccessPercent* および *Duration* CloudWatch メトリクスはステップごとに出力されるため、ユーザーは各ステップの可用性とレイテンシーをモニタリングできます。 **使用方法** ``` synthetics.executeStep(stepName,()->{ try { //step code to be executed return null; } catch (Exception e) { throw e; } }).get(); ``` **パラメータ** + *stepName*。文字列 (必須) – Synthetics ステップの特徴を説明した名前 + *実行する関数*。Callable (必須) – 実行するタスクを表します + *stepOptions*。`com.amazonaws.synthetics.StepOptions (optional)` – ステップ実行の設定に使用できる StepOptions オブジェクト。 *stepConfiguration*。` com.amazonaws.synthetics.StepConfiguration` (stepOptions の一部として必須) **戻り値** 戻ってくる値は *CompletableFuture* です。 **注記** Synthetics でサポートされるのはシーケンシャルステップのみです。例に示すように、必ず `.get()` メソッドを呼び出し、ステップが完了していることを確認してから次のステップに進んでください。 # Playwright を使用する Node.js Canary スクリプトに利用可能なライブラリ関数 このセクションでは、Node.js Playwright ランタイムを使用して Canary スクリプトで使用できるライブラリ関数について説明します。 **Topics** + [打ち上げ](#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) ## 打ち上げ この関数は、Playwright 起動関数を使用して Chromium ブラウザを起動し、ブラウザオブジェクトを返します。ブラウザバイナリを解凍し、ヘッドレスブラウザに適したデフォルトオプションを使用して Chromium ブラウザを起動します。`launch` 関数の詳細については、Playwright ドキュメントにある「[https://playwright.dev/docs/api/class-browsertype#browser-type-launch](https://playwright.dev/docs/api/class-browsertype#browser-type-launch)」を参照してください。 **使用方法** ``` const browser = await synthetics.launch(); ``` **引数** `options` [オプション](https://playwright.dev/docs/api/class-browsertype#browser-type-launch) (任意) は、ブラウザの構成可能なオプションのセットです。 **戻り値** Promise ``。ここで、[Browser](https://playwright.dev/docs/api/class-browser) は Playwright ブラウザインスタンスです。 この関数を再度呼び出すと、以前に開いたブラウザが閉じられてから新しいブラウザが開始されます。ブラウザを起動するときに、CloudWatch Synthetics で使用されている起動パラメータを上書きし、追加のパラメータを渡すことができます。例えば、次のコードスニペットでは、デフォルトの引数とデフォルトの実行可能パスを使用してブラウザを起動しますが、ビューポートは 800 x 600 ピクセルになります。詳細については、Playwright ドキュメントの「[Playwright 起動オプション](https://playwright.dev/docs/api/class-browsertype#browser-type-launch)」を参照してください。 ``` const browser = await synthetics.launch({ defaultViewport: { "deviceScaleFactor": 1, "width": 800, "height": 600 }}); ``` デフォルトでブラウザに渡される Chromium フラグを追加または上書きすることもできます。例えば、ウェブセキュリティを無効にするには、CloudWatch Synthetics の起動パラメータの引数に `--disable-web-security` フラグを追加します。 ``` // 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 `newPage()` 関数は新しい Playwright ページを作成して返します。Synthetics は Chrome DevTools Protocol (CDP) 接続を自動的にセットアップして、HTTP アーカイブ (HAR) 生成のネットワークキャプチャを有効にします。 **使用方法** 以下のいずれかの方法で、`newPage()` を使用してください。 **1. 新しいブラウザコンテキストで新しいページを作成する：** ``` const page = await synthetics.newPage(browser); ``` **2. 指定したブラウザコンテキストで新しいページを作成する：** ``` // 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) ``` **引数** Playwright [Browser](https://playwright.dev/docs/api/class-browser) インスタンスまたは Playwright [BrowserContext](https://playwright.dev/docs/api/class-browsercontext) インスタンスのいずれかを受け入れます。 **戻り値** Promise 。ここで、Page は Playwright [Page](https://playwright.dev/docs/api/class-page) インスタンスです。 ## close 現在開いているブラウザを閉じます。 **使用方法** ``` await synthetics.close(); ``` スクリプトの `finally` ブロックでブラウザを閉じることをお勧めします。 **引数** なし **戻り値** ブラウザを起動するために Synthetics 起動関数で使用される Promise を返します。 ## getDefaultLaunchOptions `getDefaultLaunchOptions()` 関数は、CloudWatch Synthetics で使用するブラウザ起動オプションを返します。 **使用方法** ``` const defaultOptions = await synthetics.getDefaultLaunchOptions(); ``` **引数** なし **戻り値** ブラウザを起動するために Synthetics `launch` 関数で使用される Playwright [起動オプション](https://playwright.dev/docs/api/class-browsertype#browser-type-launch)を返します。 ## executeStep `executeStep` 関数は、Synthetics スクリプトでステップを実行するために使用されます。CloudWatch Synthetics では、Synthetics ステップは、Canary スクリプトを一連の明確に定義されたアクションに分割する方法であり、アプリケーションジャーニーのさまざまな部分を個別にモニタリングできます。CloudWatch Synthetics は、ステップごとに以下を実行します。 + ステップの開始前とステップの完了後にスクリーンショットを自動的にキャプチャします。ステップ内でスクリーンショットをキャプチャすることもできます。スクリーンショットはデフォルトでキャプチャされますが、Synthetics 設定を使用してオフにできます。 + ステップの期間、`pass` または `fail` ステータス、ソースページと宛先ページの URL、関連するスクリーンショットなど、ステップ実行の詳細の概要を含むレポートが Canary 実行ごとに作成されます。CloudWatch Synthetics コンソールで実行を選択すると、**[ステップ]** タブで各ステップの実行の詳細を表示できます。 + `SuccessPercent` および `Duration` CloudWatch メトリクスはステップごとに出力されるため、ユーザーは各ステップの可用性とレイテンシーをモニタリングできます。 **使用方法** ``` await synthetics.executeStep("mystepname", async function () { await page.goto(url, { waitUntil: 'load', timeout: 30000 }); } ``` **注記** ステップは順番に実行する必要があります。Promise では必ず `await` を使用してください。 **引数** + `stepName` string (必須) (ブール値) - Synthetics ステップの名前。 + `functionToExecute` async function (必須) - Synthetics を実行する関数。この関数には、 ステップのロジックが含まれている必要があります。 + `stepConfig` オブジェクト (オプション) — ステップ設定では、このステップのグローバル Synthetics 設定を上書きします。 + `continueOnStepFailure` ブール値 (オプション) — このステップが失敗した後も Canary スクリプトの実行を継続するかどうか。 + `screenshotOnStepStart` ブール値 (オプション) - このステップの開始時にスクリーンショットを作成するかどうか。 + `screenshotOnStepSuccess` ブール値 (オプション) — このステップが成功した場合にスクリーンショットを作成するかどうか。 + `screenshotOnStepFailure` ブール値 (オプション) — このステップが失敗した場合にスクリーンショットを作成するかどうか。 + `page` — Playwright ページオブジェクト (オプション) Playwright ページオブジェクト。Synthetics は、このページオブジェクトを使用してスクリーンショットと URL をキャプチャします。デフォルトでは、Synthetics は、スクリーンショットや URL などのページの詳細をキャプチャするために `synthetics.newPage()` 関数が呼び出されたときに作成された Playwright ページを使用します。 **戻り値** ` functionToExecute` 関数によって返された値で解決される Promise を返します。スクリプトの例については、このガイドの「[Canary スクリプトのサンプルコード](CloudWatch_Synthetics_Canaries_Samples.md)」を参照してください。 # Puppeteer を使用した Node.js Canary スクリプト用のライブラリ関数 このセクションでは、Node.js Canary スクリプトで使用できるライブラリ関数を説明します。 **Topics** + [すべての Canary に適用される Node.js ライブラリクラスおよび関数](#CloudWatch_Synthetics_Library_allcanaries) + [UI Canary のみに適用される Node.js ライブラリクラスおよび関数](#CloudWatch_Synthetics_Library_UIcanaries) + [API Canary のみに適用されるライブラリクラスおよび関数](#CloudWatch_Synthetics_Library_APIcanaries) ## すべての Canary に適用される Node.js ライブラリクラスおよび関数 以下の Node.js 用の CloudWatch Synthetics ライブラリ関数は、すべての Canary について有用です。 **Topics** + [Synthetics クラス](#CloudWatch_Synthetics_Library_Synthetics_Class_all) + [SyntheticsConfiguration クラス](#CloudWatch_Synthetics_Library_SyntheticsConfiguration) + [Synthetics logger](#CloudWatch_Synthetics_Library_SyntheticsLogger) + [SyntheticsLogHelper クラス](#CloudWatch_Synthetics_Library_SyntheticsLogHelper) ### Synthetics クラス すべての Canary の次の関数は、Synthetics クラスにあります。 **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); `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]);](#CloudWatch_Synthetics_Library_executeStep)」および「[executeHttpStep(stepName, requestOptions, [callback], [stepConfig])](#CloudWatch_Synthetics_Library_executeHttpStep)」を参照してください **Topics** + [setConfig(options)](#CloudWatch_Synthetics_Library_setConfig) + [ビジュアルモニターリング](#CloudWatch_Synthetics_Library_SyntheticsLogger_VisualTesting) #### 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`。 **重要** `includeResponseBody` または ` logResponseBody` のいずれかを有効にした場合、aws-sdk v3 クライアントを含む、一部の API からのレスポンスではデータオブジェクトが返されません。これは、Node.js の制限と使用されるレスポンスオブジェクトのタイプに起因する現象です。 **CloudWatch メトリクスに関する setConfig (オプション)** `syn-nodejs-puppeteer-3.1` 以降を使用する Canary の場合、**setConfig** の **(オプション)** には、Canary によって発行されるメトリクスを決定する次のブール値パラメータを含めることができます。これらの各オプションのデフォルトは `true` です。`aggregated` で始まるオプションは、` CanaryName` ディメンションなしでメトリクスを出力するかどうかを決定します。これらのメトリクスを使用して、すべての Canary の集計結果を確認できます。その他のオプションは、`CanaryName` ディメンションを含むメトリクスを出力するかどうかを決定します。これらのメトリクスを使用して、個々の Canary の結果を確認できます。 Canary から発行される CloudWatch メトリクスのリストについては、「[Canary によって発行される CloudWatch メトリクス](CloudWatch_Synthetics_Canaries_metrics.md)」を参照してください。 + `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` です。 + `includeUrlPassword`(ブール値) — URL に表示されるパスワードを含めるかどうか。デフォルトでは、機密データの開示を防ぐために、URL に表示されるパスワードはログとレポートで墨消しされます。デフォルトは `false` です。 + `restrictedUrlParameters` (配列)— 編集する URL パスまたはクエリパラメータのリスト。これは、ログ、レポート、エラーに表示される URL に適用されます。パラメータ名では大文字と小文字が区別されます。アスタリスク (\$1) を値として渡すと、すべての URL パスおよびクエリパラメータ値を墨消しできます。デフォルトは、空白の配列です。 + `logRequest`（ブール値）-すべてのリクエストを Canary ログに記録するかどうか。UI Canary の場合、ブラウザから送信された各リクエストがログに記録されます。デフォルトは `true` です。 + `logResponse`（ブール値）-すべてのレスポンスを Canary ログに記録するかどうか。UI Canary の場合、ブラウザが受信したすべてのレスポンスをログに記録します。デフォルトは `true` です。 + `logRequestBody`（ブール値）-リクエスト本文を Canary ログのリクエストとともに記録するかどうか。この設定は、`logRequest` が `true` である場合にのみ適用されます。デフォルトは `false` です。 + `logResponseBody`（ブール値）-レスポンス本文を Canary ログのレスポンスとともに記録するかどうか。この設定は、`logResponse` が `true` である場合にのみ適用されます。デフォルトは ` false` です。 **重要** `includeResponseBody` または ` logResponseBody` のいずれかを有効にした場合、aws-sdk v3 クライアントを含む、一部の API からのレスポンスではデータオブジェクトが返されません。これは、Node.js の制限と使用されるレスポンスオブジェクトのタイプに起因する現象です。 + `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(\$12xxMetric)** ブール引数を受け入れます。この引数は、この Canary に対して `2xx` ディメンションを持つ `CanaryName` メトリクスを出力するかどうかを指定します。 **with4xxMetric(\$14xxMetric)** ブール引数を受け入れます。この引数は、この Canary に対して `4xx` ディメンションを持つ `CanaryName` メトリクスを出力するかどうかを指定します。 **with5xxMetric(\$15xxMetric)** ブール引数を受け入れます。この引数は、この 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 に適用されます。アスタリスク (\$1) を値として渡すと、すべての 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('@aws/synthetics-puppeteer'); // 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 クラス](#CloudWatch_Synthetics_Library_SyntheticsConfiguration)」を参照してください。 ``` syntheticsConfiguration.withVisualCompareWithBaseRun(true); ``` この行がスクリプトに追加された後に初めて Canary が正常に実行されると、その実行中に撮影されたスクリーンショットが比較のベースラインとして使用されます。最初に Canary を実行した後、CloudWatch コンソールを使用して Canary を編集して、次のいずれかの操作を行うことができます。 + Canary の次の実行を新しいベースラインとして設定する。 + 現在のベースラインスクリーンショットに境界を描画し、ビジュアル比較時に無視するスクリーンショットの領域を指定する。 + スクリーンショットをビジュアルモニターリングに使用しないようにする。 CloudWatch コンソールを使用して Canary を編集する方法の詳細については、 「[Canary を編集または削除する](synthetics_canaries_deletion.md)」を参照してください。 **ビジュアルモニターリングのその他のオプション** **syntheticsConfiguration.withVisualVarianceThresholdPercentage(desiredPercentage)** ビジュアル比較におけるスクリーンショットの差異の許容パーセンテージを設定します。 **syntheticsConfiguration.withVisualVarianceHighlightHexColor("\$1fafa00")** ビジュアルモニターリングを使用する 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('@aws/synthetics-logger'); ``` 有用な関数定義: **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 は、Synthetics の構成設定 `restrictedUrlParameters` に基づいて、ログ、レポート、HAR ファイル、および Canary 実行エラーに含める前に、ログに記録されるすべての URL とエラーメッセージをサニタイズします。` getSanitizedUrl` または `getSanitizedErrorMessage` は、スクリプトに URL またはエラーを記録している場合にのみ使用できます。Synthetics は、スクリプトによってスローされた Canary エラーを除いて、Canary アーティファクトを保存しません。Canary 実行アーティファクトは、顧客アカウントに保存されます。詳細については、「[Synthetics Canary のセキュリティ上の考慮事項](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) この関数は、`syn-nodejs-puppeteer-3.2` 以降で使用できます。これは、設定に基づいてサニタイズされた URL 文字列を返します。プロパティ `restrictedUrlParameters`1を設定することで、パスワードや access\$1token などの機密性の高い URL を編集するように選択できます。デフォルトでは、URL 内のパスワードは編集できます。URL パスワードを有効にするには、必要に応じて `includeUrlPassword` を true に設定します。 渡された 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 実行 Artifact を保存しないことに注意してください。ログ、スクリーンショット、レポートなどの Artifact は、すべてカスタマーアカウントの Amazon S3 バケットに保存されます。 最初のステップでは、Synthetics の構成を設定します。 ``` // 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); ``` 次に、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'); ``` これは、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 = syntheticsLogHelper.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('@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'); try { // Your code which can throw an error containing url which your script logs } catch (error) { const sanitizedErrorMessage = syntheticsLogHelper.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` 以降で使用できます。これは、` syntheticsConfiguration` の `restrictedHeaders` プロパティに基づいてサニタイズされたヘッダーを返します。`restrictedHeaders` プロパティで指定されたヘッダーは、ログ、HAR ファイル、およびレポートから編集されます。 **パラメータ** + *headers* は、サニタイズするヘッダーを含むオブジェクトです。 + *stepConfig* (オプション) この関数のグローバル Synthetics 設定を上書きします。`stepConfig` が渡されない場合、グローバル設定を使用してヘッダーをサニタイズします。 ## UI Canary のみに適用される Node.js ライブラリクラスおよび関数 Node.js 用の次の CloudWatch Synthetics ライブラリ関数は、UI の Canary にのみ適用されます。 **Topics** + [Synthetics クラス](#CloudWatch_Synthetics_Library_Synthetics_Class) + [BrokenLinkCheckerReport クラス](#CloudWatch_Synthetics_Library_BrokenLinkCheckerReport) + [SyntheticsLink クラス](#CloudWatch_Synthetics_Library_SyntheticsLink) ### Synthetics クラス Synthetics クラスには、次の関数が含まれます。 **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 クラス](#CloudWatch_Synthetics_Library_RequestResponseLogHelper) + [setRequestResponseLogHelper();](#CloudWatch_Synthetics_Library_setRequestResponseLogHelper) + [async takeScreenshot(name, suffix);](#CloudWatch_Synthetics_Library_takeScreenshot) #### async addUserAgent(page, userAgentString); この関数は、指定されたページの user-agent ヘッダーに *userAgentString* を追加します。 例: ``` 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 クラス](#CloudWatch_Synthetics_Library_SyntheticsConfiguration)」を参照してください。 `executeStep` 関数は、次のことも行います。 + ステップが開始されたことをログに記録します。 + `-starting` という名前でスクリーンショットを作成します。 + タイマーを開始します。 + 指定された関数を実行します。 + 関数が正常に戻ると、合格としてカウントします。関数がスローされると、失敗としてカウントします。 + タイマーを終了します。 + ステップが合格したか失敗したかをログに記録します。 + `-succeeded` や ` -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 クラス](#CloudWatch_Synthetics_Library_SyntheticsConfiguration)」を参照してください。 次の例では、` continueOnStepFailure` のデフォルトの `false` 設定を `true` に上書きし、スクリーンショットをいつ取得するかを指定します。 ``` 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 で使用するブラウザ起動オプションを返します。詳細については、「[起動オプションの種類](https://pptr.dev/browsers-api/browsers.launchoptions/)」を参照してください ``` // This function returns default launch options used by Synthetics. const defaultOptions = await synthetics.getDefaultLaunchOptions(); ``` #### getPage (); 現在開いているページを Puppeteer オブジェクトとして返します。詳細については、[Puppeteer API v1.14.0](https://github.com/puppeteer/puppeteer/blob/v1.14.0/docs/api.md) を参照してください。 例: ``` let page = await synthetics.getPage(); ``` レスポンス: 現在のブラウザセッションで現在開いているページ (Puppeteer オブジェクト)。 #### getRequestResponseLogHelper(); **重要** `syn-nodejs-puppeteer-3.2` 以降のランタイムを使用する Canary で、この関数は `RequestResponseLogHelper` クラスと共に廃止予定です。この関数を使用すると、Canary ログに警告が表示されます。この関数は、将来のランタイムバージョンで削除されます。この関数を使用している場合は、代わりに [RequestResponseLogHelper クラス](#CloudWatch_Synthetics_Library_RequestResponseLogHelper) を使用してください。 この関数は、リクエストとレスポンスのログ記録フラグを調整するためのビルダーパターンとして使用します。 例: ``` synthetics.setRequestResponseLogHelper(getRequestResponseLogHelper().withLogRequestHeaders(false));; ``` レスポンス: ``` {RequestResponseLogHelper} ``` #### launch(options) この関数のオプションは、`syn-nodejs-2.1` ランタイムバージョン以降でのみ使用できます。 この関数は UI Canary でのみ使用します。これは、既存のブラウザを閉じ、新しいブラウザを起動します。 **注記** CloudWatch Synthetics は、スクリプトの実行を開始する前に、必ずブラウザを起動します。カスタムオプションを使用して新しいブラウザを起動する場合を除いては、launch() を呼び出す必要はありません。 (options) は、ブラウザで設定する構成可能なオプションのセットです。詳細については、「[起動オプションの種類](https://pptr.dev/browsers-api/browsers.launchoptions/)」を参照してください。 この関数をオプションなしで呼び出すと、Synthetics はデフォルトの引数である `executablePath` と `defaultViewport` を使用してブラウザを起動します。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` フラグを追加します。 ``` // 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 クラス](#CloudWatch_Synthetics_Library_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 クラス](#CloudWatch_Synthetics_Library_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` 関数でステップ名を渡すことで、さらに多くのスクリーンショットを作成できます。 次の例では、`stepName` の値として `signupForm` を使用してスクリーンショットを作成します。スクリーンショットには ` 02-signupForm-address` という名前が付けられ、Canary レポートで指定された ` signupForm` という名前のステップにリンクされます。 ``` await synthetics.takeScreenshot('signupForm', 'address') ``` ### BrokenLinkCheckerReport クラス このクラスは、Synthetics リンクを追加するメソッドを提供します。これは、`syn-nodejs-2.0-beta` 以降のバージョンのランタイムを使用する Canary でのみサポートされています。 `BrokenLinkCheckerReport` を使用するには、スクリプトに次の行を含めます。 ``` const BrokenLinkCheckerReport = require('@aws/synthetics-broken-link-checker-report'); const brokenLinkCheckerReport = new BrokenLinkCheckerReport(); ``` 有用な関数定義: **addLink(*syntheticsLink*, isBroken)** ` syntheticsLink ` は、リンクを表す ` SyntheticsLink` オブジェクトです。この関数は、ステータスコードに従ってリンクを追加します。デフォルトでは、ステータスコードが利用できない場合、またはステータスコードが 400 以上の場合、リンク切れとみなされます。このデフォルトの動作は、値が `true` または `false` のオプションのパラメータ `isBrokenLink` を渡すことによって上書きできます。 この関数には戻り値がありません。 **getLinks()** この関数は、リンク切れチェッカーレポートに含まれる `SyntheticsLink` オブジェクトの配列を返します。 **getTotalBrokenLinks()** この関数は、リンク切れの総数を表す数値を返します。 **getTotalLinksChecked()** この関数は、レポートに含まれるリンクの総数を表す数値を返します。 **BrokenLinkCheckerReport の使用方法** 次の Canary スクリプトコードスニペットは、リンクに移動して、リンク切れチェッカーレポートに追加する例を示しています。 1. `SyntheticsLink`、`BrokenLinkCheckerReport`、および ` 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. レポートにリンクを追加するには、` BrokenLinkCheckerReport` のインスタンスを作成します。 ``` let brokenLinkCheckerReport = new BrokenLinkCheckerReport(); ``` 1. 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); ``` 1. レポートを Synthetics に追加します。これにより、Canary 実行ごとに S3 バケットに ` BrokenLinkCheckerReport.json` という名前の JSON ファイルが作成されます。コンソールには、各 Canary 実行のリンクレポートと、スクリーンショット、ログ、HAR ファイルを表示できます。 ``` await synthetics.addReport(brokenLinkCheckerReport); ``` ### SyntheticsLink クラス このクラスは、情報をラップするメソッドを提供します。これは、`syn-nodejs-2.0-beta` 以降のバージョンのランタイムを使用する Canary でのみサポートされています。 `SyntheticsLink` を使用するには、スクリプトに次の行を含めます。 ``` const SyntheticsLink = require('@aws/synthetics-link'); const syntheticsLink = new SyntheticsLink("https://www.amazon.com"); ``` この関数は、`syntheticsLinkObject` を返します 有用な関数定義: **withUrl(*url*)** ` url ` は URL 文字列です。この関数は、`syntheticsLinkObject` を返します **withText(*text*)** ` text ` はアンカーテキストを表す文字列です。この関数は `syntheticsLinkObject` を返します。リンクに対応するアンカーテキストを追加します。 **withParentUrl(*parentUrl*)** ` parentUrl ` は、親 (ソースページ) URL を表す文字列です。この関数は、`syntheticsLink Object` を返します **withStatusCode(*statusCode*)** ` statusCode ` は、ステータスコードを表す文字列です。この関数は、`syntheticsLinkObject` を返します **withFailureReason(*failureReason*)** ` failureReason ` は、エラーの理由を表す文字列です。この関数は、`syntheticsLink Object` を返します **addScreenshotResult(*screenshotResult*)** ` screenshotResult ` はオブジェクトです。これは、Synthetics 関数 `ScreenshotResult` によって返された `takeScreenshot` のインスタンスです。このオブジェクトには以下が含まれています。 + `fileName` – ` screenshotFileName` を表す文字列 + `pageUrl` (オプション) + `error` (オプション) ## API Canary のみに適用されるライブラリクラスおよび関数 以下の CloudWatch Synthetics ライブラリ関数は、API Canary についてのみ有用です。 **Topics** + [executeHttpStep(stepName, requestOptions, [callback], [stepConfig])](#CloudWatch_Synthetics_Library_executeHttpStep) ### executeHttpStep(stepName, requestOptions, [callback], [stepConfig]) 提供された HTTP リクエストをステップとして実行し、`SuccessPercent` (pass/fail) および `Duration` メトリクスを発行します。 **executeHttpStep** は、リクエストで指定されたプロトコルに応じて、HTTP または HTTPS ネイティブ関数のいずれかを内部で使用します。 この関数は、Canary のレポートにステップ実行の概要も追加します。概要には、次のような各 HTTP リクエストの詳細が含まれます。 + 開始時間 + 終了時間 + ステータス (PASSED/FAILED) + 失敗の理由 (失敗した場合) + リクエスト/レスポンスヘッダー、本文、ステータスコード、ステータスメッセージ、パフォーマンスタイミングなどの HTTP 呼び出しの詳細。 **Topics** + [パラメータ](#CloudWatch_Synthetics_Library_executeHttpStep_parameters) + [executeHttpStep の使用例](#CloudWatch_Synthetics_Library_executeHttpStep_examples) #### パラメータ **stepName(*文字列*)** ステップの名前を指定します。この名前は、このステップの CloudWatch メトリクスを発行する場合にも使用されます。 **requestOptions(*オブジェクトまたは文字列*)** このパラメータの値には、URL、URL 文字列、またはオブジェクトを指定できます。オブジェクトの場合、HTTP リクエストを行うために設定可能なオプションのセットである必要があります。Node.js ドキュメントの [http.request(options[, callback])](https://nodejs.org/api/http.html#http_http_request_options_callback) のすべてのオプションをサポートしています。 これらの Node.js オプションに加えて、**requestOptions** では、追加のパラメータ `body` がサポートされます。`body` パラメータを使用して、データをリクエスト本文として渡すことができます。 **callback(*レスポンス*)** (オプション) これは HTTP レスポンスで呼び出されるユーザー関数です。レスポンスは、[Class: http.IncomingMessage](https://nodejs.org/api/http.html#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](CloudWatch_Synthetics_Canaries_Samples.md#CloudWatch_Synthetics_Canaries_Samples_APIsteps)」を参照してください。 # Selenium を使用する Python Canary スクリプトで利用可能なライブラリ関数 このセクションでは、Python Canary スクリプトで使用できる Selenium ライブラリ関数の一覧を示しています。 **Topics** + [すべての Canary に適用される Python および Selenium ライブラリクラスおよび関数](#CloudWatch_Synthetics_Library_allcanaries_Python) + [UI Canary のみに適用される Python および Selenium ライブラリクラスおよび関数](#CloudWatch_Synthetics_Library_Python_UIcanaries) ## すべての Canary に適用される Python および Selenium ライブラリクラスおよび関数 以下の Python 用の CloudWatch Synthetics Selenium ライブラリ関数は、すべての Canary について有用です。 **Topics** + [SyntheticsConfiguration クラス](#CloudWatch_Synthetics_Library_SyntheticsConfiguration_Python) + [SyntheticsLogger クラス](#CloudWatch_Synthetics_Library_SyntheticsLogger_Python) ### SyntheticsConfiguration クラス SyntheticsConfiguration クラスを使用して、Synthetics ライブラリ関数の動作を設定できます。例えば、このクラスを使用して、スクリーンショットをキャプチャしないように ` executeStep()` 関数を設定できます。 CloudWatch Synthetics の設定は、グローバルレベルで設定できます。 関数の定義: #### set\$1config(options) ``` from aws_synthetics.common import synthetics_configuration ``` ` options ` はオブジェクトです。これは Canary の設定可能なオプションのセットです。以下のセクションでは、` options ` で使用し得るフィールドについて説明します。 + `screenshot_on_step_start` (ブール値) – ステップを開始する前にスクリーンショットを作成するかどうか。 + `screenshot_on_step_success` (ブール値) – ステップが正常に完了した後にスクリーンショットを作成するかどうか。 + `screenshot_on_step_failure` (ブール値) – ステップが失敗した後にスクリーンショットを作成するかどうか。 **with\$1screenshot\$1on\$1step\$1start(screenshot\$1on\$1step\$1start)** ステップを開始する前にスクリーンショットを作成するかどうかを示すブール値の引数を受け入れます。 **with\$1screenshot\$1on\$1step\$1success(screenshot\$1on\$1step\$1success)** ステップを正常に完了した後にスクリーンショットを作成するかどうかを示すブール値の引数を受け入れます。 **with\$1screenshot\$1on\$1step\$1failure(screenshot\$1on\$1step\$1failure)** ステップが失敗した後にスクリーンショットを作成するかどうかを示すブール値の引数を受け入れます。 **get\$1screenshot\$1on\$1step\$1start()** ステップを開始する前にスクリーンショットを作成するかどうかを返します。 **get\$1screenshot\$1on\$1step\$1success()** ステップを正常に完了した後にスクリーンショットを作成するかどうかを返します。 **get\$1screenshot\$1on\$1step\$1failure()** ステップが失敗した後にスクリーンショットを作成するかどうかを返します。 **disable\$1step\$1screenshots()** スクリーンショットオプション (get\$1screenshot\$1on\$1step\$1start、get\$1screenshot\$1on\$1step\$1success、および get\$1screenshot\$1on\$1step\$1failure) をすべて無効にします。 **enable\$1step\$1screenshots()** スクリーンショットオプション (get\$1screenshot\$1on\$1step\$1start、get\$1screenshot\$1on\$1step\$1success、および get\$1screenshot\$1on\$1step\$1failure) をすべて有効にします。デフォルトでは、これらすべてのメソッドが有効になります。 **CloudWatch メトリクスに関する setConfig (オプション)** `syn-python-selenium-1.1` 以降を使用する Canary の場合、**setConfig** の **(オプション)** には、Canary によって発行されるメトリクスを決定する次のブール値パラメータを含めることができます。これらの各オプションのデフォルトは `true` です。` aggregated` で始まるオプションは、` CanaryName` ディメンションなしでメトリクスを出力するかどうかを決定します。これらのメトリクスを使用して、すべての Canary の集計結果を確認できます。その他のオプションは、`CanaryName` ディメンションを含むメトリクスを出力するかどうかを決定します。これらのメトリクスを使用して、個々の Canary の結果を確認できます。 Canary から発行される CloudWatch メトリクスのリストについては、「[Canary によって発行される CloudWatch メトリクス](CloudWatch_Synthetics_Canaries_metrics.md)」を参照してください。 + `failed_canary_metric` (ブール値) – この Canary の ` Failed` メトリクス (`CanaryName` ディメンションを含む) を出力するかどうか。デフォルトは `true` です。 + `failed_requests_metric` (ブール値) – この Canary の `Failed requests` メトリクス (`CanaryName` ディメンションを含む) を出力するかどうか。デフォルトは `true` です。 + `2xx_metric` (ブール値) – この Canary の `2xx` メトリクス (`CanaryName` ディメンションを含む) を出力するかどうか。デフォルトは `true` です。 + `4xx_metric` (ブール値) – この Canary の `4xx` メトリクス (`CanaryName` ディメンションを含む) を出力するかどうか。デフォルトは `true` です。 + `5xx_metric` (ブール値) – この Canary の `5xx` メトリクス (`CanaryName` ディメンションを含む) を出力するかどうか。デフォルトは `true` です。 + `step_duration_metric` (ブール値) – この Canary の `Step duration` メトリクス (`CanaryName` `StepName` ディメンションを含む) を出力するかどうか。デフォルトは `true` です。 + `step_success_metric` (ブール値) – この Canary の `Step success` メトリクス (`CanaryName` `StepName` ディメンションを含む) を出力するかどうか。デフォルトは `true` です。 + `aggregated_failed_canary_metric` (ブール値) – この Canary の `Failed` メトリクス (`CanaryName` ディメンションを含まない) を出力するかどうか。デフォルト: `true`。 + `aggregated_failed_requests_metric` (ブール値) – この Canary の `Failed Requests` メトリクス (`CanaryName` ディメンションを含まない) を出力するかどうか。デフォルト: `true`。 + `aggregated_2xx_metric` (ブール値) – この Canary の ` 2xx` メトリクス (`CanaryName` ディメンションを含まない) を出力するかどうか。デフォルト: `true`。 + `aggregated_4xx_metric` (ブール値) – この Canary の ` 4xx` メトリクス (`CanaryName` ディメンションを含まない) を出力するかどうか。デフォルト: `true`。 + `aggregated_5xx_metric` (ブール値) – この Canary の ` 5xx` メトリクス (`CanaryName` ディメンションを含まない) を出力するかどうか。デフォルト: `true`。 **with\$12xx\$1metric(2xx\$1metric)** ブール引数を受け入れます。この引数は、この Canary に対して `2xx` ディメンションを持つ `CanaryName` メトリクスを出力するかどうかを指定します。 **with\$14xx\$1metric(4xx\$1metric)** ブール引数を受け入れます。この引数は、この Canary に対して `4xx` ディメンションを持つ `CanaryName` メトリクスを出力するかどうかを指定します。 **with\$15xx\$1metric(5xx\$1metric)** ブール引数を受け入れます。この引数は、この Canary に対して `5xx` ディメンションを持つ `CanaryName` メトリクスを出力するかどうかを指定します。 **withAggregated2xxMetric(aggregated2xxMetric)** ブール引数を受け入れます。この引数は、この Canary に対してディメンションを持たない `2xx` メトリクスを出力するかどうかを指定します。 **withAggregated4xxMetric(aggregated4xxMetric)** ブール引数を受け入れます。この引数は、この Canary に対してディメンションを持たない `4xx` メトリクスを出力するかどうかを指定します。 **with\$1aggregated\$15xx\$1metric(aggregated\$15xx\$1metric)** ブール引数を受け入れます。この引数は、この Canary に対してディメンションを持たない `5xx` メトリクスを出力するかどうかを指定します。 **with\$1aggregated\$1failed\$1Canary\$1metric(aggregated\$1failed\$1Canary\$1metric)** ブール引数を受け入れます。この引数は、この Canary に対してディメンションを持たない `Failed` メトリクスを出力するかどうかを指定します。 **with\$1aggregated\$1failed\$1requests\$1metric(aggregated\$1failed\$1requests\$1metric)** ブール引数を受け入れます。この引数は、この Canary に対してディメンションを持たない `Failed requests` メトリクスを出力するかどうかを指定します。 **with\$1failed\$1canary\$1metric(failed\$1canary\$1metric)** ブール引数を受け入れます。この引数は、この Canary に対して `Failed` ディメンションを持つ `CanaryName` メトリクスを出力するかどうかを指定します。 **with\$1failed\$1requests\$1metric(failed\$1requests\$1metric)** ブール引数を受け入れます。この引数は、この Canary に対して `Failed requests` ディメンションを持つ `CanaryName` メトリクスを出力するかどうかを指定します。 **with\$1step\$1duration\$1metric(step\$1duration\$1metric)** ブール引数を受け入れます。この引数は、この Canary に対して `Duration` ディメンションを持つ `CanaryName` メトリクスを出力するかどうかを指定します。 **with\$1step\$1success\$1metric(step\$1success\$1metric)** ブール引数を受け入れます。この引数は、この Canary に対して `StepSuccess` ディメンションを持つ `CanaryName` メトリクスを出力するかどうかを指定します。 ##### メトリクスを有効または無効にする方法 **disable\$1aggregated\$1request\$1metrics()** Canary が ` CanaryName` ディメンションなしで出力されるすべてのリクエストメトリクスを出力するのを無効にします。 **disable\$1request\$1metrics()** Canary ごとのメトリクスとすべての Canary で集計されたメトリクスの両方を含む、すべてのリクエストメトリクスを無効にします。 **disable\$1step\$1metrics()** ステップ成功メトリクスとステップ期間メトリクスの両方を含む、すべてのステップメトリクスを無効にします。 **enable\$1aggregated\$1request\$1metrics()** Canary が ` CanaryName` ディメンションなしで出力されるすべてのリクエストメトリクスを送信できるようにします。 **enable\$1request\$1metrics()** Canary ごとのメトリクスとすべての Canary で集計されたメトリクスの両方を含む、すべてのリクエストメトリクスを有効にします。 **enable\$1step\$1metrics()** ステップ成功メトリクスとステップ期間メトリクスの両方を含む、すべてのステップメトリクスを有効にします。 **UI Canary での使用** まず、Synthetics 依存関係をインポートし、設定を取得します。次に、以下のいずれかのオプションを使用して setConfig メソッドを呼び出すことで、各オプションの設定を行います。 ``` 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 ``` または ``` synthetics_configuration.with_screenshot_on_step_start(False).with_screenshot_on_step_success(False).with_screenshot_on_step_failure(True) ``` すべてのスクリーンショットを無効にするには、次の例のように disableStepScreenshots() 関数を使用します。 ``` synthetics_configuration.disable_step_screenshots() ``` コード内の任意の個所でスクリーンショットを有効または無効にすることができます。例えば、1 つのステップでのみスクリーンショットを無効にするには、そのステップを実行する前にスクリーンショットを無効にしてステップの実行後に有効にします。 ##### UI Canary の set\$1config(options) `syn-python-selenium-1.1` から始まり、UI Canary については、` set_config` は次のブールパラメータを含めることができます。 + `continue_on_step_failure` (ブール値) – ステップが失敗した後も Canary スクリプトの実行を続行するかどうか (これは **executeStep** 関数を参照します)。いずれかのステップが失敗しても、Canary 実行は失敗としてマークされます。デフォルト: `false`。 ### SyntheticsLogger クラス `synthetics_logger` は、コンソールと、同じログレベルのローカルログファイルの両方にログを書き込みます。このログファイルは、ログレベルが、呼び出されたログ関数の該当するログ記録レベル以下である場合にのみ、両方の場所に書き込まれます。 ローカルログファイルのログ記録ステートメントには、呼び出された関数のログレベルに合わせて「DEBUG:」や「INFO:」などが先頭に追加されます。 Amazon S3 の結果の場所にアップロードされるログファイルを作成する場合、`synthetics_logger` を使用する必要はありません。代わりに、別のログファイルを `/tmp` フォルダ内に作成できます。`/tmp` フォルダ内に作成したファイルは、アーティファクトとして S3 バケットの結果の場所にアップロードされます。 `synthetics_logger` を使用するには: ``` from aws_synthetics.common import synthetics_logger ``` ****有用な関数定義: ログレベルの取得: ``` log_level = synthetics_logger.get_level() ``` ログレベルの設定: ``` synthetics_logger.set_level() ``` 指定されたレベルでメッセージをログ記録します。レベルは、次の構文の例に示すように、`DEBUG`、` INFO`、`WARN`、または `ERROR` とすることができます。 ``` 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) ``` デバッグパラメータの詳細については、[logging.debug](https://docs.python.org/3/library/logging.html#logging.debug) の標準 Python ドキュメントをご参照ください。 これらのロギング関数では、`message` はメッセージフォーマット文字列です。`args` は、文字列フォーマット演算子を使用して `msg` にマージされる引数です。 `kwargs` には、次の 3 つのキーワード引数があります。 + `exc_info` – false と評価されない場合、ログメッセージに例外情報を追加します。 + `stack_info` – デフォルト設定は false です。true の場合、実際のロギング呼び出しを含むスタック情報をロギングメッセージに追加します。 + `extra` – 3 番目のオプションのキーワード引数。ロギングイベント用に作成された `LogRecord` の `__dict__` を設定するために使用されるディクショナリでユーザー定義属性を渡すために使用できます。 例: レベル `DEBUG` のメッセージをログに記録します: ``` synthetics_logger.debug('Starting step - login.') ``` レベル `INFO` のメッセージをログに記録します。`logger.log` は `logger.info` のシノニムです: ``` synthetics_logger.info('Successfully completed step - login.') ``` または ``` synthetics_logger.log('Successfully completed step - login.') ``` レベル `WARN` のメッセージをログに記録します: ``` synthetics_logger.warning('Warning encountered trying to publish %s', 'CloudWatch Metric') ``` レベル `ERROR` のメッセージをログに記録します: ``` synthetics_logger.error('Error encountered trying to publish %s', 'CloudWatch Metric') ``` 例外をログに記録します。 ``` synthetics_logger.exception(message, *args, **kwargs) ``` レベル `ERROR` のメッセージをログに記録します。例外情報は、ロギングメッセージに追加されます。この関数は、例外ハンドラからのみ呼び出す必要があります。 例外パラメータの詳細については、[logging.exception](https://docs.python.org/3/library/logging.html#logging.exception) の標準 Python ドキュメントをご参照ください `message` はメッセージフォーマット文字列です。`args` は引数で、文字列フォーマット演算子を使用して `msg` にマージされます。 `kwargs` には、次の 3 つのキーワード引数があります。 + `exc_info` – false と評価されない場合、ログメッセージに例外情報を追加します。 + `stack_info` – デフォルト設定は false です。true の場合、実際のロギング呼び出しを含むスタック情報をロギングメッセージに追加します。 + `extra` – 3 番目のオプションのキーワード引数。ロギングイベント用に作成された `LogRecord` の `__dict__` を設定するために使用されるディクショナリでユーザー定義属性を渡すために使用できます。 例: ``` synthetics_logger.exception('Error encountered trying to publish %s', 'CloudWatch Metric') ``` ## UI Canary のみに適用される Python および Selenium ライブラリクラスおよび関数 以下の Python 用の CloudWatch Synthetics Selenium ライブラリ関数は、UI Canary についてのみ有用です。 **Topics** + [SyntheticsBrowser クラス](#CloudWatch_Synthetics_Library_Python_SyntheticsBrowser) + [SyntheticsWebDriver クラス](#CloudWatch_Synthetics_Library_Python_SyntheticsWebDriver) ### SyntheticsBrowser クラス **注記** `SyntheticsBrowser` は Chrome ブラウザでのみサポートされています。 `synthetics_webdriver.Chrome()` を呼び出してブラウザインスタンスを作成すると、返されるブラウザインスタンスのタイプは `SyntheticsBrowser` となります。` SyntheticsBrowser` クラスは WebDriver クラスを継承し、[WebDriver](https://www.selenium.dev/documentation/webdriver/) によって公開されるすべてのメソッドへのアクセスを提供します。このクラスは ChromeDriver を制御し、Canary スクリプトがブラウザを駆動できるように設定し、Selenium WebDriver が Synthetics で動作できるようにします。 **注記** Synthetics は WebDriver [quit](https://www.selenium.dev/selenium/docs/api/py/selenium_webdriver_firefox/selenium.webdriver.firefox.webdriver.html) メソッドをオーバーライドし、何もアクションを実行しません。ブラウザの終了については、Synthetics が自動で処理するため心配する必要はありません。 標準的な Selenium メソッドに加えて、以下のメソッドも提供します。 **Topics** + [set\$1viewport\$1size (幅、高さ)](#CloudWatch_Synthetics_Library_set_viewport_size) + [save\$1screenshot(ファイル名, サフィックス)](#CloudWatch_Synthetics_Library_save_screenshot) #### set\$1viewport\$1size (幅、高さ) ブラウザのビューポートを設定します。例: ``` browser.set_viewport_size(1920, 1080) ``` #### save\$1screenshot(ファイル名, サフィックス) スクリーンショットを `/tmp` ディレクトリに保存します。スクリーンショットは、そこから S3 バケットの Canary アーティファクトフォルダにアップロードされます。 *filename* はスクリーンショットのファイル名で、*suffix* はスクリーンショットの命名に使用されるオプションの文字列です。 例: ``` browser.save_screenshot('loaded.png', 'page1') ``` ### SyntheticsWebDriver クラス このクラスを使用するには、スクリプトで以下を使用します。 ``` 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); `errorMessage` はエラーの詳細を示し、`ex` は発生した例外を示します `add_execution_error` を使用すると、Canary の実行エラーを設定できます。これにより、スクリプトの実行を中断することなく Canary を失敗させることができます。また、`successPercent` メトリクスにも影響を与えません。 Canary スクリプトの成功または失敗を確認するために重要でない場合にのみ、エラーを実行エラーとして追跡するようにします。 `add_execution_error` の使用例を次に示します。ここでは、エンドポイントの可用性をモニターリングしながら、ページが読み込まれた後にスクリーンショットを取得しています。スクリーンショットの作成に失敗したとしても、エンドポイントの可用性が判断されるわけではないため、スクリーンショットの作成中に発生したすべてのエラーは、キャッチした上で実行エラーとして追加します。可用性に関するメトリックスには、依然としてエンドポイントが起動し実行中であることが示されていますが、Canary のステータスは失敗としてマークされています。次に示すコードブロックのサンプルでは、このようなエラーをキャッチし、実行エラーとして追加します。 ``` 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) `user_agent_str` の値をブラウザのユーザーエージェントヘッダーに追加します。ブラウザインスタンスを作成する前に、`user_agent_str` を割り当てる必要があります。 例: ``` await synthetics_webdriver.add_user_agent('MyApp-1.0') ``` `add_user_agent` は `async` 関数内で使用する必要があります。 #### execute\$1step(step\$1name, function\$1to\$1execute) 1 つの関数を処理します。また、次の操作も行います。 + ステップが開始されたことをログに記録します。 + `-starting` という名前でスクリーンショットを作成します。 + タイマーを開始します。 + 指定された関数を実行します。 + 関数が正常に戻ると、合格としてカウントします。関数がスローされると、失敗としてカウントします。 + タイマーを終了します。 + ステップが合格したか失敗したかをログに記録します。 + `-succeeded` や ` -failed` という名前でスクリーンショットを作成します。 + `stepName` `SuccessPercent` メトリクスを出力します。合格の場合は 100、不合格の場合は 0 です。 + `stepName` `Duration` メトリクスを出力します。値は、ステップの開始時刻と終了時刻に基づきます。 + 最後に、`functionToExecute` から返された内容を返し、`functionToExecute` からスローされた内容を再スローします。 例: ``` 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) 指定された URL に HTTP リクエストを行い、HTTP リクエストのレスポンスコードを返します。HTTP リクエスト中に例外が発生した場合は、代わりに「error」という値を持つ文字列が返されます。 例: ``` 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() Chromium ブラウザのインスタンスを起動し、作成したブラウザインスタンスを返します。 例: ``` browser = synthetics_webdriver.Chrome() browser.get("https://example.com/) ``` シークレットモードでブラウザを起動するには、次を使用します。 ``` add_argument('——incognito') ``` プロキシ設定を追加するには、次を使用します。 ``` add_argument('--proxy-server=%s' % PROXY) ``` 例: ``` from selenium.webdriver.chrome.options import Options chrome_options = Options() chrome_options.add_argument("——incognito") browser = syn_webdriver.Chrome(chrome_options=chrome_options) ``` # cron を使用して Canary 実行をスケジュールする cron 式を使用すると、Canary のスケジュールを柔軟に立てることができます。cron 式には、次の表に示す順序で 5 つまたは 6 つのフィールドが含まれています。フィールドはスペースで区切ります。構文は、CloudWatch コンソールを使用して Canary を作成するか、AWS CLI または AWS SDK を使用するかによって異なります。コンソールを使用する場合は、最初の 5 つのフィールドのみを指定します。AWS CLI または AWS SDK を使用する場合は、6 つのフィールドをすべて指定し、`Year` フィールドに `*` を指定する必要があります。 | **フィールド** | **許可される値** | **使用できる特殊文字** | | --- | --- | --- | | 分 | 0-59 | , - \$1 / | | 時間 | 0-23 | , - \$1 / | | 日 | 1-31 | , - \$1 ? / L W | | 月 | 1-12 または JAN-DEC | , - \$1 / | | 曜日 | 1-7 または SUN-SAT | , - \$1 ? L \$1 | | 年 | \$1 | | **特殊文字** + **, ** (カンマ) は、フィールドの式に複数の値を含めます。例えば、[月] フィールドの、「JAN,FEB,MAR」は、1 月、2 月、3 月を含みます。 + 特殊文字 **-** (ダッシュ) は、範囲を指定します。日フィールドの、「1-15」は、指定した月の 1 日から 15 日を含みます。 + **\$1** (アスタリスク) 特殊文字には、フィールド内のすべての値が含まれます。[時間] フィールドの **\$1** には すべての時間が含まれます。同じ式で、[日] フィールドと [曜日] フィールドの両方で **\$1** を使用することはできません。一方に使用する場合は、もう一方に [**?**] を使用する必要があります。 + **/** (スラッシュ) は増分を指定します。[分] フィールドに 1/10 と入力して、時間の最初の分から開始して 10 分おきを指定できます (例えば、11 分、21 分、31 分など)。 + **?** (疑問符) は、任意を意味します。[日] フィールドに **7** と入力し、7 番目の曜日がどの曜日か気にしない場合は、**?**を [曜日] フィールドに入力します。 + Day-of-month フィールドまたは Day-of-week フィールドの、ワイルドカード **L** は月または週の最終日を指定します。 + Day-of-month フィールドのワイルドカード **W** は、平日を指定します。Day-of-month フィールドで、**3W** は月の 3 日目に最も近い平日を指定します。 + Day-of-week フィールドの **\$1** ワイルドカードは、月の指定された曜日の特定のインスタンスを指定します。例えば、3\$12 は月の第 2 火曜日です。3 は毎週の 3 日目であるため、火曜日を指し、2 は月内のその種類の 2 つ目を指します。 **制限事項** + cron 式の日フィールドと曜日フィールドを同時に指定することはできません。一方のフィールドに値または `*` (アスタリスク) を指定する場合、もう一方のフィールドで **?** (疑問符) を使用する必要があります。 + 1 分より短い間隔を導き出す cron 式はサポートされていません。 + 実行前に 1 年以上待つように Canary を設定することはできないため、[`Year`] フィールドでは `*` のみ指定することができます。 **例** Canary を作成するときは、次のサンプルの cron 文字列を参照できます。以下の例は、AWS CLI または AWS SDK を使用して Canary を作成または更新するための正しい構文です。CloudWatch コンソールを使用している場合は、各例の最後の 「`*`」を省略します。 | 式 | 意味 | | --- | --- | | `0 10 * * ? *` | 毎日午前 10:00 (UTC) に実行 | | `15 12 * * ? *` | 毎日午後 12:15 (UTC) に実行 | | `0 18 ? * MON-FRI *` | 毎週月曜日から金曜日まで午後 6:00 (UTC) に実行 | | `0 8 1 * ? *` | 毎月初日の午前 8:00 (UTC) に実行 | | `0/10 * ? * MON-SAT *` | 毎週月曜日から土曜日まで 10 分ごとに実行 | | `0/5 8-17 ? * MON-FRI *` | 月曜日から金曜日まで午前 8:00 から午後 5:55 (UTC) まで 5 分ごとに実行 | # Canary を自動的に再試行するように設定する Canary を作成または更新するときに、スケジュールされた実行が失敗しても自動的に再試行するように Canary を設定できます。これにより、実際の障害と一時的な不具合を区別でき、実行結果の信頼性が高まります。この機能はアラームの誤検知や手動での介入を減らしつつ、より回復力の高いモニタリングシステムを構築するのに最適です。 **自動的に再試行する Canary を作成する方法** 1. CloudWatch コンソールの [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) を開いてください。 1. ナビゲーションペインで、**[Application Signals]**、**[Synthetics Canary]** の順に選択します。 1. **[Canary を作成]** を選択します。 1. **[追加設定]** の **[自動再試行]** で、再試行の最大数を選択します。 **Canary の再試行の最大数を変更する方法** 1. CloudWatch コンソールの [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) を開いてください。 1. ナビゲーションペインで、**[Application Signals]**、**[Synthetics Canary]** の順に選択します。 1. 次のいずれかを試すことができます。 + 対象の Canary を選択し、**[アクション]**、**[自動再試行を有効にする]** の順に選択して、再試行の最大数を調整します。 + 対象の Canary を選択して、**[アクション]**、**[編集]** の順に選択します。**[詳細を編集]** ページで **[追加設定]**、**[自動再試行]** の順に選択し、再試行設定を調整します。 **制限事項** 自動再試行を設定するにあたっては、次の制限があります。 + ランタイムバージョン `syn-nodejs-puppeteer-10.0 ` 以降、` syn-nodejs-playwright-2.0` 以降、`syn-python-selenium-5.1` 以降、または `syn-nodejs-3.0` 以降でのみサポートされます。 + タイムアウトが 10 分後という長時間にわたる Canary 実行では、1 度しか再試行できません。それ以外のすべての Canary は、最大 2 回の再試行に対応しています。 # CloudWatch Synthetics Canary での依存関係の使用 このセクションでは、CloudWatch Synthetics Canary で `Dependencies` を使用する方法について説明します。`Dependencies` フィールドを使用すると、Canary の依存関係を指定でき、Canary スクリプトで使用できる追加のライブラリまたはカスタムコードを含めることができます。 ## 概要: CloudWatch Synthetics Canary では、依存関係としての Lambda レイヤーの指定をサポートしています。この機能を使用すると、次のことができます。 + 複数の Canary 間で共通コードを共有する + Canary スクリプトコードとは別に依存関係を管理する + 依存関係を Lambda レイヤーに移動して Canary スクリプトのサイズを小さくする ## サポートされている API `Dependencies` フィールドは、次の API でサポートされています。 + [CreateCanary](https://docs.aws.amazon.com/AmazonSynthetics/latest/APIReference/API_CreateCanary.html) + [UpdateCanary](https://docs.aws.amazon.com/AmazonSynthetics/latest/APIReference/API_UpdateCanary.html) + [StartCanaryDryRun](https://docs.aws.amazon.com/AmazonSynthetics/latest/APIReference/API_StartCanaryDryRun.html) ## 構文 `Dependencies` フィールドは、リクエスト構文のコード構造の一部です。 ``` "Code": { "Handler": "string", "S3Bucket": "string", "S3Key": "string", "S3Version": "string", "ZipFile": blob, "Dependencies": [ { "Type": "LambdaLayer", "Reference": "string" } ] } ``` ## 依存関係の使用 さまざまなシナリオでの `Dependencies` フィールドの使用例と手順をいくつか示します。 ### 依存関係を使用した Canary の作成 Canary を作成するときに、依存関係として Lambda レイヤーを指定できます。 ``` { "Name": "my-canary", "Code": { "Handler": "pageLoadBlueprint.handler", "S3Bucket": "my-bucket", "S3Key": "my-canary-script.zip", "Dependencies": [ { "Type": "LambdaLayer", "Reference": "arn:aws:lambda:us-west-2:123456789012:layer:my-custom-layer:1" } ] }, "ArtifactS3Location": "s3://my-bucket/artifacts/", "ExecutionRoleArn": "arn:aws:iam::123456789012:role/my-canary-role", "Schedule": { "Expression": "rate(5 minutes)" }, "RuntimeVersion": "syn-nodejs-puppeteer-3.9" } ``` ### Canary の依存関係の更新 UpdateCanary API を使用して Canary の依存関係を更新できます。 ``` { "Name": "my-canary", "Code": { "Dependencies": [ { "Type": "LambdaLayer", "Reference": "arn:aws:lambda:us-west-2:123456789012:layer:my-updated-layer:2" } ] } } ``` ### 依存関係の削除 Canary から依存関係を削除するには、Dependencies フィールドに空の配列を指定します。 ``` { "Name": "my-canary", "Code": { "Dependencies": [] } } ``` ### StartCanaryDryRun による依存関係のテスト 新しい依存関係により Canary を更新する前に、StartCanaryDryRun API を使用してテストできます。 ``` { "Name": "my-canary", "Code": { "Dependencies": [ { "Type": "LambdaLayer", "Reference": "arn:aws:lambda:us-west-2:123456789012:layer:my-test-layer:3" } ] } } ``` ## 制約事項と考慮事項 + 依存関係として指定できる Lambda レイヤーは 1 つだけです。 + 依存関係を持つ Canary の作成に使用するロールには、[必要なロールとアクセス許可](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_Roles.html)に加えて、依存関係レイヤーへの ` lambda:GetLayerVersion` アクセス権が必要です。 ## 互換性のある Lambda レイヤーの作成 レイヤーの作成とパッケージ化の方法については、「[レイヤーによる Lambda 依存関係の管理](https://docs.aws.amazon.com/lambda/latest/dg/chapter-layers.html)」を参照してください。また、Canary パッキング構造に基づく Canary チェックのパッケージ構造については、「[Canary スクリプトの作成](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_WritingCanary.html)」を参照してください。