支持的日志目的地先决条件配置日志记录日志架构和格式代理工时日志代理元数据日志索引使用日志知识库文件同步日志安全注意事项

使用 CloudWatch 日志监控亚马逊 Quick

您可以使用 Amazon L CloudWatch ogs 在 Amazon Quick 中提供聊天对话、用户反馈、代理时间使用情况和索引存储使用情况，以供您分析。这些日志可以传送到多个目的地 CloudWatch，例如亚马逊 S3 或 Amazon Data Firehose（适用标准费率）。

重要

在启用 Amazon Quick AI 功能后不久即可设置供应商日志传输。日志不可追溯——您只会收到配置交付后发生的事件。

以下是您可以使用 Amazon Quick 的日志完成的任务示例：

通过查看聊天消息内容，找出常见的用户查询和难点。
通过查看 feedbackReason 等指标来监控回复的质量。
通过分析反馈数据（包括评论和有用性评级）来了解用户的情绪和满意度。
生成自定义控制面板和报告，以跟踪一段时间内的关键指标和趋势。
识别和分析聊天未返回答案或用户查询被屏蔽的案例。
监控代理的使用时间。
跟踪知识库和空间中索引存储的使用情况。
跟踪知识库同步操作并识别文档抓取或索引失败。

重要

源自对话的日志可能包含聊天中传递的敏感信息或个人身份数据。设置日志订阅时，您可以从日志中过滤掉这些信息。或者，您可以使用日志屏蔽策略来掩盖 CloudWatch 日志中的这些数据。有关更多信息，请参阅 Help protect sensitive log data with masking。

支持的日志目的地

Amazon Quick 可以将日志传送到以下目的地：

亚马逊 CloudWatch 日志 — 用于实时监控和分析
Amazon S3 — 用于长期存储和批处理
Amazon Data Fire hose — 用于流媒体分析和数据转换

先决条件

在启用日志记录之前，请确保您具备以下条件：

具有企业版或专业版订阅的有效亚马逊 Quick 实例
配置日志传输的适当 IAM 权限
为您的日志配置的目的地（日CloudWatch 志、Amazon S3 存储桶或 Firehose）

配置日志记录

要启用 Amazon Quick 聊天和反馈的日志记录，请配置 IAM 权限，创建交付来源和目的地，并验证日志传输。

设置 IAM 权限

要为 Amazon Quick 设置 CloudWatch 日志，请使用以下 IAM 策略示例授予必要的权限。


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

您还必须允许在客户管理 Amazon 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 政策，请参阅 A mazon Log CloudWatch s 用户指南中的启用 Amazon 服务日志记录。

使用PutDeliverySource CloudWatch 日志 API 操作创建交付源。为传输来源命名，然后为 resourceArn 指定应用程序的 ARN。对于logTypeCHAT_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 日志 API 操作启用用户对话记录，您可以调用PutDeliverySourcePutDeliveryDestination、和 CreateDelivery API 操作。

注意

Vended-log 按地区配送。每次交付仅捕获在中指定的区域中发生的resourceArn活动PutDeliverySource。要接收来自多个区域的日志，请在每个区域配置单独的交付。

验证日志传输

配置日志传输后，验证日志是否已传送到目的地：

验证设置：使用 CloudWatch 日志中的 DescribeDeliveries API 验证在账户中创建的交付列表。
CloudWatch 日志：检查指定的日志组中是否有新的日志流。
Amazon S3：监控您的存储桶中是否有新的日志文件。
Fire hose：验证数据是否流经您的交付流。

日志架构和格式

Amazon Quick 日志遵循结构化架构，所有日志类型共享通用字段，聊天和反馈日志的特定字段共享。

通用字段

所有日志事件都包含以下常用字段：

resource_arn— 您的亚马逊 Quick 账户的资源 ARN（例如，arn:aws:quicksight:us-east-1:111122223333:account/111122223333:）
event_timestamp— 以毫秒为单位的 Unix 纪元时间（例如，）1763532110061
logType— 日志的类型（例如，CHAT_LOGS或FEEDBACK_LOGS）
accountId— Amazon 账户 ID（例如，123456789012）
user_arn— 与该活动相关的亚马逊 Quick 用户 ARN（例如，"arn:aws:quicksight:us-west-2:111122223333:user/default/user"）

聊天日志

聊天记录记录对话互动：

注意

不在历史记录和记忆中的临时对话仍会传送到聊天记录中。每条记录都包括发起对话的用户的user_arn和user_type。

