Amazon Q in ConnectのログをCloudWatch Logsに出力してみた

平井裕二
2025.02.05
 はじめに本記事では、Amazon Q in ConnectのログをCloudWatch Logsに出力する方法について解説します。
Amazon Q in Connectのログを出力するためには、AWS CLIやAPI経由での設定が必要です。AWSマネジメントコンソールから設定はできません。
AWSの公式ドキュメントには設定方法の概要は記載されているものの、具体的なAWS CLIコマンドは含まれていません。
そこで本記事では、AWS CloudShellを使用したAWS CLIでの具体的な設定手順を解説します。
https://docs.aws.amazon.com/ja_jp/connect/latest/adminguide/monitor-q-assistants-cloudwatch.html
また、AWS公式ドキュメントでは一部のイベントログ例は掲載されているものの、全てのイベント種類やJSONオブジェクトのプロパティは網羅されていません。

実際の環境で出力されるログの詳細な内容についても確認します。
https://docs.aws.amazon.com/ja_jp/connect/latest/adminguide/monitor-q-assistants-cloudwatch.html#example1-assistant-log
 前提条件Q in Connectを設定済み
https://dev.classmethod.jp/articles/amazon-q-in-connect-setting-search-content/

 CloudWatch Logsにログを出力以下の手順では、AWS CloudShellを使用してログ出力の設定を行います。
Amazon Q in ConnectのアシスタントARNを取得します。

Connectで設定済みのAmazon Qのドメイン名はamazon-q-in-connectにしています。このドメイン名は、AWSマネジメントコンソールで確認することができます。

$ aws qconnect list-assistants | jq '.assistantSummaries[] | 
  select(.name == "amazon-q-in-connect")'

##出力結果
{
  "aiAgentConfiguration": {
    "ANSWER_RECOMMENDATION": {
      "aiAgentId": "3025a3fa-5419-4c9c-a040-877213b93f70:4"
    },
    "MANUAL_SEARCH": {
      "aiAgentId": "652f0287-1610-4fee-bbe3-c687c13f5ec3:4"
    },
    "SELF_SERVICE": {
      "aiAgentId": "529207fe-80fd-42be-bcf2-facd2141aec7:1"
    }
  },
  "assistantArn": "arn:aws:wisdom:ap-northeast-1:111111111111:assistant/a1793008-f4de-481b-a9ed-3697ef373ff2",
  "assistantId": "a1793008-f4de-481b-a9ed-3697ef373ff2",
  "capabilityConfiguration": {
    "type": "V2"
  },
  "integrationConfiguration": {
    "topicIntegrationArn": "arn:aws:sns:ap-northeast-1:721038445438:wisdom-78d30d9a-ce3a-4f6f-9312-a1545b31b7d7"
  },
  "name": "amazon-q-in-connect",
  "status": "ACTIVE",
  "tags": {
    "AmazonConnectEnabled": "True"
  },
  "type": "AGENT"
}

## 以下でも可
$ aws qconnect list-assistants | jq -r '.assistantSummaries[] | 
  select(.name == "amazon-q-in-connect") | 
  .assistantArn'

## 出力結果
arn:aws:wisdom:ap-northeast-1:111111111111:assistant/a1793008-f4de-481b-a9ed-3697ef373ff2
CloudWatch Logsにログを送信するための配信元（Delivery Source）を作成します。
先ほど取得したアシスタントARNを使用します
配信元の名前はq-in-connect-sourceと設定しました
$ aws logs put-delivery-source \
    --log-type EVENT_LOGS \
    --name "q-in-connect-source" \
    --resource-arn "arn:aws:wisdom:ap-northeast-1:111111111111:assistant/a1793008-f4de-481b-a9ed-3697ef373ff2" \
    --region ap-northeast-1

## 出力結果
{
    "deliverySource": {
        "name": "q-in-connect-source",
        "arn": "arn:aws:logs:ap-northeast-1:111111111111:delivery-source:q-in-connect-source",
        "resourceArns": [
            "arn:aws:wisdom:ap-northeast-1:111111111111:assistant/a1793008-f4de-481b-a9ed-3697ef373ff2"
        ],
        "service": "wisdom",
        "logType": "EVENT_LOGS"
    }
}
ちなみに、Amazon Q in Connectがサポートするログタイプは以下の1種類のみです。
EVENT_LOGS：通話中およびチャット中のQ in Connectのイベントを追跡するログです。
ロググループを作成します。

ロググループ名は/aws/connect/q-in-connectと設定しました。
$ aws logs create-log-group \
    --log-group-name "/aws/connect/q-in-connect" \
    --region ap-northeast-1
CloudWatch Logs にログを保存するための 配信先 (Delivery Destination) を作成します。
destinationResourceArnの値は、ロググループのARNから末尾の:*を削除したものを指定します。
ロググループのARN

arn:aws:logs:ap-northeast-1:111111111111:log-group:/aws/connect/q-in-connect:*
実際に設定する値（末尾の:*を削除）

arn:aws:logs:ap-northeast-1:111111111111:log-group:/aws/connect/q-in-connect
配信先の名前はq-in-connect-destinationにしました。
$ aws logs put-delivery-destination \
    --name "q-in-connect-destination" \
    --delivery-destination-configuration '{"destinationResourceArn":"arn:aws:logs:ap-northeast-1:111111111111:log-group:/aws/connect/q-in-connect"}' \
    --output-format "json" \
    --region ap-northeast-1

