Amazon Connect AIエージェントのログ調査で確認すべき3つのログを CloudWatch Logs Insights で取得する方法
はじめに
Amazon Connect AIエージェントを使っていると、想定した分岐に進まない、AIエージェントが意図しない応答を返す、Lex 側では認識できていそうなのに最終的な挙動が合わない、といった形で調査が必要になることがあります。
こうした事象は、Amazon Connect のフロー、Amazon Connect AIエージェント、Amazon Lex が連携して動作するため、どこで期待した結果とずれたのかを切り分けるには、それぞれのログを確認するのが重要です。
また、事象の切り分けを進める中で、AWS サポートに問い合わせる場合にも、関連ログの確認や取得が必要になることがあります。
そのため、コンタクトIDを起点に必要なログを素早く取り出せるようにしておくと、日々の調査でも問い合わせ時でも役立ちます。
その際に確認したい主なログは、以下の3つです。
- Amazon Connect フローログ
- Amazon Connect AIエージェントログ
- Amazon Lex テキストログ
今回は、これら3つのログを Amazon CloudWatch Logs Insights で取得する方法を紹介します。
前提条件
事前に以下の設定が完了している前提です。
Amazon Connect AIエージェントログの出力方法
Amazon Lex のテキストログ出力方法と見方
Amazon Connect フローログの有効化方法
コンタクトIDは、コンタクト検索から取得済みとします。今回は fcaa9763-5b96-42e5-a779-36afed45b254 を例にします。
また、コンタクトの日付もあわせて確認しておきます。CloudWatch Logs Insights では時間範囲の指定が重要なので、先に把握しておくと調査しやすくなります。
CloudWatch Logs Insights
CloudWatch Logs Insights を利用するため、CloudWatch のログのインサイトページに遷移します。
以降は、対象のロググループを選択し、時間範囲を設定したうえでクエリを実行します。
Amazon Connect フローログ
まずは Amazon Connect フローログです。
Amazon Connect のフローログには、ログエントリに対応するブロックの情報、コンタクトID、ブロック完了後に実行された内容などが含まれます。
また、Lex や Lambda をフロー内で利用している場合、その入出力に関する情報もフローログに含まれます。
時間範囲を設定し、対象のロググループを選択したうえで、以下のクエリを実行します。
fields @timestamp, @message
| filter ContactId = "fcaa9763-5b96-42e5-a779-36afed45b254"
| sort @timestamp asc
実行後は、[結果をエクスポート] から [テーブルをダウンロード (CSV)] を選ぶことで、CSV形式で出力できます。
なお、AWS ドキュメントでは、CloudWatch Logs のロググループ画面から、ロググループ全体を文字列検索する方法も紹介されています。
たとえば、コンタクトIDの全部または一部を検索ボックスに入力して、該当イベントを探す方法です。
コンタクト数が少ない環境ではこの方法でも確認できますが、コンタクト数が多い場合は CloudWatch Logs Insights で絞り込むほうが扱いやすいです。
Amazon Connect AIエージェントログ
次に Amazon Connect AIエージェントログです。
Amazon Connect AIエージェントの CloudWatch ログでは、session_name と session_id を使ってセッションを追えます。
session_id は Connect AIエージェントセッションの一意な識別子で、AWS ドキュメントでも session_name や session_id を使ったクエリ例が案内されています。
AIエージェントログでは、session_name にコンタクトIDが入り、session_id がそのセッションに紐づく共通の識別子になります。
そのため、まず session_name から session_id を取得し、その後に session_id を使って対象ログ全体を取得します。
時間範囲を設定し、対象のロググループを選択したうえで、まず以下のクエリを実行します。
fields @timestamp, event_type, session_id
| filter session_name = "fcaa9763-5b96-42e5-a779-36afed45b254"
| sort @timestamp asc
| limit 20
実行すると session_id が確認できます。今回の例では、取得した session_id を次のクエリで使います。
続いて、取得した session_id を指定して、以下のクエリを実行します。
fields @timestamp, @message
| filter session_id = "8a64514b-81fa-49af-b0cc-f042350d65a9"
| sort @timestamp asc
こちらも、[結果をエクスポート] から [テーブルをダウンロード (CSV)] を選ぶことで、CSV形式で出力できます。
Amazon Connect AIエージェントログは、1つのログストリーム内に複数コンタクトのログが出力されるため、そのままログストリームを眺めるとかなり見にくいです。
そのため、ログストリーム単位で追うのではなく、CloudWatch Logs Insights で session_name や session_id を使って絞り込む方法が調査しやすいです。
なお、ログフィールドの定義は以下にまとまっています。
Amazon Lex のログ
最後に Amazon Lex のテキストログです。
Amazon Lex V2 のテキストログには、sessionId、inputTranscript、messages、requestId、sessionState などが含まれます。
CloudWatch Logs には、ユーザーの発話ごとにこうした情報が記録されるため、どの入力に対してどの応答が返されたかを追いやすいです。
時間範囲を設定し、対象のロググループを選択したうえで、以下のクエリを実行します。
fields @timestamp, @message
| filter sessionId = "fcaa9763-5b96-42e5-a779-36afed45b254"
| sort @timestamp asc
Lex のログは、今回のような Amazon Connect 連携の構成では sessionId とコンタクトIDを対応づけて調査できます。
そのため、コンタクトIDが分かっていれば、比較的素直に対象のやり取りを追うことができます。
なお、ログフィールドの定義は以下にまとまっています。
料金
CloudWatch Logs Insights は従量課金なので、利用時は料金に注意してください。
CloudWatch の料金ページでは、無料利用枠として、毎月 5 GB のデータが Logs Insights クエリによるスキャン対象として含まれています。
また、東京リージョンの Logs Insights クエリ料金として、スキャンしたデータ 1 GB あたり 0.005 USD と案内されています。
そのため、クエリ実行時は時間範囲を必要最小限に絞ることが重要です。
事前にコンタクトの日付や時刻を確認しておくことで、より少ないスキャン量で効率よく調査できます。
まとめ
今回は、Amazon Connect AIエージェントの調査でよく確認する以下3つのログを、コンタクトIDを起点に CloudWatch Logs Insights で取得する方法を整理しました。
- Amazon Connect フローログ
- Amazon Connect AIエージェントログ
- Amazon Lex テキストログ
同じコンタクトに対して、フローログ、AIエージェントログ、Lexログをあわせて確認することで、どこで想定と異なる動作になったのかを切り分けしやすくなります。
