サポートされているログの送信先前提条件のログ記録の設定ログスキーマと形式エージェント時間ログエージェントメタデータログインデックス使用状況ログナレッジベースのファイル同期ログセキュリティに関する考慮事項

CloudWatch Logs を使用した Amazon Quick のモニタリング

Amazon CloudWatch Logs を使用して、Amazon Quick でチャット会話、ユーザーフィードバック、エージェント時間の使用状況、インデックスストレージの使用状況を配信し、分析できます。これらのログは、CloudWatch、Amazon S3、Amazon Data Firehose などの複数の宛先に配信できます (標準料金が適用されます）。

重要

Amazon Quick AI 機能を有効にした直後に、提供されたログ配信を設定します。ログは遡及的ではありません。配信が設定された後にのみ発生するイベントを受け取ります。

Amazon Quick のログを使用して実行できるタスクの例を次に示します。

チャットメッセージの内容を確認して、一般的なユーザークエリと問題点を特定する。
feedbackReason などのメトリクスを確認して、応答の品質をモニタリングする。
コメントや有用性評価などのフィードバックデータを分析することで、ユーザーの感情と満足度を理解する。
カスタムダッシュボードとレポートを生成して、主要なメトリクスと傾向を経時的に追跡する。
チャットが応答を返さなかったり、ユーザークエリがブロックされたりしたケースを特定して分析します。
エージェント時間の使用状況をモニタリングします。
ナレッジベースとスペース全体でインデックスストレージの使用状況を追跡します。
ナレッジベースの同期オペレーションを追跡し、ドキュメントのクロールまたはインデックス作成の失敗を特定します。

重要

会話のログには、チャットで渡される機密データや個人を特定できるデータが含まれる場合があります。ログサブスクリプションを設定するときに、この情報をログから除外できます。または、CloudWatch Logs マスキングポリシーを使用して、ログでこのデータをマスキングすることもできます。詳細については、「Help protect sensitive log data with masking」を参照してください。

サポートされているログの送信先

Amazon Quick は、次の宛先にログを配信できます。

Amazon CloudWatch Logs – リアルタイムのモニタリングと分析用
Amazon S3 – 長期ストレージとバッチ処理用
Amazon Data Firehose – ストリーミング分析とデータ変換用

前提条件

ログ記録を有効にする前に、以下があることを確認してください。

Enterprise または Professional サブスクリプションを持つアクティブな Amazon Quick インスタンス
ログ配信を設定するための適切な IAM アクセス許可
ログ用に設定された送信先 (CloudWatch Logs、Amazon S3 バケット、または Firehose)

のログ記録の設定

Amazon Quick Chat とフィードバックのログ記録を有効にするには、IAM アクセス許可を設定し、配信ソースと配信先を作成し、ログ配信を検証します。

IAM 許可をセットアップする

Amazon Quick の CloudWatch Logs を設定するには、次の IAM ポリシー例を使用して必要なアクセス許可を付与します。


{
    "Version": "2012-10-17",
    "Statement": [{
        "Sid": "QuicksightLogDeliveryPermissions",
        "Effect": "Allow",
        "Action": "quicksight:AllowVendedLogDeliveryForResource",
        "Resource": "arn:aws:quicksight:region:account-id:account/account-id"
    }]
}

また、カスタマーマネージド AWS KMS キーポリシーでdelivery.logs.amazonaws.comサービスプリンシパルを許可する必要があります。


{
    "Effect": "Allow",
    "Principal": {
        "Service": "delivery.logs.amazonaws.com"
    },
    "Action": [
        "kms:GenerateDataKey",
        "kms:Decrypt"
    ],
    "Resource": "*",
    "Condition": {
        "StringEquals": {
            "kms:EncryptionContext:SourceArn": "arn:partition:logs:region:account-id:*"
        }
    }
}

ログサブスクリプションを設定する

特定のログ記録先に必要なすべてのアクセス許可を持つ IAM ポリシーの例については、Amazon CloudWatch Logs ユーザーガイド」の AWS 「サービスからのログ記録を有効にする」を参照してください。

PutDeliverySource CloudWatch Logs API オペレーションを使用して配信ソースを作成します。配信ソースに名前を付け、resourceArn でアプリケーションの ARN を指定します。にはlogType、CHAT_LOGS、、AGENT_HOURS_LOGS、AGENT_METADATA_LOGS、FEEDBACK_LOGS、INDEX_USAGE_LOGSまたはを指定しますKB_FILE_SYNC_LOGS。


{
    "logType": "CHAT_LOGS",
    "name": "my-quick-suite-delivery-source",
    "resourceArn": "arn:aws:quicksight:your-region:your-account-id:account/account-id"
}


{
    "logType": "FEEDBACK_LOGS",
    "name": "my-quick-suite-delivery-source",
    "resourceArn": "arn:aws:quicksight:your-region:your-account-id:account/account-id"
}


{
    "logType": "AGENT_HOURS_LOGS",
    "name": "my-quick-suite-delivery-source",
    "resourceArn": "arn:aws:quicksight:your-region:your-account-id:account/account-id"
}


{
    "logType": "INDEX_USAGE_LOGS",
    "name": "my-quick-index-usage-delivery-source",
    "resourceArn": "arn:aws:quicksight:your-region:your-account-id:account/account-id"
}


{
    "logType": "KB_FILE_SYNC_LOGS",
    "name": "my-quick-kb-file-sync-delivery-source",
    "resourceArn": "arn:aws:quicksight:your-region:your-account-id:account/account-id"
}


{
    "logType": "AGENT_METADATA_LOGS",
    "name": "my-quick-agent-metadata-delivery-source",
    "resourceArn": "arn:aws:quicksight:your-region:your-account-id:account/account-id"
}

CloudWatch Logs API オペレーションでユーザー会話のログ記録を有効にするには、PutDeliverySource、PutDeliveryDestination、および CreateDelivery API オペレーションを呼び出します。

注記

Vended-log 配信はリージョンごとです。各配信は、ので指定されたリージョンで発生したアクティビティのみをキャプチャresourceArnしますPutDeliverySource。複数のリージョンからログを受信するには、リージョンごとに個別の配信を設定します。

ログ配信の検証

ログ配信を設定したら、ログが送信先に配信されていることを確認します。

セットアップを確認する: CloudWatch Logs の DescribeDeliveries API を使用して、アカウントで作成された配信のリストを確認します。
CloudWatch Logs: 指定されたロググループで新しいログストリームを確認します。
Amazon S3: 新しいログファイルがないかバケットをモニタリングします。
Firehose: データが配信ストリームを流れることを確認します。

ログスキーマと形式

Amazon Quick Logs は、すべてのログタイプで共有される共通フィールドと、チャットログとフィードバックログの特定のフィールドを含む構造化スキーマに従います。

共通フィールド

すべてのログイベントには、次の共通フィールドが含まれます。

resource_arn – Amazon Quick アカウントのリソース ARN (例: arn:aws:quicksight:us-east-1:111122223333:account/111122223333:)
event_timestamp – ミリ秒単位の Unix エポック時間 (例: 1763532110061)
logType – ログのタイプ (例: CHAT_LOGSまたは FEEDBACK_LOGS)
accountId – AWS アカウント ID (例: 123456789012)
user_arn – イベントに関連付けられた Amazon Quick ユーザー ARN (例: "arn:aws:quicksight:us-west-2:111122223333:user/default/user")

チャットログ

チャットログは会話のやり取りをキャプチャします。

注記

履歴とメモリから除外された一時的な会話は、引き続きチャットログに配信されます。各レコードには、会話を開始したユーザーの user_type user_arnとが含まれます。

user_arn – イベントに関連付けられた Amazon Quick ユーザー ARN
user_type – イベントに関連付けられた Amazon Quick ユーザータイプ (例: ADMIN_PRO)
status_code – チャットリクエストのステータス (例: success、request_blocked、no_answer_found)
conversation_id – ユーザー会話の一意の ID
system_message_id – システムによって生成されたメッセージ ID
message_scope – メッセージの範囲 (例: 、all_resourcesspecific_resources、no_resources)
user_message_id – ユーザーメッセージの一意の ID
user_message – 会話のユーザーメッセージ
agent_id – チャットエージェントの一意の ID、またはデフォルトエージェントのSYSTEM一意の ID
flow_id – Amazon Quick Flow の一意の ID、またはフロー呼び出し-でない場合
system_text_message – 会話中のシステムレスポンス
user_selected_resources – ユーザーによって選択されたリソースのリスト
action_connectors – 会話で使用できるアクションコネクタのリスト
cited_resource – 引用されたリソースのリスト
file_attachment – ユーザーによってアタッチされたファイルのリスト
resource_arn – Amazon Quick アカウントのリソース ARN
event_timestamp – イベントのタイムスタンプ
logType – CHAT_LOGS
accountId – AWS アカウント ID

チャットログの例を次に示します。


{
    "user_arn": "arn:aws:quicksight:us-east-1:111122223333:user/default/johndoe",
    "user_type": "ADMIN_PRO",
    "status_code": "success",
    "conversation_id": "c11ba72c-ff18-4213-9686-1952bb547c19",
    "system_message_id": "42a37690-1804-442b-8368-3d34570dd2cd",
    "message_scope": "all_resources",
    "user_message_id": "5ec45e03-bf22-40c7-b32a-d69eb015f86b",
    "user_message": "What is in this document?",
    "agent_id": "SYSTEM",
    "flow_id": "-",
    "system_text_message": "Here is a summary of the attached document.",
    "user_selected_resources": [{"resourceId": "ALL", "resourceType": "space"}],
    "action_connectors": [{"actionConnectorId": "quicksuite-documentation"}, {"actionConnectorId": "quicksuite-websearch"}],
    "cited_resource": [{"citedResourceType": "document", "citedResourceId": null, "citedResourceName": "example-document.html"}],
    "file_attachment": [{"fileAttachmentType": "html", "fileAttachmentName": "example-document.html"}],
    "resource_arn": "arn:aws:quicksight:us-east-1:111122223333:account/111122223333",
    "event_timestamp": 1787185484508,
    "logType": "CHAT_LOGS",
    "accountId": "111122223333"
}

フィードバックログ

フィードバックログは、チャットレスポンスに関するユーザーのフィードバックをキャプチャします。

user_arn – イベントに関連付けられた Amazon Quick ユーザー ARN
user_type – イベントに関連付けられた Amazon Quick ユーザータイプ (例: ADMIN_PRO)
status_code – イベント配信のステータス
conversation_id – 会話の一意の ID
system_message_id – システムによって生成されたメッセージ ID
user_message_id – ユーザーメッセージの一意の ID
feedback_type – フィードバックのタイプ (例: Not Useful、Useful)
feedback_reason – ユーザーが選択したフィードバックの理由
feedback_details – (オプション) ユーザーが提供する追加の詳細
resource_arn – Amazon Quick アカウントのリソース ARN
event_timestamp – イベントのタイムスタンプ
logType – FEEDBACK_LOGS
accountId – AWS アカウント ID

フィードバックログの例を次に示します。


{
    "user_arn": "arn:aws:quicksight:us-east-1:111122223333:user/default/johndoe",
    "user_type": "ADMIN_PRO",
    "status_code": "success",
    "conversation_id": "c11ba72c-ff18-4213-9686-1952bb547c19",
    "system_message_id": "42a37690-1804-442b-8368-3d34570dd2cd",
    "user_message_id": "5ec45e03-bf22-40c7-b32a-d69eb015f86b",
    "feedback_type": "Not Useful",
    "feedback_reason": "Too wordy",
    "feedback_details": "The answer included too much background information.",
    "resource_arn": "arn:aws:quicksight:us-east-1:111122223333:account/111122223333",
    "event_timestamp": 1787185500123,
    "logType": "FEEDBACK_LOGS",
    "accountId": "111122223333"
}

エージェント時間ログ

このログタイプは、料金に使用されるクイックアカウント内のさまざまなエージェントの使用状況ログをキャプチャします。

user_arn – イベントに関連付けられた Amazon Quick ユーザー ARN
subscription_type – ユーザーのサブスクリプション階層。値: ENTERPRISE、PROFESSIONAL。
reporting_service – エージェント時間を消費したクイックサーフェス。現在の値には、FLOW、AUTOMATION、およびが含まれますRESEARCH。追加のクイック機能がエージェントの時間の計測を開始すると、新しい値が表示されることがあります。
usage_group – 使用量がサブスクリプションの使用権限の対象であるか、超過料金として請求されるか。値:
- Included – サブスクリプション階層の日次使用権限付与内の使用量。増分料金はかかりません。
- Extra – 日次付与を超える超過。消費時に請求されます。
usage_hours – このレコードで消費されたエージェント時間を示す 10 進値
service_resource_arn – 時間を消費したリソースの ARN (フロー、オートメーション、研究セッションなど)
resource_arn – Amazon Quick アカウントのリソース ARN
event_timestamp – イベントのタイムスタンプ
logType – AGENT_HOURS_LOGS
accountId – AWS アカウント ID

エージェント時間ログの例を次に示します。


{
    "user_arn": "arn:aws:quicksight:us-east-1:111122223333:user/default/johndoe",
    "subscription_type": "ENTERPRISE",
    "reporting_service": "RESEARCH",
    "usage_group": "Included",
    "usage_hours": 0.0928,
    "service_resource_arn": "arn:aws:quicksight::111122223333:research/a11b2bbc-c123-3abc-a12b-12a34b5c678d",
    "resource_arn": "arn:aws:quicksight:us-east-1:111122223333:account/111122223333",
    "event_timestamp": 1787183715000,
    "logType": "AGENT_HOURS_LOGS",
    "accountId": "111122223333"
}

エージェントメタデータログ

エージェントメタデータログは、作成、更新、アクセス許可の変更、削除など、チャットエージェントのライフサイクルイベントをキャプチャします。エージェントオペレーションごとに 1 つのレコードが出力されます。

user_arn – イベントに関連付けられた Amazon Quick ユーザー ARN。
event_name – エージェントライフサイクルオペレーション。新しいオペレーションが追加されると、値には CreateAgent、UpdateAgentPermissions、、 UpdateAgent DeleteAgentなどがあります。
event_version – ログレコードのスキーマバージョン。
agent_id – エージェントの UUID。
agent_arn – エージェントの完全な ARN。
agent_name – エージェントの名前を表示します。
agent_status – エージェントの現在のステータス (例: ACTIVE)。
request_id – オペレーションのリクエスト識別子。
description – エージェントの説明テキスト。
spaces – エージェントにアタッチされたスペースの JSON 配列。
permissions_granted – このオペレーションで追加されたアクセス許可。
permissions_revoked – このオペレーションで削除されたアクセス許可。
permissions_state – オペレーション後の現在のアクセス許可。
update_action – 実行された更新アクション。
version – エージェントバージョン番号。
icon_id – エージェントのアイコン識別子。
magic_builder_query – ビルダーを介してエージェントを作成するために使用される自然言語クエリ。
instructions – エージェントの手順。
failed_to_add_spaces – アタッチできなかったスペース。
failed_to_remove_spaces – デタッチできなかったスペース。
draft_discarded – ドラフトが破棄されたかどうか。
custom_prompt_input – エージェント用に設定されたカスタムプロンプト入力。
welcome_message – エージェントのユーザーに表示されるようこそメッセージ。
starter_prompts – エージェントのユーザーに推奨されるスタータープロンプト。
resource_arn – Amazon Quick アカウントのリソース ARN。
event_timestamp – イベントのタイムスタンプ。
log_type – AGENT_METADATA_LOGS.
account_id – AWS アカウント ID。

注記

custom_prompt_input、welcome_message、および starter_promptsフィールドには、機密コンテンツが含まれています。配信用にカスタマーマネージド AWS KMS キーを設定すると、これらのフィールドは暗号化されます。キーがないと、クリアテキストで配信されます。

CreateAgent イベントのエージェントメタデータログの例を次に示します。


{
    "user_arn": "arn:aws:quicksight:us-east-1:111122223333:user/default/johndoe",
    "event_version": "1.0",
    "event_name": "CreateAgent",
    "agent_id": "12345678-90ab-cdef-1234-567890abcdef",
    "request_id": "fedcba98-7654-3210-fedc-ba9876543210",
    "agent_arn": "arn:aws:quicksight:us-east-1:111122223333:agent/12345678-90ab-cdef-1234-567890abcdef",
    "agent_name": "Project Status Assistant",
    "agent_status": "ACTIVE",
    "description": "An agent that helps track project status and find relevant documentation.",
    "spaces": "[{\"Arn\": \"arn:aws:quicksight:us-east-1:111122223333:space/11112222-3333-4444-5555-666677778888\"}]",
    "resource_arn": "arn:aws:quicksight:us-east-1:111122223333:account/111122223333",
    "event_timestamp": 1787185396000,
    "log_type": "AGENT_METADATA_LOGS",
    "account_id": "111122223333"
}

インデックス使用状況ログ

インデックス使用状況ログは、ナレッジベースとスペースのソースごとのストレージメトリクスをキャプチャします。イベントは、変更 (作成、更新、同期、または削除) が発生するたびに発行されます。

user_arn – イベントに関連付けられた Amazon Quick ユーザー ARN
consumed_index_size – インデックス全体で消費される合計サイズ (バイト単位)
source_type – ソースのタイプ: SPACEまたは KB
source_name – スペースまたはナレッジベースの表示名
source_arn – ソースの完全な ARN
consumed_source_size – この個々のソースによって消費されるサイズ (バイト単位)
consumed_source_doc_count – このソース内のドキュメントの数
resource_arn – Amazon Quick アカウントのリソース ARN
event_timestamp – イベントのタイムスタンプ
log_type – INDEX_USAGE_LOGS
account_id – AWS アカウント ID

インデックス使用状況ログの例を次に示します。


{
    "account_id": "111122223333",
    "event_timestamp": 1774911984257,
    "log_type": "INDEX_USAGE_LOGS",
    "user_arn": "arn:aws:quicksight::111122223333:user/default/user",
    "resource_arn": "arn:aws:quicksight:us-west-2:111122223333:account/111122223333",
    "consumed_index_size": 500000,
    "source_type": "SPACE",
    "source_name": "my-space",
    "source_arn": "arn:aws:quicksight:us-west-2:111122223333:space/2744af89-31b2-423b-93a2-69b0cd0d7fa1",
    "consumed_source_size": 244436,
    "consumed_source_doc_count": 2
}

注記

イベントは、変更時にソースごとに発行されます。すべてのソースが毎日イベントを出力するわけではありません。現在の状態を再構築するには、ごとに最新のイベントを使用しますsource_arn。

ダッシュボードの構築とインデックス使用状況ログに対するクエリの実行については、「」を参照してくださいインデックスストレージの使用状況をモニタリングする。

ナレッジベースのファイル同期ログ

ナレッジベースのファイル同期ログは、ドキュメントごとの同期ステータスイベントをキャプチャします。同期実行ごとにドキュメントごとに 1 つのログレコードが出力されます。

document_id – URL やファイルパスなどの元のドキュメント識別子。
document_title – ドキュメントのタイトル。
document_status – ターミナルドキュメントのステータス。値: ADDED、MODIFIED、UNMODIFIED、、DELETEDSKIPPED、FAILED。
sync_result – 高可用性の結果。値: AVAILABLEまたは UNAVAILABLE。
sync_id – ジョブ実行 ID を同期します。
data_source_id – ナレッジベースが接続されているデータソースの識別子。
source_uri – ドキュメントのソース URL。
error_message – ステータスが FAILEDまたはの場合のエラーの説明SKIPPED。
error_mitigation – エラーを解決するための実用的なガイダンス。
error_type – ステータスが FAILEDまたはの場合のエラーコードSKIPPED。
knowledge_base_id – ログを生成したナレッジベースの UUID。

次の表に、document_status値とそれに対応するを示しますsync_result。

document_status	sync_result	意味
`ADDED`	`AVAILABLE`	新しいドキュメントのインデックスが正常に作成されました
`MODIFIED`	`AVAILABLE`	変更が再インデックスされた既存のドキュメント
`UNMODIFIED`	`AVAILABLE`	ドキュメントの内容は変更されず、インデックスの再作成は不要
`DELETED`	`UNAVAILABLE`	ドキュメントがインデックスから削除されました
`SKIPPED`	`UNAVAILABLE`	robots.txt やサイズ制限など、クロール中にフィルタリングされたドキュメント
`FAILED`	`UNAVAILABLE`	クロールまたはインデックス作成中にドキュメントが失敗しました

次の例は、ドキュメントがナレッジベースに追加されたナレッジベースのファイル同期ログの成功を示しています。


{
    "resource_arn": "arn:aws:quicksight:us-west-2:111122223333:account/111122223333",
    "event_timestamp": 1781296858575,
    "log_type": "KB_FILE_SYNC_LOGS",
    "account_id": "111122223333",
    "document_id": "https://docs.aws.amazon.com/quick/latest/userguide/monitoring-cloudwatch-logs.html",
    "document_title": "Monitoring Amazon QuickSight usage using CloudWatch Logs",
    "document_status": "ADDED",
    "sync_result": "AVAILABLE",
    "sync_id": "86a70a9a-cad9-4fc6-8881-e3909c8954d2",
    "data_source_id": "56225744-18bc-4373-a91f-861dd1c3d566",
    "source_uri": "https://docs.aws.amazon.com/quick/latest/userguide/monitoring-cloudwatch-logs.html",
    "knowledge_base_id": "b0bd0a47-8095-439d-9dff-c64bd5fe3fa3"
}

次の例は、検証エラーのためにクロールがスキップされたスキップされたドキュメントログを示しています。


{
    "resource_arn": "arn:aws:quicksight:us-west-2:111122223333:account/111122223333",
    "event_timestamp": 1781296492951,
    "log_type": "KB_FILE_SYNC_LOGS",
    "account_id": "111122223333",
    "document_id": "https://docs.aws.amazon.com/quick/latest/userguide/blocked-page.html",
    "document_title": "Blocked Page",
    "document_status": "SKIPPED",
    "sync_result": "UNAVAILABLE",
    "sync_id": "86a70a9a-cad9-4fc6-8881-e3909c8954d2",
    "data_source_id": "56225744-18bc-4373-a91f-861dd1c3d566",
    "source_uri": "https://docs.aws.amazon.com/quick/latest/userguide/blocked-page.html",
    "error_message": "This URL wasn't crawled because crawling isn't allowed by its robots.txt file.",
    "error_mitigation": "Contact the website administrator for assistance.",
    "error_type": "VALIDATION_ERROR",
    "knowledge_base_id": "b0bd0a47-8095-439d-9dff-c64bd5fe3fa3"
}

セキュリティに関する考慮事項

暗号化 – 機密データにはカスタマーマネージド AWS KMS キーを使用します。
アクセスコントロール — 最小特権の IAM ポリシーを実装します。
データ保持 — コンプライアンス要件に適した保持ポリシーを設定します。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

Amazon Quick でのインシデント対応、ログ記録、モニタリング

CloudTrail を使用したモニタリング