Amazon Connect でのコンタクトフローエラーをトラブルシューティングするにはどうすればよいですか?

簡単な説明

コンタクトフローエラーのトラブルシューティングに関するチュートリアルについては、「Troubleshooting contact flow errors in Amazon Connect」(Amazon Connect でのコンタクトフローエラーのトラブルシューティング) ワークショップを参照してください。

コンタクトフローを調査してトラブルシューティングするには、以下の前提条件を満たす必要があります。

コンタクトフローログ

フローログを有効にします。コンタクトフローログを使用して、コールがコンタクトフローの異なるブロックを通過する方法を理解します。また、障害をトラブルシューティングし、エラーが発生する場所を特定するためにもコンタクトフローログを使用します。

コンタクトフローのエクスポート

フローのエクスポート手順については、「フローのインポート/エクスポート方法」を参照してください。

エクスポートを使用して、コンタクトフローに関する理解を深めます。

• コールがフローを通過する方法を確認する。
• コンタクトフローログを関連付ける。
• サンドボックス環境で問題を再現する。

Amazon Connect 向けの Amazon CloudWatch メトリクス

詳細については、「CloudWatch を使用したインスタンスのモニタリング」を参照してください。

コンタクトフローに関連するイベントのモニタリングとトラブルシューティングには、ContactFlowErrors および ContactFlowFatalError メトリクスを使用します。

• ContactFlowFatalError メトリクスは、システムエラーが原因でフローの実行が失敗した回数を示します。例えば、Amazon Connect の障害などです。
• ContactFlowErrors メトリクスは、コンタクトフローのエラーブランチが実行される回数を示します。

コンタクトフローエラーをトラブルシューティングするには、CloudWatch Logs Insights をクエリして、コンタクトフローのどのブロックがエラーブランチをたどっているかを特定します。その後、そのブロックを使用してエラーの根本的な原因を特定します。

解決方法

まず、クエリを実行して関連するエラーイベントを確認します。

1.    Amazon CloudWatch コンソールを開きます。

2.    ナビゲーションペインで [Logs Insights] (ログのインサイト) を選択します。

3.    Amazon Connect インスタンスログのロググループの名前を選択します。形式は /aws/connect/yourinstancename です。

4.    右上隅で、クエリのタイムスケールを指定します。

5.    特定の時間範囲について、以下のクエリを実行します。

fields @timestamp, @message
| filter @message like 'Results'
| parse @message '"Results":"*","ContactId":"*","ContactFlowId":"*","ContactFlowName":"*","ContactFlowModuleType":"*"' as Results, ContactId, ContactFlowId, ContactFlowName, BlockType
| filter Results like 'rror' or Results like 'ailed' or Results like 'imeout' or Results like 'xception' or Results like 'No prompt provided' or Results like 'Instance has reached concurrent Lambda thread access limit' or Results like 'nsupported' or Results like 'nvalid' or Results like 'not found' or Results like 'execution limit reached'
| sort @timestamp asc
| display Timestamp, Results, ContactId, ContactFlowId, ContactFlowName, BlockType

-または-

特定のコンタクト ID について以下のクエリを実行します。

注意: ContactID の値は、お使いのコンタクト ID に置き換えてください。

fields @timestamp, @message
| sort @timestamp desc
| filter ContactID = "162faf0b-4e68-4a4b-bbde-96c9631f2a95"

次に、コンタクトフローエラーをトラブルシューティングするために、以下のリソースを確認します。

• CloudWatch アラームの設定詳細を確認して、アラームを設定したメトリクス (ContactFlowErrors または ContactFlowFatalError) と、アラームに関連付けられたコンタクトフローを特定します。メトリクスが ContactFlowFatalError である場合は、システムエラーが原因でフローの実行が失敗していることから、サービス問題である可能性があります。アラームを設定するメトリクスが ContactFlowErrors の場合は、コンタクトブロックがエラーブランチにルーティングされたことを示します。
• 影響を受けたコンタクトフローに関連するログを確認して、どのブロックがエラーを引き起こしたかを特定します。フローブロックの詳細については、「フローブロック定義」を参照してください。

