本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用 CloudWatch Logs 監控 Amazon Quick
<a name="monitoring-cloudwatch-logs"></a>

您可以使用 [Amazon CloudWatch Logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AWS-logs-and-resource-policy.html) 在 Amazon Quick 中提供聊天對話、使用者意見回饋、客服人員時數用量和索引儲存用量，供您分析。這些日誌可以傳送到多個目的地，例如 CloudWatch、Amazon S3 或 Amazon Data Firehose （適用標準費率）。

**重要**  
在啟用 Amazon Quick AI 功能後不久設定自動提供的日誌交付。日誌不會追溯 – 您只會收到設定交付後發生的事件。

以下是您可以使用 Amazon Quick 日誌完成的任務範例：
+ 檢閱聊天訊息內容來識別常見的使用者查詢和困擾。
+ 查看 `feedbackReason` 等指標來監控回應品質。
+ 分析意見回饋資料來瞭解使用者情緒和滿意度，包括評論和實用性評分。
+ 產生自訂儀表板和報告，以追蹤長期的關鍵指標和趨勢。
+ 識別和分析聊天未傳回答案或使用者查詢遭到封鎖的案例。
+ 監控客服人員時數用量。
+ 跨知識庫和空間追蹤索引儲存用量。
+ 追蹤知識庫同步操作，並識別文件編目或索引失敗。

**重要**  
對話日誌可能包含聊天中傳遞的敏感或個人身分識別資料。設定日誌訂閱時，您可以從日誌中篩選掉此資訊。或者您可以使用 CloudWatch Logs 遮罩政策在日誌上遮罩此資料。如需詳細資訊，請參閱[使用遮罩功能協助保護敏感日誌資料](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/mask-sensitive-log-data.html)。

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

Amazon Quick 可以將日誌交付至下列目的地：
+ **Amazon CloudWatch Logs** – 用於即時監控和分析
+ **Amazon S3** – 用於長期儲存和批次處理
+ **Amazon Data Firehose** – 用於串流分析和資料轉換

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

在啟用記錄之前，請確定您有下列項目：
+ 具備企業或專業訂閱的作用中 Amazon Quick 執行個體
+ 設定日誌交付的適當 IAM 許可
+ 為您的日誌設定的目的地 (CloudWatch Logs、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 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:*"
        }
    }
}
```

### 設定日誌訂閱
<a name="quicksuite-chat-feedback-configure-log-subscription"></a>

如需具有特定記錄目的地所有必要許可的 IAM 政策，請參閱《*Amazon CloudWatch Logs 使用者指南*》中的[從 AWS 服務啟用記錄](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AWS-logs-and-resource-policy.html)。

使用 [PutDeliverySource](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutDeliverySource.html) CloudWatch Logs API 操作建立交付來源。為交付來源指定名稱，並為 `resourceArn` 指定應用程式 ARN。針對 `logType`，指定 `CHAT_LOGS`、`AGENT_HOURS_LOGS`、`AGENT_METADATA_LOGS`、`INDEX_USAGE_LOGS`、 `FEEDBACK_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`。若要從多個區域接收日誌，請在每個區域中設定個別交付。

### 驗證日誌交付
<a name="quicksuite-chat-feedback-verify-log-delivery"></a>

設定日誌交付後，請確認日誌已交付至目的地：
+ **驗證設定：**使用 CloudWatch Logs 中的 `DescribeDeliveries` API 驗證在帳戶中建立的交付清單。
+ **CloudWatch Logs**：檢查指定的日誌群組是否有新的日誌串流。
+ **Amazon S3**：監控儲存貯體是否有新的日誌檔案。
+ **Firehose**：確認資料正在流經您的交付串流。

## 日誌結構描述和格式
<a name="quicksuite-chat-feedback-log-schema-format"></a>

Amazon Quick 日誌遵循結構化結構描述，其中包含所有日誌類型共用的通用欄位，以及聊天和意見回饋日誌的特定欄位。

### 常用欄位
<a name="quicksuite-chat-feedback-common-fields"></a>

所有日誌事件都包含下列常見欄位：
+ `resource_arn` – Amazon Quick 帳戶的資源 ARN （例如 `arn:aws:quicksight:us-east-1:111122223333:account/111122223333:`)
+ `event_timestamp` – Unix epoch 時間，以毫秒為單位 （例如 `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"`)

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

聊天日誌會擷取對話互動：

**注意**  
從歷史記錄和記憶體中排除的臨時對話仍會交付至聊天日誌。每個記錄都包含起始對話`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_resources``specific_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"
}
```

### 意見回饋日誌
<a name="quicksuite-chat-feedback-logs"></a>

意見回饋日誌會擷取使用者對聊天回應的意見回饋：
+ `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"
}
```

## 客服人員時數日誌
<a name="quicksuite-agent-hours-logs"></a>

此日誌類型會擷取您 Quick 帳戶中用於定價之不同客服人員的使用日誌：
+ `user_arn` – 與事件相關聯的 Amazon Quick 使用者 ARN
+ `subscription_type` – 使用者的訂閱方案。值：`ENTERPRISE`、`PROFESSIONAL`。
+ `reporting_service` – 耗用代理程式時數的快速表面。目前的值包括 `FLOW`、 `AUTOMATION`和 `RESEARCH`。當其他快速功能開始計量客服人員時數時，新值可能會顯示。
+ `usage_group` – 用量是否涵蓋在訂閱權利範圍內，或是否以超額計費。數值：
  + `Included` – 訂閱方案每日授予權利內的用量。不收取增量費用。
  + `Extra` – 超出每日授與。依用量計費。
+ `usage_hours` – 小數值，指出此記錄使用的客服人員時數
+ `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"
}
```

## 客服人員中繼資料日誌
<a name="quicksuite-agent-metadata-logs"></a>

客服人員中繼資料日誌會擷取聊天客服人員的生命週期事件，包括建立、更新、許可變更和刪除。每個代理程式操作會發出一筆記錄：
+ `user_arn` – 與事件相關聯的 Amazon Quick 使用者 ARN。
+ `event_name` – 代理程式生命週期操作。在新增新操作時`UpdateAgent``DeleteAgent`，值包括 `CreateAgent`、`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` – 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"
}
```

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

索引用量日誌會擷取知識庫和空間的每個來源儲存指標。每當發生變更 （建立、更新、同步或刪除） 時，就會發佈事件：
+ `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`。

如需針對索引用量日誌建置儀表板和執行查詢的相關資訊，請參閱 [監控索引儲存體用量](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` – 高階可用性結果。值： `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"
}
```

## 安全考量
<a name="quicksuite-chat-feedback-security-considerations"></a>
+ **加密** – 針對敏感資料使用客戶受管 AWS KMS 金鑰。
+ **存取控制** – 實作最低權限的 IAM 政策。
+ **資料保留** – 為您的合規要求設定適當的保留政策。