AWSサービスの監視通知やイベント駆動システムでは、Amazon EventBridgeルール*1を使ってイベント発生を検知して処理を実行していると思います。
Amazon EventBridgeルールを作成する機会が多くなっているので、設定をデバッグするときに役に立つ情報を紹介します。
EventBridge ルールの概要
こちらの図はAWSのAmazon EventBridge製品サイト（https://aws.amazon.com/jp/eventbridge/）から引用したものです。
AWSサービスなどのイベントソースからEventBusに送られたイベントは、EventBridgeルールによって、ターゲットとなるサービスに渡されます。
EventBridgeルールには、イベントパターンとターゲットのふたつの設定があります。
イベントパターンでは、EventBusから特定のイベントを抽出するためのマッチングパターンを設定します。ターゲットでは、対象のイベントを検知したときに実行する処理を指定します。
ターゲットにはEventBridgeの連携をサポートしているAWSサービスを指定でき、LambdaやStepFunctions、ECSタスクを実行したり、SNSでイベント発生を通知できます。ターゲットの対象はAWSサービスだけではなく、外部APIの呼び出しや、ほかのアカウントやリージョンのEventBusを指定してイベントを転送することもできます。
また、ひとつのイベントパターンに対して複数のターゲットを指定することができるので、Pub/Subメッセージング機能として利用でがきます。
EventBridgeルールのデバッグでは、想定通り動作しない原因がイベントパターンなのかターゲットなのかを切り分けていく必要があります。
イベントのサンプルを手に入れる
マネジメントコンソールのイベントパターン作成画面は、ユーザーをサポートする機能が充実しており、複雑な条件を必要としないルールであれば、UIに沿ってポチポチと選択していくだけで簡単にイベントパターンを作ることができます。
AWSの各サービスが発生させるイベントサンプルを生成する機能が用意されていて、作成したイベントパターンを、このサンプルを使って画面上からテストできます。
CloudFormationなどのIaCツールを使ってリソースを管理している場合でも、まずはマネジメントコンソールを使ってたたき台を作ってからコードに落とし込むことをオススメします。
ドキュメントでイベントフォーマットを調べる
イベントパターンでEventBusから取り出すイベントの条件を細かく設定する場合は、イベントのフォーマットや、項目が取りうる値を把握する必要があります。
イベントの基本的なフォーマットは以下のドキュメントに記載があります。
source や detail-type 、detailなどのフィールドで条件指定してフックしたいイベントを絞り込みます。
サービスごとにどのようなイベントが発生するかは、以下のドキュメントから各サービスのイベント項目のドキュメントをだどれるようになっています。
このドキュメントにサービス以外でも、各サービスのドキュメントでEventのサンプルが記載されている場合があります。
マネジメントコンソールで確認できるサンプルイベントがドキュメントで解説されている場合があるので、サンプルの "id" や "detail-type" でドキュメントを検索してみることをオススメします。
実際のイベントをCloudWatchLogsに記録する
CloudWatchログにイベントパターンで検出したイベントを記録しておくことで、狙ったイベントをフィルタできているかを簡単に確認できます。
CloudWatchログに記録するには、ターゲットに「CloudWatchロググループ」を指定してルールを作成するだけです。
トリガーとなる処理を実行して、CloudWatchログにイベントが記録されていれば、イベントパターンを正しく設定できていることがわかります。
イベントパターンを作成するときに、sourceやdetail-typeフィールドの値は名前から予想がつきやすいですが、さらに細かい条件を追加するためにはdetailでの条件付けが必要になります。
最初はイベントパターンsourceやdetail-typeでだけ指定して、記録された実際のイベントから条件を絞っていくと目的のイベントパターンが作成しやすいです。
また、記録された実際のイベントメッセージは、EventBridgeのデバッグだけではなくLambdaの実装やテスト等にも役立つかと思います。
CloudWatchメトリクスを確認する
EventBridgeルールが想定通りに動いていないときには、CloudWatchメトリクスを使って問題点を切り分けできます。
| メトリクス | 説明 |
|---|---|
| TriggeredRules | イベントパターンの条件に合致した回数 |
| FailedInvocations | ターゲットの実行に失敗した回数 |
TriggeredRules がカウントされていない場合、イベントパターンの設定に誤りがあるか、イベント自体が発生していない可能性があります。
上記で紹介したイベントパターンのデバッグ方法を参考にして、イベントパターンの修正をしてください。
イベントパターンの条件を緩くしているのにイベントが記録されない場合は、イベントが発生しない操作の可能性があります。対象サービスのドキュメントでイベントの調査したりAWSサポートへ仕様を問い合わせる必要があります。
FailedInvocationsがカウントされている場合、イベントパターンによるフィルタには成功しているが、ターゲットを実行しようとして失敗していることがわかります。ターゲット実行のデバッグについてはこの後紹介します。
そのほかのEventBridgeメトリクスは以下から確認できます。
デッドレターキューを設定する
ターゲットの実行に失敗している場合、調査の手がかりとしてエラーコードやメッセージを確認する必要があります。
各ターゲットの「デッドレターキュー」を設定することで、原因を調査するための情報を確認できるようになります。
デッドレターキューはターゲットに正常に配信できなかったイベントを保存するための機能です。
詳しくは以下のドキュメントで解説されています。
ターゲットの設定に追加する「デッドレターキュー」の実体は、SQSに作成したキューです。
デッドレターキューを設定するためには、SQSキューを事前に作成します。作成するキューは標準キューである必要があります。
SQSにもデッドレターキューという同じ名前の機能がありますが、EventBridgeルールのデッドレターキューとは無関係なので、作成するキューに設定する必要はありません。
EventBridgeルールのターゲット設定にある「再試行ポリシーとデッドレターキュー」で、作成したキューを指定してルールを保存します。
イベントが発生する操作を行い、ターゲットのinvocationに失敗したらSQSの管理画面からキューに入ってるメッセージを確認します。
キューに記録されたメッセージの「属性」にターゲット実行のエラー情報が記録されていることがわかります。
この図のではERROR_CODEとERROR_MESSAGEから、ターゲットに送信しようとしたイベントメッセージのjsonフォーマットが原因で失敗しているとわかります。
キューに記録されたメッセージの「本文」でターゲットに送信しようとした文字列が確認できます。
この例に利用したEventBridgeルールは、発生したイベントメッセージを入力トランスフォーマ機能で整形して、ターゲットの外部APIに送信するものでした。
送信するデータを整形する設定の誤りでjsonフォーマットが崩れていたため、このエラーメッセージが発生していました。
AWSのサービスと連携している場合は、実行権限のエラーや対象リソースが見つからないなどのエラーが想定されます。先ほど記載したデッドレターキューのドキュメントにERROR_CODEのサンプル値がが紹介されているので参考にしてみてください。
まとめ
EventBridgeルールはAWSのサービス連携の要となるサービスで、クラウドネイティブなシステム設計をする場合、必ずといっていいほど利用します。
フルマネージドな仕組みで、マネージメントコンソールから簡単にルールを作れるように管理機能が充実している一方、開発・運用で調査に必要な情報がデフォルトのままでは取得することができません。
今回紹介した内容が、より効率的で安定したEventBridgeルールの開発・運用に役立てば幸いです。
AWSへの機能要望としては、簡単にデバッグ用のイベントを発生させて、フィルタからターゲット実行までの動作確認をしやすくするような機能が欲しいですね。
*1:EventBridgeルールの機能はCloudWatchで提供されていた経緯があるため、CloudWatch Eventsと記載される場合があります
