기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# CloudWatch Logs를 사용하여 Amazon Quick 사용량 모니터링
[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 마스킹 정책을 사용하여 로그에서 이 데이터를 마스킹할 수 있습니다. 자세한 내용은 [Help protect sensitive log data with masking](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/mask-sensitive-log-data.html)을 참조하세요.
## 지원되는 로그 대상
Amazon Quick은 다음 대상으로 로그를 전송할 수 있습니다.
+ **Amazon CloudWatch Logs** - 실시간 모니터링 및 분석용
+ **Amazon S3** - 장기 스토리지 및 배치 처리용
+ **Amazon Data Firehose** - 스트리밍 분석 및 데이터 변환용
## 사전 조건
로깅을 활성화하려면 먼저 다음 사항을 충족해야 합니다.
+ Enterprise 또는 Professional 구독이 있는 활성 Amazon Quick 인스턴스
+ 로그 전송을 구성하기 위한 적절한 IAM 권한
+ 로그에 대해 구성된 대상(CloudWatch Logs, Amazon S3 버킷 또는 Firehose)
## 로깅 구성
Amazon Quick 채팅 및 피드백에 대한 로깅을 활성화하려면 IAM 권한을 구성하고, 전송 소스 및 대상을 생성하고, 로그가 성공적으로 전송되고 있는지 확인해야 합니다.
**Topics**
+ [IAM 권한 설정](#quicksuite-chat-feedback-setup-iam-permissions)
+ [로그 구독 구성](#quicksuite-chat-feedback-configure-log-subscription)
+ [로그 전송 확인](#quicksuite-chat-feedback-verify-log-delivery)
### 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 서비스에서 로깅 활성화](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을 지정합니다. 의 경우 `CHAT_LOGS`, `AGENT_HOURS_LOGS` 또는 `logType`를 지정합니다. `FEEDBACK_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"
}
```
CloudWatch Logs API 작업을 사용하여 사용자 대화 로깅을 활성화하려면 , `PutDeliverySource` `PutDeliveryDestination`및 `CreateDelivery` API 작업을 호출합니다.
**참고**
`PutDeliverySource` 입력의 리소스 ARN에 언급된 리전에 대해 로그를 사용할 수 있습니다.
### 로그 전송 확인
구성이 완료되면 로그가 대상으로 전달되고 있는지 확인합니다.
+ **설정 확인:** CloudWatch Logs의 `DescribeDeliveries` API를 사용하여 계정에서 생성된 전송 목록을 확인합니다.
+ **CloudWatch Logs**: 지정된 로그 그룹에 새 로그 스트림이 있는지 확인합니다.
+ **Amazon S3**: 버킷에서 새 로그 파일을 모니터링합니다.
+ **Firehose**: 데이터가 전송 스트림을 통해 흐르는지 확인합니다.
## 로그 스키마 및 형식
Amazon Quick 로그는 모든 로그 유형에서 공유되는 공통 필드와 채팅 및 피드백 로그에 대한 특정 필드가 있는 구조화된 스키마를 따릅니다.
### 공통 필드
모든 로그 이벤트에는 다음과 같은 공통 필드가 포함됩니다.
+ `resource_arn` - Amazon Quick 계정의 리소스 ARN(예: `arn:aws:quicksight:us-east-1:111122223333:account/111122223333:`)
+ `event_timestamp` - 이벤트의 ISO 8601 타임스탬프(예: `1763532110061`)
+ `logType` - 로그 유형(예: `Chat` 또는 `Feedback`)
+ `accountId` - AWS 계정 ID(예: `123456789012`)
+ `user_arn` - 이벤트와 연결된 Amazon Quick 사용자 ARN(예: `"arn:aws:quicksight:us-west-2:111122223333:user/default/user"`)
### 채팅 로그
채팅 로그는 대화 상호 작용을 캡처하고 아래 필드를 포함합니다.
+ `status_code` - 채팅 요청 상태(예: `Success, request_blocked, no_answer_found` )
+ `namespace*` - 이벤트에 대한 Amazon Quick 네임스페이스(예: `default`)
+ `user_type` - 이벤트와 연결된 Amazon Quick 사용자 유형(예: `ADMIN_PRO`)
+ `conversation_id` - 사용자 대화의 고유 ID
+ `system_message_id` - 시스템에서 생성된 메시지 ID
+ `latency*` - 밀리초 단위의 채팅 메시지 지연 시간
+ `time_to_first_token*` - 첫 번째 응답 토큰의 밀리초 단위 시간
+ `message_scope` - 메시지 범위(예: `all_resources, specific_resources, no_resources` )
+ `user_message_id` - 사용자 메시지의 고유 ID
+ `user_message` - 대화의 사용자 메시지
+ `agent_id` - 채팅 에이전트의 고유 ID
+ `flow_id` - Amazon Quick Flow의 고유 ID
+ `system_text_message` - 대화의 시스템 응답
+ `surface_type*` - 대화에 사용 중인 애플리케이션
+ `web_search*` - 웹 검색 활성화 여부
+ `user_selected_resources`- 사용자가 선택한 리소스 목록
+ `action_connectors` - 작업 커넥터 목록
+ `cited_resource` - 인용된 리소스 목록
+ `file_attachment` - 사용자가 첨부한 파일 목록
다음은 채팅 로그의 예입니다.
```
{
"status_code": "success",
"namespace": "default",
"user_type": "ADMIN_PRO",
"conversation_id": "a11b2bbc-c123-3abc-a12b-12a34b5c678d",
"system_message_id": "a11b2bbc-c123-3abc-a12b-12a34b5c678d",
"latency": "10000",
"time_to_first_token": "10000",
"message_scope": "all_resources",
"user_message_id": "a11b2bbc-c123-3abc-a12b-12a34b5c678d",
"user_message": "Hi chat",
"agent_id": "a11b2bbc-c123-3abc-a12b-12a34b5c678d",
"flow_id": "a11b2bbc-c123-3abc-a12b-12a34b5c678d?",
"system_text_message": "Hello user",
"surface_type": "WEB_EXPERIENCE",
"web_search": "true"
"user_selected_resources": [{"resource_type": "Dashboard","resource_id": "146abs-1222-534894"},{"resource_type": "Space","resource_id": "123abs-1234-534894"}],
"action_connectors": [{"action_connector_id": "quicksight-website"},{"action_connector_id": "123abs-1234-534894"}]
"cited_resource": [{"cited_resource_name": "Dashboard","cited_resource_id": "146abs-1222-534894","cited_resource_name": "ds1"},{"cited_resource_name": "Space","cited_resource_id": "123abs-1234-534894","cited_resource_name": "space1"}],
"file_attachment": [{"file_attachmet_type": "pdf","file_attachment_name": "file1.pdf"},{"file_attachmet_type": "txt","file_attachment_name": "file2.txt"}]
}
```
### 피드백 로그
피드백 로그는 채팅에서 사용자 피드백을 캡처하고 아래 필드를 포함합니다.
+ `status_code` - 이벤트 전송 상태
+ `namespace*` - 이벤트에 대한 Amazon Quick 네임스페이스(예: `default`)
+ `user_type` - 이벤트와 연결된 Amazon Quick 사용자 유형(예: `ADMIN_PRO`)
+ `conversation_id` - 대화의 고유 ID
+ `system_message_id` - 시스템에서 생성한 메시지 ID
+ `user_message_id` - 사용자 메시지의 고유 ID
+ `feedback_type` - 피드백 유형(예: `Not Useful, Useful` )
+ `feedback_reason` - 사용자가 선택한 피드백 이유
+ `feedback_details` - (선택 사항) 사용자가 제공하는 추가 세부 정보
다음은 피드백 로그의 예입니다.
```
{
"status_code": "success",
"namespace": "default",
"user_type": "ADMIN_PRO",
"conversation_id": "a11b2bbc-c123-3abc-a12b-12a34b5c678d",
"system_message_id": "a11b2bbc-c123-3abc-a12b-12a34b5c678d",
"user_message_id" : "a11b2bbc-c123-3abc-a12b-12a34b5c678d",
"feedback_type" :"Not Useful / Useful"
"feedback_reason" : "Too wordy,Issue with sources,Other etc."
"feedback_details" : "additional text shared by user"
}
```
## 에이전트/조사 시간 로그
이 로그 유형은 요금에 사용되는 Quick 계정 내의 다양한 에이전트에 대한 사용 로그를 캡처합니다.
+ `subscription_type` - 엔터프라이즈 또는 전문직
+ `reporting_service` - 에이전트에 해당하는 서비스: 검색, 흐름 또는 자동화
+ `usage_group` - 지금까지의 구독 유형 및 사용량 `Included or Extra` 기준
+ `usage_hours` - 특정 로그 인스턴스의 사용 시간을 나타내는 십진수 값
+ `service_resource_arn` - 해당 에이전트 서비스의 ARN
다음은 에이전트 시간 로그의 예입니다.
```
{
"subscription_type": "ENTERPRISE",
"reporting_service": "RESEARCH",
"usage_group": "Included",
"usage_hours": 0.3333,
"service_resource_arn": "arn:aws:quicksight:eu-west-1:111222333444:research/a11b2bbc-c123-3abc-a12b-12a34b5c678d"
}
```
**참고**
\$1 '\$1'로 표시된 필드는 기본적으로 로그 구독에 추가되지 않습니다. 필요한 경우 CreateDelivery를 호출하는 동안 명시적으로 지정해야 합니다.
## 보안 고려 사항
+ **암호화**: 민감한 데이터에 고객 관리형 AWS KMS 키 사용
+ **액세스 제어**: 최소 권한 IAM 정책 구현
+ **데이터 보존**: 규정 준수 요구 사항에 적합한 보존 정책 구성