時折、コンタクトフローブロックが CloudWatch にエラーを発行しても、対応する CloudWatch ログがない場合があります。一般的なコンタクトブロックの表については、「Troubleshooting contact flow errors in Amazon Connect」(Amazon Connect でのコンタクトフローエラーのトラブルシューティング) ワークショップの「Appendix」(付録) を参照してください。

コンタクトフロー内の AWS Lambda エラー

コンタクトフロー内で最も一般的なエラーは、Lambda 関数を呼び出すブロックで発生します。このコンタクトフローブロックは AWS Lambda を呼び出し、コンタクト属性の設定に使用できるキーと値のペアをオプションで返します。

Lambda 関数エラーを調査するには、CloudWatch Logs Insights で以下のクエリを実行します。

fields @timestamp, @message
| sort @timestamp desc
| filter Results LIKE "Error"

出力は次のようになります。

{
    "Results": "The Lambda Function Returned an Error.",
    "ContactId": "alebb22a-93c4-4f90-8f22-b3718c4578E0",
    "ContactFlowId": "contact-flow-id",
    "ContactFlowName": "chat",
    "ContactFlowModuleType": "InvokeExternalResource",
    "Timestamp": "2023-12-20T14:14:13.794Z",
    "Parameters": {
        "FunctionARN": "arn:aws:lambda:us-west-2:1099999:function:Connect-Wallboard-Historical-Metrics",
    },
 "TimeLimit": "3000"
}

InvokeExternalResource の影響を受けた ContactFlowModule タイプは、Lambda 関数、コンタクトフロー名、およびエラーを指しています。影響を受けた Lambda 関数を見つけます。次に、タイムスタンプ、またはコンタクト ID を関連付けて、Lambda 実行ログでエラーの原因となった正確なイベントを取得します。

アクセス拒否例外 以下は、InvokeExternalResource ブロックが原因で発生する、コンタクトフローログ内のエラーの例です。

{
    "Results": "Status Code: 403; Error Code: AccessDeniedException; RequestID: 435c21cc-19d8-4847-864e-e32867fe3a70
    "ContactId": "alebb22a-93c4-4f90-8f22-b3718c4578E0",
    "ContactFlowId": " arn:aws:lambda:us-west-2:1099999/contact-flow/65569e69-5c67-4061-8776-fd1d501c4838",
}

「アクセス拒否」エラーは、コンタクトフローに Lambda 関数を呼び出すためのアクセス権がないことを示します。インスタンスに関数を追加するための詳しい手順については、「Amazon Connect インスタンスに Lambda 関数を追加する」を参照してください。

コンタクトフローの Amazon Connect ログメッセージと Lambda 実行ログを関連付ける requestId はありません。Lambda 関数が呼び出しイベントを出力する場合は、ContactId を使用して、コンタクトフローログと Lambda 関数実行ログを関連付けます。関数が呼び出しイベントを出力しない場合は、コンタクトフローログのタイムスタンプを使用して、Lambda 関数の実行ログをフィルタリングします。

Lambda 関数を呼び出すブロックがエラーを返すが、Lambda 関数に対応するエントリがないという場合は、以下の設定を確認してください。

• Lambda ペイロードが NULL になっている可能性がある。
• 関数から返された出力は、英数字、ダッシュ、およびアンダースコア文字が含まれる値を使用する、キーと値のペアのフラットオブジェクトである必要がある。
• Lambda 関数のレスポンスが単純な文字列マップではない、またはレスポンスが 32k を超えている。ベストプラクティスは、Lambda 関数から返された出力をテストして、Amazon Connect に戻されるときに関数が正しく処理されることを確認することです。

コンタクトフローエラーは、複数のブロックが原因で発生する場合があります。ブロックとエラーの理由に関する詳細については、「Troubleshooting contact flow errors in Amazon Connect」(Amazon Connect でのコンタクトフローエラーのトラブルシューティング) ワークショップの「Appendix」(付録) を参照してください。

---