本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用 CloudWatch 日志监控亚马逊 Quick
<a name="monitoring-cloudwatch-logs"></a>

您可以使用 [ Amazon L CloudWatch ogs ](https://docs.amazonaws.cn/AmazonCloudWatch/latest/logs/AWS-logs-and-resource-policy.html) 在 Amazon Quick 中提供聊天对话、用户反馈、代理时间使用情况和索引存储使用情况，以供您分析。这些日志可以传送到多个目的地 CloudWatch，例如亚马逊 S3 或 Amazon Data Firehose（适用标准费率）。

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

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

**重要**  
源自对话的日志可能包含聊天中传递的敏感信息或个人身份数据。设置日志订阅时，您可以从日志中过滤掉这些信息。或者，您可以使用日志屏蔽策略来掩盖 CloudWatch 日志中的这些数据。有关更多信息，请参阅 [Help protect sensitive log data with masking](https://docs.amazonaws.cn/AmazonCloudWatch/latest/logs/mask-sensitive-log-data.html)。

## 支持的日志目的地
<a name="quicksuite-chat-feedback-supported-log-destinations"></a>

Amazon Quick 可以将日志传送到以下目的地：
+ **亚马逊 CloudWatch 日志 ** — 用于实时监控和分析
+ **Amazon S3 ** — 用于长期存储和批处理
+ **Amazon Data Fire ** hose — 用于流媒体分析和数据转换

## 先决条件
<a name="quicksuite-chat-feedback-logging-prerequisites"></a>

在启用日志记录之前，请确保您具备以下条件：
+ 具有企业版或专业版订阅的有效亚马逊 Quick 实例
+ 配置日志传输的适当 IAM 权限
+ 为您的日志配置的目的地（日CloudWatch 志、Amazon S3 存储桶或 Firehose）

## 配置 日志记录
<a name="quicksuite-chat-feedback-configure-logging"></a>

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

**Topics**
+ [设置 IAM 权限](#quicksuite-chat-feedback-setup-iam-permissions)
+ [配置日志订阅](#quicksuite-chat-feedback-configure-log-subscription)
+ [验证日志传输](#quicksuite-chat-feedback-verify-log-delivery)

### 设置 IAM 权限
<a name="quicksuite-chat-feedback-setup-iam-permissions"></a>

要为 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:*"
        }
    }
}
```

### 配置日志订阅
<a name="quicksuite-chat-feedback-configure-log-subscription"></a>

例如，具有特定日志目标所需全部权限的 IAM 政策，请参阅 A * mazon Log CloudWatch s 用户指南[中的](https://docs.amazonaws.cn/AmazonCloudWatch/latest/logs/AWS-logs-and-resource-policy.html)启用 Amazon 服务日志记录*。

使用[PutDeliverySource](https://docs.amazonaws.cn/AmazonCloudWatchLogs/latest/APIReference/API_PutDeliverySource.html) CloudWatch 日志 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 日志 API 操作启用用户对话记录，您可以调用`PutDeliverySource``PutDeliveryDestination`、和 `CreateDelivery` API 操作。

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

### 验证日志传输
<a name="quicksuite-chat-feedback-verify-log-delivery"></a>

配置日志传输后，验证日志是否已传送到目的地：
+ **验证设置：使用 CloudWatch 日志中的 `DescribeDeliveries` API ** 验证在账户中创建的交付列表。
+ **CloudWatch 日志**：检查指定的日志组中是否有新的日志流。
+ **Amazon S3**：监控您的存储桶中是否有新的日志文件。
+ **Fire ** hose：验证数据是否流经您的交付流。

## 日志架构和格式
<a name="quicksuite-chat-feedback-log-schema-format"></a>

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

### 通用字段
<a name="quicksuite-chat-feedback-common-fields"></a>

所有日志事件都包含以下常用字段：
+ `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"`）

### 聊天日志
<a name="quicksuite-chat-logs"></a>

聊天记录记录对话互动：

**注意**  
不在历史记录和记忆中的临时对话仍会传送到聊天记录中。每条记录都包括发起对话的用户的`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"
}
```

### 反馈日志
<a name="quicksuite-chat-feedback-logs"></a>

反馈日志捕获用户对聊天回复的反馈：
+ `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"
}
```

## 代理工时日志
<a name="quicksuite-agent-hours-logs"></a>

此日志类型捕获用于定价的 Quick 账户中不同代理的使用日志：
+ `user_arn`— 与该活动相关的亚马逊 Quick 用户 ARN
+ `subscription_type`— 用户的订阅等级。价值观：`ENTERPRISE`，`PROFESSIONAL`。
+ `reporting_service`— 消耗代理数小时的 Quick 表面。当前值包括`FLOW``AUTOMATION`、和`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"
}
```

## 代理元数据日志
<a name="quicksuite-agent-metadata-logs"></a>

代理元数据日志捕获聊天代理的生命周期事件，包括创建、更新、权限更改和删除。每个代理操作都会发出一条记录：
+ `user_arn`— 与该活动相关的亚马逊 Quick 用户 ARN。
+ `event_name`— 代理生命周期操作。添加新操作时的值包括`CreateAgent``UpdateAgent``DeleteAgent``UpdateAgentPermissions`、、、和其他值。
+ `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_input``welcome_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"
}
```

## 索引使用日志
<a name="quicksuite-index-usage-logs"></a>

索引使用日志捕获知识库和空间的每个源存储指标。每当发生更改（创建、更新、同步或删除）时，就会发布事件：
+ `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` 的最新事件。

有关构建仪表板和对索引使用日志运行查询的信息，请参阅[监控索引存储使用情况](index-usage-monitoring.md)。

## 知识库文件同步日志
<a name="quicksuite-kb-file-sync-logs"></a>

知识库文件同步日志捕获每个文档的同步状态事件。每次同步运行都会为每个文档发出一条日志记录：
+ `document_id`— 原始文档标识符，例如 URL 或文件路径。
+ `document_title`— 文件标题。
+ `document_status`— 终端文件状态。价值观：`ADDED``MODIFIED`、、`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"
}
```

## 安全注意事项
<a name="quicksuite-chat-feedback-security-considerations"></a>
+ **加密 **-使用客户管理的 Amazon KMS 密钥存储敏感数据。
+ **访问控制 ** — 实施最低权限 IAM 策略。
+ **数据保留 ** — 为您的合规性要求配置适当的保留政策。