기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 예약된 쿼리 시작하기
예약된 쿼리를 생성할 때 쿼리 실행 방식과 결과가 전달되는 위치를 정의하는 몇 가지 주요 구성 요소를 구성합니다. 이러한 구성 요소를 이해하면 효과적인 자동 로그 분석을 설정하는 데 도움이 됩니다.
예약된 각 쿼리는 다음과 같은 주요 구성 요소로 구성됩니다.
**쿼리 구성**
분석에 사용할 CloudWatch Logs Insights 쿼리 문자열, 대상 로그 그룹 및 쿼리 언어입니다.
**예약 표현식**
쿼리 실행 시기를 정의하는 cron 표현식 또는 빈도 달력입니다. 시간대 설정을 지정하여 쿼리가 올바른 현지 시간에 실행되도록 할 수 있습니다. 콘솔에는 “5분 동안 매주 화요일 15:10에 쿼리 실행, UTC에 즉시 적용, 무기한으로 적용”과 같이 사람이 읽을 수 있는 일정 설명이 표시됩니다.
**시간 범위**
각 쿼리 실행의 룩백 기간으로, 실행 시간의 시작 시간 오프셋으로 정의됩니다. 이는 각 쿼리 실행이 분석할 기록 데이터의 양을 결정합니다.
**실행 일정 미리 보기**
콘솔에는 정확한 날짜와 시간(예: 2025/10/28 15:10, UTC, 15:10, UTC, 2025/11/11 2025/11/04 15:10, UTC)이 포함된 다음 3개의 예약된 쿼리 실행이 표시되므로 일정이 올바르게 구성되었는지 확인할 수 있습니다.
**대상**
실행 성공 후 쿼리 결과가 전달되는 위치입니다. 지원되는 대상에는 Amazon S3 버킷이 포함되며 기본적으로 메타데이터는 기본 이벤트 버스로 전송됩니다.
**실행 역할**
CloudWatch Logs가 쿼리를 실행하고 결과를 지정된 대상으로 전송하기 위해 수임하는 IAM 역할입니다.
예약된 쿼리를 생성하기 전에 필요한 권한과 리소스가 구성되어 있는지 확인합니다.
# 예약된 쿼리 생성
CloudWatch Logs Insights 쿼리를 자동으로 실행하고 선택한 대상으로 결과를 전송하는 예약된 쿼리를 생성합니다.
## 사전 조건
예약된 쿼리를 생성하기 전에 다음이 있는지 확인합니다.
+ **로그 그룹** - 분석하려는 데이터가 포함된 하나 이상의 로그 그룹
+ **실행 IAM 역할** - 다음 권한이 있는 IAM 역할:
+ `logs:StartQuery` - CloudWatch Logs Insights 쿼리를 시작할 수 있는 권한
+ `logs:GetQueryResults` - 쿼리 결과를 검색할 수 있는 권한
+ `logs:DescribeLogGroups` - 로그 그룹 정보에 액세스할 수 있는 권한. 이는 로그 그룹 검색을 위한 접두사 기반 로그 그룹에만 필요합니다.
+ **대상 권한** - 선택한 대상에 대한 추가 IAM 권한:
+ Amazon S3 대상의 경우: `s3:PutObject`
+ ** AWS CLI 및 API 사용의 경우** - CloudWatch Logs APIs 호출할 수 있는 권한이 있는 구성된 AWS 자격 증명
자세한 IAM 정책 예제는 섹션을 참조하세요[Amazon CloudWatch Logs용 Identity and Access Management](auth-and-access-control-cwl.md). 또한 계정당 1,000개의 예약된 쿼리만 가질 수 있습니다.
------
#### [ Console ]
**예약된 쿼리를 생성하려면(콘솔)**
1. CloudWatch Logs 콘솔을 여시겠습니까? [https://us-east-1.console.aws.amazon.com/cloudwatch/homeregion=us-east-1\$1logsV2:logs-insights](https://us-east-1.console.aws.amazon.com/cloudwatch/home?region=us-east-1#logsV2:logs-insights).
1. 탐색 창에서 **Logs Insights를** 선택합니다.
1. **예약된 쿼리 생성을** 선택합니다.
1. **쿼리 정의** 섹션에서 다음을 수행합니다.
1. **쿼리 언어**의 경우 목록에서 사용할 쿼리 언어를 선택합니다.
1. **쿼리 문자열**의 경우 상자에 CloudWatch Logs Insights 쿼리를 입력합니다.
1. **로그 그룹의** 경우 목록에서 쿼리할 로그 그룹을 선택합니다.
1. **일정 설정** 섹션에서 다음을 수행합니다.
1. **일정 표현**식에서 쿼리 실행 시기를 구성합니다. 사전 정의된 옵션 중에서 선택하거나 사용자 지정 cron 표현식을 입력합니다.
1. **생성 시 유효**에서 일정이 활성화되는 시기를 지정합니다. YYYY/MM/DD 형식을 사용하여 즉시 또는 특정 날짜 및 시간에 시작하도록 선택합니다.
1. **시간 범위에서** 각 쿼리 실행의 룩백 기간을 지정합니다. 쿼리할 실행 시간과 얼마나 멀어지는지 정의하는 지속 시간을 분 단위로 입력합니다.
1. **무기한 계속**에서 일정이 종료되는 시간을 지정합니다. YYYY/MM/DD 형식을 사용하여 무기한 또는 특정 날짜 및 시간까지 실행하도록 선택합니다.
1. 콘솔에는 구성을 기반으로 다음 3개의 예약된 쿼리 실행이 표시되며 쿼리가 실행되는 정확한 날짜와 시간을 UTC 단위로 표시합니다.
1. **쿼리 결과를 S3에 게시 - 선택** 사항 섹션에서(S3 대상을 사용하는 경우):
1. **S3 버킷**의 경우 대상 버킷이 동일한 계정에 있는 경우 **이** AWS 계정을 선택하고 버킷이 다른 계정에 있는 경우 **다른** AWS 계정을 선택하고 버킷 소유 계정의 계정 ID를 입력으로 제공합니다.
1. **Amazon S3 URI**에 결과를 저장할 Amazon S3 버킷과 접두사(예: `s3://my-bucket/query-results/`)를 입력합니다. **이 계정을** 선택한 경우 ** Amazon S3 찾아보**기를 선택하여 기존 Amazon S3 위치를 탐색하고 선택할 수 있습니다.
1. (선택 사항) **KMS 키 ARN**에 고객 관리형 AWS KMS 키의 ARN을 입력하여 SSE-KMS를 사용하여 쿼리 결과를 암호화합니다. 키는 대상 Amazon S3 버킷과 동일한 AWS 리전에 있어야 합니다.
1. **Amazon S3에 쿼리 결과를 게시하기 위한 IAM 역할** 섹션에서 다음 옵션 중 하나를 선택합니다.
1. **기본 권한이 있는 새 역할 자동 생성을** 선택하여 CloudWatch Logs가 Amazon S3에 쿼리 결과를 전달하는 데 필요한 권한이 있는 IAM 역할을 자동으로 설정합니다.
1. **기존 역할 사용을** 선택하여 CloudWatch Logs가 Amazon S3에 쿼리 결과를 전송하는 데 필요한 정책이 있는 기존 IAM 역할을 선택합니다. 검색 필드를 사용하여 목록에서 적절한 IAM 역할을 찾아 선택합니다.
1. **예약된 쿼리 실행을 위한 IAM 역할** 섹션에서 다음 옵션 중 하나를 선택합니다.
1. **기본 권한이 있는 새 역할 자동 생성을** 선택하여 CloudWatch Logs가 예약된 쿼리를 실행하는 데 필요한 권한이 있는 IAM 역할을 자동으로 설정합니다.
1. **기존 역할 사용을** 선택하여 CloudWatch Logs가 예약된 쿼리를 실행하는 데 필요한 정책이 있는 기존 IAM 역할을 선택합니다. 검색 필드를 사용하여 목록에서 적절한 IAM 역할을 찾아 선택합니다.
1. **일정 생성을** 선택하여 예약된 쿼리를 생성합니다.
------
#### [ AWS CLI ]
**예약된 쿼리를 생성하려면(AWS CLI)**
+ `create-scheduled-query` 명령을 사용하여 새 예약된 쿼리를 생성합니다.
```
aws logs create-scheduled-query \
--name "ErrorAnalysisQuery" \
--query-language "CWLI" \
--query-string "fields @timestamp, @message | filter @message like /ERROR/ | stats count() by bin(5m)" \
--schedule-expression "cron(8 * * * ? *)" \
--execution-role-arn "arn:aws:iam::123456789012:role/CloudWatchLogsScheduledQueryRole" \
--log-group-identifiers "/aws/lambda/my-function" "/aws/apigateway/my-api" \
--state "ENABLED"
```
------
#### [ API ]
**예약된 쿼리를 생성하려면(API)**
+ `CreateScheduledQuery` 작업을 사용하여 새 예약된 쿼리를 생성합니다. 다음 예제에서는 1시간마다 실행되는 예약된 쿼리를 생성합니다.
```
{
"name": "ErrorAnalysisQuery",
"queryLanguage": "CWLI",
"queryString": "fields @timestamp, @message | filter @message like /ERROR/ | stats count() by bin(5m)",
"scheduleExpression": "cron(8 * * * ? *)",
"executionRoleArn": "arn:aws:iam::123456789012:role/CloudWatchLogsScheduledQueryRole",
"logGroupIdentifiers": ["/aws/lambda/my-function", "/aws/apigateway/my-api"],
"state": "ENABLED"
}
```
------
예약된 쿼리를 생성한 후 **예약된 쿼리** 페이지에서 ListScheduledQueries API를 사용하여 해당 쿼리를 보고 관리할 수 있습니다.이 API에는 이름, 생성 날짜, 마지막 실행 상태, 마지막으로 트리거된 시간 및 반복 빈도와 함께 예약된 모든 쿼리가 표시됩니다.
# 예약된 쿼리 보기 및 관리
각 쿼리에 대해 다음 정보를 사용할 수 있습니다.
**이름**
예약된 쿼리에 할당한 고유한 이름입니다. 이름을 선택하여 자세한 구성 및 실행 기록을 봅니다.
**Creation(생성) 날짜**
예약된 쿼리가 생성된 날짜로, YYYY-MM-DD 형식으로 표시됩니다.
**마지막 실행 상태**
가장 최근 쿼리 실행의 실행 상태입니다. 가능한 값은 다음과 같습니다.
+ **완료** - 쿼리가 성공적으로 실행되었으며 결과가 구성된 모든 대상으로 전송되었습니다.
+ **실패** - 쿼리 실행 또는 결과 전송에 실패했습니다. 실행 내역에서 오류 세부 정보를 확인합니다.
+ **잘못된 쿼리** - 쿼리가 유효하지 않고 구문 문제가 있습니다.
+ **제한 시간** - 쿼리가 제한 시간을 초과했습니다. 쿼리는 60분 후 자동으로 시간 초과됩니다.
**마지막 트리거 시간**
쿼리가 마지막으로 실행된 날짜와 시간으로, YYYY-MM-DD HH:MM:SS 형식으로 표시됩니다. 쿼리가 아직 실행되지 않은 경우 **없음을** 표시합니다.
**모든 반복**
쿼리의 일정 빈도입니다. cron 표현식을 사용하는 쿼리에 대한 **사용자 지정** 또는 더 간단한 일정에 대한 특정 빈도 설명을 표시합니다.
**예약된 쿼리** 페이지는 예약된 모든 쿼리에 대한 개요를 제공하며, 중앙 위치에서 예약된 모든 쿼리를 보고, 모니터링하고, 관리할 수 있도록 현재 상태 및 실행 기록을 보여줍니다. 이 정보를 사용하여 쿼리 성능을 모니터링하고, 문제를 식별하고, 자동화된 로그 분석 워크플로를 관리할 수 있습니다.
------
#### [ Console ]
**예약된 쿼리를 보려면(콘솔)**
1. CloudWatch Logs 콘솔을 여시겠습니까? [https://us-east-1.console.aws.amazon.com/cloudwatch/homeregion=us-east-1\$1logsV2:logs-insights](https://us-east-1.console.aws.amazon.com/cloudwatch/home?region=us-east-1#logsV2:logs-insights).
1. CloudWatch Logs 콘솔에서 **예약된 쿼리**, **예약된 쿼리 보기를** 선택합니다.
------
#### [ AWS CLI ]
**예약된 쿼리를 나열하려면(AWS CLI)**
+ `list-scheduled-queries` 명령을 사용하여 예약된 모든 쿼리를 나열합니다.
```
aws logs list-scheduled-queries --max-results 10
```
------
#### [ API ]
**예약된 쿼리를 나열하려면(API)**
+ `ListScheduledQueries` 작업을 사용하여 예약된 모든 쿼리를 검색합니다.
```
{
"maxResults": 10
}
```
------
**예약된 쿼리** 페이지 헤더에는 계정의 총 예약된 쿼리 수가 표시되므로 사용량을 추적하고 자동화된 로그 분석 워크플로를 효과적으로 관리할 수 있습니다.
# 예약된 쿼리 실행 기록 보기
실행 기록을 사용하여 예약된 쿼리의 성능을 모니터링하고 쿼리 실행 또는 결과 전송 문제를 해결합니다.
실행 내역에는 성공한 실행, 실패 및 대상 처리 결과를 포함하여 각 쿼리 실행의 상태가 표시됩니다. 이 정보를 사용하여 패턴을 식별하고, 문제를 진단하고, 쿼리가 예상대로 실행되고 있는지 확인할 수 있습니다.
------
#### [ Console ]
**실행 기록을 보려면(콘솔)**
1. CloudWatch Logs 콘솔에서 **예약된 쿼리**, **예약된 쿼리 보기를** 선택합니다.
1. 검사할 예약된 쿼리를 선택합니다.
1. **Execution history(실행 내역)** 탭을 선택합니다.
------
#### [ AWS CLI ]
**실행 기록을 보려면(AWS CLI)**
1. `get-scheduled-query-history` 명령을 사용하여 예약된 쿼리의 실행 기록을 검색합니다.
```
aws logs get-scheduled-query-history \
--identifier "DailyErrorMonitoring" \
--start-time 1743379200 \
--end-time 1743465600 \
--max-results 10
```
1. 실행 상태를 기준으로 필터링하려면 `--execution-statuses` 파라미터를 추가합니다.
```
aws logs get-scheduled-query-history \
--identifier "DailyErrorMonitoring" \
--start-time 1743379200 \
--end-time 1743465600 \
--max-results 1 \
--execution-statuses "SUCCEEDED"
```
------
#### [ API ]
**실행 기록을 보려면(API)**
+ `GetScheduledQueryHistory` 작업을 사용하여 실행 기록을 검색합니다.
```
{
"identifier": "DailyErrorMonitoring",
"startTime": 1743379200,
"endTime": 1743465600,
"maxResults": 10,
"executionStatuses": ["SUCCEEDED", "FAILED"]
}
```
------
실행 내역에 다음이 표시됩니다.
+ **실행 상태** - 실행 중, 완료, 실패, 제한 시간 또는 InvalidQuery
+ **트리거된 시간** - 쿼리가 실행된 시간
+ **대상** - S3 및 EventBridge를 포함하여 구성된 각 대상의 처리 상태
+ **오류 메시지** - 쿼리 실행 또는 대상 처리 실패에 대한 세부 정보
# 예약된 쿼리 업데이트
요구 사항이 발전함에 따라 예약된 쿼리 구성을 수정하여 쿼리 문자열, 일정, 대상 또는 실행 역할을 변경합니다.
쿼리 문자열, 일정 표현식, 대상 및 실행 역할을 포함하여 예약된 쿼리의 모든 측면을 업데이트할 수 있습니다. 변경 사항은 향후 실행에 즉시 적용됩니다.
------
#### [ Console ]
**예약된 쿼리를 업데이트하려면(콘솔)**
1. CloudWatch Logs 콘솔에서 **예약된 쿼리**, **예약된 쿼리 보기를** 선택합니다.
1. 업데이트할 예약된 쿼리를 선택합니다.
1. **편집**을 선택합니다.
1. 필요에 따라 구성을 수정합니다.
1. **변경 사항 저장**을 선택합니다.
------
#### [ AWS CLI ]
**예약된 쿼리를 업데이트하려면(AWS CLI)**
+ `update-scheduled-query` 명령을 사용하여 기존 예약된 쿼리를 수정합니다.
```
aws logs update-scheduled-query \
--identifier "arn:aws:logs:us-east-1:111122223333:scheduled-query:5e0c0228-1c29-4d26-904f-59f1f1ba3c8f" \
--description "Monitor for ERROR level logs daily" \
--query-language "LogsQL" \
--query-string "fields @timestamp, @message | filter @message like /ERROR/" \
--log-group-identifiers "/aws/lambda/my-function-1" "/aws/lambda/my-function-2"
```
------
#### [ API ]
**예약된 쿼리를 업데이트하려면(API)**
1. `UpdateScheduledQuery` 작업을 사용하여 예약된 쿼리 구성을 수정합니다.
```
{
"identifier": "arn:aws:logs:us-east-1:111122223333:scheduled-query:5e0c0228-1c29-4d26-904f-59f1f1ba3c8f",
"queryString": "fields @timestamp, @message | filter @message like /WARNING|ERROR/ | stats count() by bin(5m)",
"scheduleExpression": "cron(0 */2 * * ? *)",
"state": "ENABLED"
}
```
1. 여러 구성 파라미터를 한 번에 업데이트하려면:
```
{
"identifier": "arn:aws:logs:us-east-1:111122223333:scheduled-query:5e0c0228-1c29-4d26-904f-59f1f1ba3c8f",
"queryString": "fields @timestamp, @message, @level | filter @level = 'ERROR'",
"scheduleExpression": "cron(0 8,12,16 * * ? *)",
"executionRoleArn": "arn:aws:iam::111122223333:role/UpdatedScheduledQueryRole",
"logGroupIdentifiers": ["/aws/lambda/my-function", "/aws/lambda/another-function"],
"destinationConfiguration": {
"s3Configuration": {
"destinationIdentifier": "s3://111122223333-sqn-results-bucket/processed-results",
"roleArn": "arn:aws:iam::111122223333:role/Admin"
}
}
}
```
------