## 出力結果
{
    "deliveryDestination": {
        "name": "q-in-connect-destination",
        "arn": "arn:aws:logs:ap-northeast-1:111111111111:delivery-destination:q-in-connect-destination",
        "deliveryDestinationType": "CWL",
        "outputFormat": "json",
        "deliveryDestinationConfiguration": {
            "destinationResourceArn": "arn:aws:logs:ap-northeast-1:111111111111:log-group:/aws/connect/q-in-connect"
        }
    }
}
配信元 (q-in-connect-source) と 配信先のロググループを関連付けます。
$ aws logs create-delivery \
    --delivery-destination-arn "arn:aws:logs:ap-northeast-1:111111111111:delivery-destination:q-in-connect-destination" \
    --delivery-source-name "q-in-connect-source" \
    --region ap-northeast-1

## 出力結果
{
    "delivery": {
        "id": "7ktwj3otDV1gUIhR",
        "arn": "arn:aws:logs:ap-northeast-1:111111111111:delivery:7ktwj3otDV1gUIhR",
        "deliverySourceName": "q-in-connect-source",
        "deliveryDestinationArn": "arn:aws:logs:ap-northeast-1:111111111111:delivery-destination:q-in-connect-destination",
        "deliveryDestinationType": "CWL",
        "recordFields": [
            "assistant_id",
            "event_timestamp",
            "event_type",
            "session_id",
            "session_name",
            "recommendation_id",
            "recommendation",
            "is_recommendation_useful",
            "relevance_score",
            "recommendation_title",
            "recommendation_sources",
            "intent_id",
            "intent",
            "intent_clicked",
            "utterance",
            "prompt",
            "response",
            "session_event_id",
            "session_event_ids",
            "issue_probability",
            "is_valid_trigger",
            "prompt_type",
            "completion",
            "model_id",
            "connect_user_arn",
            "conversation_session_data",
            "session_message_id"
        ]
    }
}
設定後、ロググループを確認すると、以下のログストリームが自動的に作成されています。
ログストリーム名：log_stream_created_by_aws_to_validate_log_delivery_subscriptions

メッセージは以下の通りです。
Permissions are set correctly to allow AWS CloudWatch Logs to write into your logs while creating a subscription.
 ログを出力してみる実際にログ出力を確認するため、Q in Connectのコンテンツ検索で「クラスメソッドメンバーズでできることは？」という質問を投げかけてみます。
質問を実行すると、CloudWatch LogsにQiCAssistantTranscriptという新しいログストリームが作成されました。
以下の3つのログイベントが出力されました。それぞれの内容を確認していきましょう。
最初のログイベント
イベントタイプ：TRANSCRIPT_QUERY_ASSISTANT
発生時刻：2025-02-05T05:28:41.526Z
特徴：クエリの初期実行を示すログです。この時点では処理が完了していないため、completion（応答内容）は空の状態となっています。
{
    "assistant_id": "a1793008-f4de-481b-a9ed-3697ef373ff2",
    "event_timestamp": 1738733321526,
    "event_type": "TRANSCRIPT_QUERY_ASSISTANT",
    "recommendation_id": "628eee3f-8bff-4415-abb6-acb7b87b2c44",
    "completion": ""
}
第2ログイベント（TRANSCRIPT_QUERY_ASSISTANT）
発生時刻：2025-02-05T05:28:45.399Z
イベントタイプ：TRANSCRIPT_QUERY_ASSISTANT
プロンプトタイプ：BEDROCK_KB_GENERATIVE_ANSWER
使用モデル：Claude 3 Haiku
特徴：このログには、ユーザーのクエリに対する生成された回答が含まれています。
{
    "assistant_id": "a1793008-f4de-481b-a9ed-3697ef373ff2",
    "event_timestamp": 1738733325399,
    "event_type": "TRANSCRIPT_QUERY_ASSISTANT",
    "recommendation_id": "f513a088-fa6c-474e-a44f-c7e282861b14",
    "prompt_type": "BEDROCK_KB_GENERATIVE_ANSWER",
    "completion": "クラスメソッドメンバーズでは以下のようなサービスを提供しています: - AWSの利用費を割引し、請求書の一本化や円建て払いなどのコスト削減サービス\n- 24時間365日のAWSサポートや、セキュリティ設定の初期化・変更対応などの運用支援サービス\n- AWSの導入支援やコンサルティング、マイグレーションなどの技術支援サービス",
    "model_id": "anthropic.claude-3-haiku-20240307-v1:0"
}
第3ログイベント（TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION）
発生時刻：2025-02-05T05:28:45.420Z
イベントタイプ：TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION
このログには、大規模言語モデル（LLM）への実際のプロンプト内容が記録されています。プロンプトには、ユーザーからの質問に対する回答を生成するための詳細な指示が含まれています。
{
  "assistant_id": "a1793008-f4de-481b-a9ed-3697ef373ff2",
  "event_timestamp": 1738733325420,
  "event_type": "TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION",
  "prompt": {
    // 長いプロンプトの内容
  },
  "prompt_type": "BEDROCK_KB_GENERATIVE_ANSWER",
  "completion": {
    "citations": [
      // 引用情報の配列
    ],
    "output": {
      "text": "クラスメソッドメンバーズでは以下のようなサービスを提供しています: ..."
    },
    "sessionId": "a29428a9-346d-4c3f-98af-c24b4e63ffaa"
  },
  "model_id": "anthropic.claude-3-haiku-20240307-v1:0"
}
ログの時刻を比較すると、質問から応答までの所要時間は約4秒であることが確認できます。コンテンツ検索での応答速度は一般的なユースケースにおいて十分な実用性があると言えます。
もう一度Q in Connectに質問すると、ログストリームQiCAssistantTranscriptにログイベントが3つ追加されました。
 最後に本記事では、AWS CloudShellとAWS CLIを使用して、Amazon Q in ConnectのログをCloudWatch Logsに出力する具体的な手順を解説しました。
なお、現時点ではAWSマネジメントコンソールからの設定はサポートされていません。サポートを希望される場合は、AWSへフィードバックしましょう。