user_arn— 与该活动相关的亚马逊 Quick 用户 ARN
user_type— 与活动关联的 Amazon Quick 用户类型（例如，ADMIN_PRO）
status_code— 聊天请求的状态（例如，success、request_blocked、no_answer_found）
conversation_id— 用户对话的唯一 ID
system_message_id— System-generated 消息 ID
message_scope— 消息的范围（例如，all_resources、specific_resources、no_resources）
user_message_id— 用户消息的唯一 ID
user_message— 对话中的用户消息
agent_id— 聊天代理的唯一 ID，或默认代理SYSTEM的唯一 ID
flow_id— 亚马逊 Quick Flow 的唯一 ID，-如果不是 Flow 调用
system_text_message— 对话中的系统响应
user_selected_resources— 用户选择的资源列表
action_connectors— 对话中可用的操作连接器列表
cited_resource— 引用资源清单
file_attachment— 用户附加的文件列表
resource_arn— 您的亚马逊 Quick 账户的资源 ARN
event_timestamp— 事件的时间戳
logType – CHAT_LOGS
accountId— Amazon 账户 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— 与该活动相关的亚马逊 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— 您的亚马逊 Quick 账户的资源 ARN
event_timestamp— 事件的时间戳
logType – FEEDBACK_LOGS
accountId— Amazon 账户 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"
}

代理工时日志

此日志类型捕获用于定价的 Quick 账户中不同代理的使用日志：

user_arn— 与该活动相关的亚马逊 Quick 用户 ARN
subscription_type— 用户的订阅等级。价值观：ENTERPRISE，PROFESSIONAL。
reporting_service— 消耗代理数小时的 Quick 表面。当前值包括FLOWAUTOMATION、和RESEARCH。随着其他 Quick 功能开始计量代理工作时间，新值可能会出现。
usage_group— 使用量是否包含在订阅权限范围内，还是按超额计费。值：
- Included— 在订阅级别的每日权利授予范围内的使用量。不收取增量费用。
- Extra— 超出每日补助金的超额。按消费计费。
usage_hours— 表示此记录消耗的代理时数的十进制值
service_resource_arn— 消耗数小时的资源的 ARN（例如，流程、自动化或研究会话）
resource_arn— 您的亚马逊 Quick 账户的资源 ARN
event_timestamp— 事件的时间戳
logType – AGENT_HOURS_LOGS
accountId— Amazon 账户 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"
}

代理元数据日志

代理元数据日志捕获聊天代理的生命周期事件，包括创建、更新、权限更改和删除。每个代理操作都会发出一条记录：

user_arn— 与该活动相关的亚马逊 Quick 用户 ARN。
event_name— 代理生命周期操作。添加新操作时的值包括CreateAgentUpdateAgentDeleteAgentUpdateAgentPermissions、、、和其他值。
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— 您的亚马逊 Quick 账户的资源 ARN。
event_timestamp— 事件的时间戳。
log_type – AGENT_METADATA_LOGS.
account_id— Amazon 账号。

注意

custom_prompt_inputwelcome_message、和starter_prompts字段包含敏感内容。当您配置客户管理的 Amazon 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— 与该活动相关的亚马逊 Quick 用户 ARN
consumed_index_size— 整个索引消耗的总大小（以字节为单位）
source_type— 来源类型：SPACE或 KB
source_name— 显示空间或知识库的名称
source_arn— 源代码的完整 ARN
consumed_source_size— 此单个源消耗的大小（以字节为单位）
consumed_source_doc_count— 此来源中的文件数量
resource_arn— 您的亚马逊 Quick 账户的资源 ARN
event_timestamp— 事件的时间戳
log_type – INDEX_USAGE_LOGS
account_id— Amazon 账户 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
}

注意

事件在变更时按来源发布。并非所有来源每天都会发出事件。要重建当前状态，请使用 per source_arn 的最新事件。

有关构建仪表板和对索引使用日志运行查询的信息，请参阅监控索引存储使用情况。

知识库文件同步日志

知识库文件同步日志捕获每个文档的同步状态事件。每次同步运行都会为每个文档发出一条日志记录：

document_id— 原始文档标识符，例如 URL 或文件路径。
document_title— 文件标题。
document_status— 终端文件状态。价值观：ADDEDMODIFIED、、UNMODIFIED、DELETED、SKIPPED、FAILED。
sync_result— High-level 可用性结果。价值观：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。

文档状态	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"
}

安全注意事项

加密 -使用客户管理的 Amazon KMS 密钥存储敏感数据。
访问控制 — 实施最低权限 IAM 策略。
数据保留 — 为您的合规性要求配置适当的保留政策。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

Amazon Quick 中的事件响应、记录和监控

使用监控 CloudTrail