기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다. # 예약된 쿼리를 사용하여 로그 분석 자동화 예약된 쿼리를 사용하면 정기적으로 CloudWatch Logs Insights 쿼리 실행을 자동화할 수 있습니다. 로그 데이터를 분석하기 위해 쿼리를 수동으로 실행하는 대신 자동으로 실행되도록 예약된 쿼리를 구성하고 Amazon S3 버킷 또는 Amazon EventBridge 이벤트 버스와 같은 대상에 결과를 전달할 수 있습니다. 이 자동화는 정기 보고서를 생성하거나, 추세를 모니터링하거나, 로그 분석 결과를 기반으로 다운스트림 프로세스를 트리거하는 데 적합합니다. 예약된 쿼리는 CloudWatch Logs Insights에서 사용할 수 있는 세 가지 쿼리 언어를 모두 지원합니다. + [**Logs Insights 쿼리 언어(Logs Insights QL)**](CWL_AnalyzeLogData_LogsInsights.md) + [**OpenSearch Service Piped Processing Language(PPL)**](CWL_AnalyzeLogData_PPL.md) + [**OpenSearch Service Structured Query Language(SQL)**](CWL_AnalyzeLogData_SQL.md) **Topics** + [ # 예약된 쿼리 개념 이해 ](scheduled-queries-concepts.md) + [ # 일정 표현식 참조 ](scheduled-queries-schedule-reference.md) + [ # 모범 사례 ](scheduled-queries-best-practices.md) + [ # 예약된 쿼리 시작하기 ](scheduled-queries-getting-started.md) + [ # 예약된 쿼리에 대한 S3 대상 구성 ](scheduled-queries-s3-destination.md) + [ # 예약된 쿼리 문제 해결 ](scheduled-queries-troubleshooting.md) # 예약된 쿼리 개념 이해 예약된 쿼리를 생성하기 전에 쿼리 실행 방식과 결과가 전달되는 위치에 영향을 미치는 이러한 주요 개념을 이해합니다. ## IAM 역할 분리 예약된 쿼리에는 두 개의 개별 IAM 역할이 필요합니다. 하나는 쿼리를 실행하기 위한 역할이고 다른 하나는 Amazon S3 또는 Amazon EventBridge 이벤트 버스에 결과를 전달하기 위한 역할입니다. 이러한 분리가 존재하는 이유를 이해하면 권한을 올바르게 구성하고 해당 권한이 제공하는 보안 및 운영 이점을 사용하는 데 도움이 됩니다. 2역할 아키텍처는 데이터 액세스와 데이터 전송 간의 책임을 나눕니다. 쿼리 실행 역할은 로그 데이터에 액세스하고 쿼리를 실행하는 반면 대상 전송 역할은 선택한 대상에 결과를 기록합니다. 이러한 분리는 최소 권한 원칙을 따릅니다. 각 역할에는 특정 함수에 필요한 권한만 있습니다. **쿼리 실행 역할** CloudWatch Logs가 사용자를 대신하여 CloudWatch Logs Insights 쿼리를 실행하도록 허용합니다. 이 역할은 로그 그룹에 액세스하고 쿼리를 실행할 수 있는 권한이 필요하지만 대상 리소스에 액세스할 필요는 없습니다. 필요한 권한: + `logs:StartQuery` + `logs:StopQuery` + `logs:GetQueryResults` + `logs:DescribeLogGroups` + `logs:Unmask` 마스킹 해제 데이터가 필요한 경우 **KMS로 암호화된 로그 그룹의 경우:** 로그 그룹을 암호화하는 데 사용되는 KMS 키에 대한 `kms:Decrypt` 및 `kms:DescribeKey` 권한. 이러한 권한도 추가해야 합니다. **신뢰 관계 요구 사항:** 쿼리 실행 역할에는 CloudWatch Logs 서비스(`logs.amazonaws.com`)가 역할을 수임하도록 허용하는 신뢰 정책이 포함되어야 합니다. 이 신뢰 관계가 없으면 예약된 쿼리가 권한 오류와 함께 실패합니다. 쿼리 실행 역할에 대한 신뢰 정책 예제: ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "logs.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` 쿼리 실행 역할에 대한 권한 정책의 예: ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "logs:StartQuery", "logs:StopQuery", "logs:GetQueryResults", "logs:DescribeLogGroups" ], "Resource": "*" } ] } ``` **대상 전송 역할** CloudWatch Logs가 선택한 대상으로 쿼리 결과를 전송할 수 있도록 허용합니다. 이 역할에는 최소 권한 원칙에 따라 특정 대상 서비스에 대한 권한만 필요합니다. 필요한 권한은 대상 유형에 따라 다릅니다. **신뢰 관계 요구 사항:** 대상 전송 역할에는 CloudWatch Logs 서비스(`logs.amazonaws.com`)가 역할을 수임하도록 허용하는 신뢰 정책도 포함되어야 합니다. S3 대상 전송 역할에 대한 권한 정책 예제: ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:PutObject" ], "Resource": "arn:aws:s3:::your-scheduled-query-results-bucket/*" } ] } ``` 이 분리는 운영에 실질적인 이점을 제공합니다. 보안 관점에서 결과가 전달되는 위치를 변경해야 하는 경우 쿼리 실행 권한을 변경하지 않고 대상 전달 역할만 수정합니다. 규정 준수 및 감사를 위해 민감한 로그 데이터에 액세스하는 역할과 외부 시스템에 쓰는 역할을 명확하게 추적할 수 있습니다. 이렇게 하면 로그 분석 인프라가 보안 모범 사례를 따르고 있음을 더 쉽게 입증할 수 있습니다. ## 교차 리전 및 교차 계정 사용 예약된 쿼리는 특정 리전에서 생성되며 해당 리전에서 실행됩니다. 그러나 로그 그룹을 쿼리하고 리전 및 계정 간에 결과를 전달할 수 있습니다. 하나 이상의 AWS 계정을 *모니터링 계정으로* 설정하고 여러 *소스 계정*과 연결해야 합니다. 모니터링 계정은 소스 AWS 계정에서 생성된 관찰성 데이터를 보고 상호 작용할 수 있는 중앙 계정입니다. 소스 계정은 해당 계정에 있는 리소스에 대한 관찰성 데이터를 생성하는 개별 AWS 계정입니다. 소스 계정은 관측성 데이터를 모니터링 계정과 공유합니다. 따라서 연결된 모든 계정의 로그 그룹을 사용하여 모니터링 계정에서 예약된 쿼리를 설정할 수 있습니다. **교차 리전 로그 그룹 쿼리** 예약된 쿼리는 모든 리전의 로그 그룹에 액세스할 수 있습니다. 전체 ARN 형식을 사용하여 로그 그룹을 지정합니다`arn:aws:logs:region:account-id:log-group:log-group-name`. 쿼리 실행 역할에는 모든 대상 리전의 로그 그룹에 대한 `logs:StartQuery` 및 `logs:GetQueryResults` 권한이 필요합니다. **중요** 로그 그룹을 쿼리하거나 리전 간에 결과를 전송할 때 로그 데이터는 리전 경계를 넘어갑니다. 다음을 고려하세요. **데이터 레지던시 요구 사항** - 리전 간 데이터 전송이 조직의 데이터 거버넌스 정책 및 규제 요구 사항을 준수하는지 확인합니다. **데이터 전송 비용** - 리전 간 데이터 전송에는 추가 요금이 발생합니다. **네트워크 지연 시간** - 먼 리전의 로그 그룹에 액세스하는 쿼리는 지연 시간이 길어질 수 있습니다. 최적의 성능과 비용 효율성을 위해 기본 로그 그룹과 동일한 리전에서 예약된 쿼리를 생성합니다. **대체 접근 방식:** [CloudWatch Logs 중앙 집중화를](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatchLogs_Centralization.html) 사용하여 여러 계정 및 리전의 로그 데이터를 중앙 모니터링 계정으로 복제합니다. 이를 통해 단일 리전에서 모든 중앙 집중식 로그에 액세스하는 예약된 쿼리를 생성하여 리전 간 쿼리를 방지하고 IAM 권한 관리를 간소화할 수 있습니다. ## 일정 표현식 및 시간대 처리 정의한 일정에 따라 쿼리 실행 시기와 실행 빈도가 결정됩니다. 올바른 일정 표현식을 선택하면 결과를 받는 시기와 쿼리하는 데이터의 양에 영향을 줍니다. 표현식 유형을 이해하면 단순성과 정밀도 중에서 선택할 수 있습니다. Cron 표현식을 사용하면 타이밍을 정확하게 제어할 수 있으므로 정확한 시간, 요일 또는 요일을 지정할 수 있습니다. 특정 업무 시간에 실행하거나 운영 일정에 맞게 쿼리를 실행해야 하는 경우 cron 표현식을 사용합니다. 콘솔에서 간편한 일정 옵션을 사용하여 쿼리를 예약할 수도 있습니다. **cron 표현식** 특정 시간에 쿼리를 실행합니다. 형식: `cron(minute hour day-of-month month day-of-week year)` 예시: + `cron(0 9 * * ? *)` - 매일 오전 9시 UTC + `cron(0 18 ? * MON-FRI *)` - 평일 오후 6시 UTC + `cron(0 0 1 * ? *)` - 매월 1일 자정 UTC + `cron(0 12 ? * SUN *)` - 매주 일요일 정오 UTC + `cron(30 8 1 1 ? *)` - 1월 1일 오전 8시 30분 UTC 모든 예약된 쿼리는 현지 시간대 또는 AWS 리소스의 위치에 관계없이 UTC에서 실행됩니다. 이는 업무 시간 또는 시간에 민감한 분석을 위한 쿼리를 예약할 때 특히 중요합니다. 예를 들어 미국 동부 표준시로 비즈니스를 운영하고 오전 9시에 일일 보고서를 원하는 경우 UTC 오프셋(일광 절약 시간 동안 14:00 UTC, 그렇지 않으면 13:00 UTC)을 고려해야 합니다. 쿼리가 의도한 시간에 실행되도록 UTC를 염두에 두고 일정 표현식을 계획합니다. ## 쿼리 언어 선택 예약된 쿼리는 세 가지 쿼리 언어를 지원하며, 선택 사항은 쿼리를 작성하는 방법과 팀이 쿼리를 쉽게 유지 관리할 수 있는 방법에 영향을 미칩니다. 올바른 언어는 분석 요구 사항과 팀의 기존 기술에 따라 달라집니다. 주로 로그 데이터를 필터링하고 집계하는 경우 CloudWatch Logs Insights 쿼리 언어는 가장 간단한 구문을 제공합니다. 여러 단계를 통해 데이터를 재구성하거나 보강해야 하는 복잡한 데이터 변환의 경우 PPL의 파이프라인 접근 방식을 사용하면 로직을 더 쉽게 따를 수 있습니다. 데이터베이스 작업과 유사한 조인 또는 복잡한 집계를 수행해야 하는 경우 SQL은 데이터베이스 경험 팀이 빠르게 채택할 수 있는 친숙한 구문을 제공합니다. **CloudWatch Logs Insights 쿼리 언어(CWLI)** 직관적인 구문으로 로그 분석을 위해 특별히 설계되었습니다. 다음 경우에 가장 적합합니다. + 텍스트 기반 로그 분석 및 필터링 + 시계열 집계 및 통계 + 로그 분석을 처음 사용하는 팀 **OpenSearch Service Piped Processing Language(PPL)** 강력한 데이터 변환 기능을 갖춘 파이프라인 기반 쿼리 언어입니다. 다음 경우에 가장 적합합니다. + 복잡한 데이터 변환 및 보강 + 다단계 데이터 처리 워크플로 + 파이프라인 기반 처리에 익숙한 팀 **OpenSearch Service Structured Query Language(SQL)** 익숙한 데이터베이스 스타일 쿼리를 위한 표준 SQL 구문입니다. 다음 경우에 가장 적합합니다. + 복잡한 조인 및 집계 + 비즈니스 인텔리전스 및 보고 + 강력한 SQL 경험을 갖춘 팀 ## 대상 선택 및 사용 사례 쿼리 결과를 전송하는 위치에 따라 쿼리 결과를 사용하여 수행할 수 있는 작업이 결정됩니다. 이 선택은 장기 분석 구축, 자동 응답 트리거 또는 둘 다에 관계없이 전체 다운스트림 워크플로를 구성합니다. 각 대상 유형의 강점을 이해하면 사용 사례에 적합한 아키텍처를 설계하는 데 도움이 됩니다. Amazon S3 대상은 스토리지 및 배치 처리에 최적화되어 있습니다. 쿼리 결과를 몇 개월 또는 몇 년 동안 유지하거나, 시간 경과에 따른 추세를 분석하거나, 데이터를 분석 플랫폼에 제공해야 하는 경우 Amazon S3는 무제한 보존으로 비용 효율적인 스토리지를 제공합니다. EventBridge 대상은 실시간 자동화에 최적화되어 있습니다. 쿼리 결과가 알림 전송, 워크플로 시작 또는 시스템 업데이트와 같은 즉각적인 작업을 트리거해야 하는 경우 EventBridge는 애플리케이션이 즉시 응답할 수 있는 이벤트로 결과를 제공합니다. 기본적으로 모든 쿼리 완료 이벤트는 이벤트로 기본 이벤트 버스로 자동 전송되므로 다운스트림 처리 시스템, Lambda 함수 또는 기타 이벤트 기반 아키텍처와 통합할 수 있습니다. 쿼리가 성공적으로 실행된 경우에만 결과가 대상에 게시됩니다. **Amazon S3 대상** 장기 보존 및 배치 처리를 위해 쿼리 결과를 JSON 파일로 저장합니다. 다음 경우에 가장 적합합니다. + 기록 분석 및 데이터 아카이빙 + 데이터 레이크 및 분석 플랫폼과의 통합 + 규정 준수 및 감사 요구 사항 + 대규모 결과 집합의 비용 효율적인 스토리지 **EventBridge 대상** 쿼리 결과를 실시간 처리 및 자동화를 위한 이벤트로 전송합니다. 30일 동안 결과를 저장할 때만 최대 30일 동안 이벤트에서 전송된 queryId를 사용하여 쿼리 결과를 검색할 수 있습니다. 다음 경우에 가장 적합합니다. + 쿼리 결과에 대한 자동 응답 트리거 + 서버리스 워크플로 및 Lambda 함수와 통합 + 실시간 알림 및 알림 시스템 + 이벤트 기반 아키텍처 및 마이크로서비스 ## 쿼리 결과 형식 및 구조 Amazon S3 대상의 경우 - 쿼리 결과는 GetQueryResults API 응답과 동일한 구조의 JSON 형식으로 전달됩니다. Amazon EventBridge의 경우 예약된 쿼리 결과의 형식을 이해하면 다운스트림 처리 및 통합 워크플로를 설계하는 데 도움이 됩니다. 쿼리 결과는 다음 구조의 JSON 형식으로 제공됩니다. ``` { "version": "0", "id": "be72061b-eca2-e068-a7e1-83e01d6fe807", "detail-type": "Scheduled Query Completed", "source": "aws.logs", "account": "123456789012", "time": "2025-11-18T11:31:48Z", "region": "us-east-1", "resources": [ "arn:aws:logs:us-east-1:123456789012:scheduled-query:477b4380-b098-474e-9c5e-e10a8cc2e6e7" ], "detail": { "queryId": "2038fd57-ab4f-4018-bb2f-61d363f4a004", "queryString": "fields @timestamp, @message, @logStream, @log\n| sort @timestamp desc\n| limit 10000", "logGroupIdentifiers": [ "/aws/lambda/my-function" ], "status": "Complete", "startTime": 1763465460, "statistics": { "recordsMatched": 0, "recordsScanned": 0, "estimatedRecordsSkipped": 0, "bytesScanned": 0, "estimatedBytesSkipped": 0, "logGroupsScanned": 1 } } } ``` 주요 요소는 다음과 같습니다. + `statistics` - 일치, 스캔, 바이트 처리 및 예상 건너뛰기 데이터를 포함한 쿼리 성능 지표 + `startTime` - 쿼리 실행이 시작된 시간(Unix 타임스탬프) + `queryString` - 실행된 실제 쿼리 + `queryId` - 결과를 검색할 수 있는 쿼리의 쿼리 ID + `logGroupIdentifiers` - 쿼리된 로그 그룹 목록 + `status` - 쿼리 실행 상태(완료, 실패 등) # 일정 표현식 참조 이러한 참조 테이블을 사용하여 예약된 쿼리에 대한 일정 표현식을 구성합니다. 모든 시간은 협정 세계시(UTC)입니다. **Cron 표현식 구문** 형식: `cron(minute hour day-of-month month day-of-week year)` | 사용 사례 | cron 표현식 | 설명 | 사용 시기 | | --- | --- | --- | --- | | 일일 일정 | cron(0 9 \$1 \$1 ? \$1) | 매일 오전 9시 UTC | 일일 보고서 | | | cron(0 \$1/6 \$1 \$1 ? \$1) | 6시간마다(00:00, 06:00, 12:00, 18:00 UTC) | 빈번한 모니터링 | | | cron(30 2 \$1 \$1 ? \$1) | 매일 오전 2시 30분 UTC | 사용량이 적은 분석 | | 업무 시간 | cron(0 9-17 ? \$1 MON-FRI \$1) | 월요일부터 금요일까지 오전 9시부터 오후 5시까지 1시간마다 UTC | 비즈니스 모니터링 | | | cron(0 18 ? \$1 MON-FRI \$1) | 평일 오후 6시 UTC | 영업일 종료 | | | cron(0 8,12,17 ? \$1 MON-FRI \$1) | 평일 UTC 기준 오전 8시, 정오 및 오후 5시 | 주요 업무 시간 | | 주간 일정 | cron(0 12 ? \$1 SUN \$1) | 매주 일요일 정오 UTC | 주간 요약 | | | cron(0 9 ? \$1 MON \$1) | 매주 월요일 오전 9시 UTC | 주 시작 보고서 | | | cron(0 23 ? \$1 FRI \$1) | 매주 금요일 오후 11시 UTC | 주말 정리 | | 월별 일정 | cron(0 0 1 \$1 ? \$1) | 매월 1일 자정 UTC | 월별 보고서 | | | cron(0 9 L \$1 ? \$1) | 매월 마지막 날 오전 9시 UTC | 월말 처리 | | | cron(0 10 1 1,4,7,10 ? \$1) | 각 분기의 첫날 오전 10시 UTC | 분기별 분석 | | 높은 빈도 | cron(\$1/15 \$1 \$1 \$1 ? \$1) | 15분마다 | 실시간 모니터링 | | | cron(0,30 \$1 \$1 \$1 ? \$1) | 30분마다(:00 및 :30) | 빈번한 검사 | | | cron(0 \$1/2 \$1 \$1 ? \$1) | 2시간마다 | 일반 간격 | | 특수 사례 | cron(30 8 1 1 ? \$1) | 1월 1일 오전 8시 30분 UTC | 연간 보고서 | | | cron(0 6 \$1 \$1 SAT,SUN \$1) | UTC 기준 주말 오전 6시 | 주말 처리 | | | cron(0 0 ? \$1 MON\$11 \$1) | 매월 첫 번째 월요일 자정 UTC | 월별 계획 | **Cron 표현식 필드 참조** | Field | 값 | 와일드카드 | 예제 | | --- | --- | --- | --- | | 분(1분) | 0\$159 | \$1 , - / | 0 (시간 기준), \$1/15 (15분마다), 0,30 (시간당 2회) | | 시간(2번째) | 0\$123 | \$1 , - / | 9 (오전 9시), \$1/2 (2시간마다), 9-17 (영업 시간) | | Day-of-month(3일) | 1\$131, L, W | \$1 , - / ? | 1 (1일), L (마지막 날), ? (day-of-week 사용 시) | | 월(4일) | 1-12 또는 JAN-DEC | \$1 , - / | 1 (1월), JAN, 1,4,7,10 (분기별) | | Day-of-week(5일) | 1-7 또는 SUN-SAT | \$1 , - / ? \$1 L | MON-FRI (평일), SUN, MON\$11 (첫 번째 월요일) | | 연도(6년차) | 1970\$12199 | \$1 , - / | \$1 (매년), 2024 (특정 연도), 2024-2026 (범위) | **와일드카드 문자 및 특수 표현식** **`*`(별표)** 필드의 모든 값과 일치합니다. 예: 시간 필드에서 `*`는 매시간을 의미합니다. **`?` (물음표)** 특정 값이 없습니다. 다른가 지정된 경우 day-of-monthday-of-week를 사용합니다. 예: `?` day-of-month 지정할 때 day-of-week`MON-FRI`에 사용합니다. **`-`(대시)** 값의 범위입니다. 예: `MON-FRI` (월요일\$1금요일), `9-17` (오전 9시\$1오후 5시). **`,` (쉼표)** 여러 특정 값. 예: `MON,WED,FRI` (월요일, 수요일, 금요일), `8,12,17` (오전 8시, 정오, 오후 5시). **`/` (슬래시)** 단계 값 또는 증분입니다. 예: `0/15` 분 단위는 0분(0, 15, 30, 45)부터 15분마다를 의미하고, 시간 `*/2` 단위는 2시간마다를 의미합니다. **`L` (마지막)** 월 마지막 날 또는 평일의 마지막 발생. 예: day-of-month`L`은 마지막 날을 의미합니다.는 마지막 금요일을 `FRIL` 의미합니다. **`W` (평일)** 가장 가까운 평일입니다. 예:은 해당 월의 15일에 가장 가까운 평일을 `15W` 의미합니다. **`#` (n번째 발생)** 월중 평일의 N번째 발생. 예: `MON#1`는 매월 첫 번째 월요일을 의미하고,는 매월 두 번째 금요일을 `FRI#2` 의미합니다. **일반적인 패턴 및 모범 사례** + **비즈니스 애플리케이션의 경우:** 주말 또는 업무 외 시간에 쿼리를 실행하지 않으려면 `MON-FRI` 및 업무 시간(예: `9-17`)을 사용합니다. + **고주파 모니터링의 경우:** `*/15` (15분마다)와 같은 증분을 사용하지만 쿼리 동시성 제한에 유의하세요. + **리소스 효율성:** `2-6` UTC와 같은 이른 아침 시간을 사용하여 사용량이 적은 시간에 리소스 집약적인 쿼리를 예약합니다. + **월별 보고서의 경우:** 일관된 타이밍`L`을 보장하기 위해 월 마지막 날 또는 첫 번째 날과 같은 특정 날짜에 `1`를 사용합니다. # 모범 사례 다음 모범 사례를 따라 안정적이고 효율적인 예약 쿼리 작업을 보장합니다. **쿼리 최적화** + 성능 및 결과를 확인하기 위해 예약하기 전에 쿼리를 수동으로 테스트합니다. + 쿼리 초기에 필터 인덱스를 사용하여 데이터 처리 감소 + 대용량 로그 그룹의 제한 시간을 피하기 위해 시간 범위 제한 + 쿼리 복잡성 및 실행 시간 제한 고려 **일정 계획** + 예약된 다음 실행 전에 쿼리가 완료되도록 하여 중복 실행 방지 + 시간 범위를 설정할 때 로그 수집 지연 고려 + 특정 시간에 cron 표현식 사용 + 쿼리 동시성 한도에 도달하지 않도록 일정을 분산합니다. **모니터링 및 유지 관리** + 실행 기록을 정기적으로 모니터링하여 장애 또는 성능 문제 식별 + 보안을 유지하기 위해 주기적으로 IAM 역할 검토 및 업데이트 + 프로덕션에 배포하기 전에 대상 접근성 테스트 **권한 부여** + 예약된 쿼리의 모든 APIs 로그 그룹과 같은 입력에서 사용하는 리소스가 아닌 예약된 쿼리 리소스에 대해 권한을 부여합니다. 그에 따라 IAM 정책 설정 + APIs에 전달된 실행 역할을 사용하여 로그 그룹의 권한 부여 관리 # 예약된 쿼리 시작하기 예약된 쿼리를 생성할 때 쿼리 실행 방식과 결과가 전달되는 위치를 정의하는 몇 가지 주요 구성 요소를 구성합니다. 이러한 구성 요소를 이해하면 효과적인 자동 로그 분석을 설정하는 데 도움이 됩니다. 예약된 각 쿼리는 다음과 같은 주요 구성 요소로 구성됩니다. **쿼리 구성** 분석에 사용할 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. [https://us-east-1.console.aws.amazon.com/cloudwatch/home?region=us-east-1\$1logsV2:logs-insights](https://us-east-1.console.aws.amazon.com/cloudwatch/home?region=us-east-1#logsV2:logs-insights) CloudWatch Logs 콘솔을 엽니다. 1. 탐색 창에서 **Logs Insights를** 선택합니다. 1. **예약된 쿼리 생성을** 선택합니다. 1. **쿼리 정의** 섹션에서 다음을 수행합니다. 1. **쿼리 언어**의 경우 목록에서 사용할 쿼리 언어를 선택합니다. 1. **쿼리 문자열**의 상자에 CloudWatch Logs Insights 쿼리를 입력합니다. 1. **로그 그룹의** 경우 목록에서 쿼리할 로그 그룹을 선택합니다. 1. **일정 설정** 섹션에서 다음을 수행합니다. 1. **일정 표현**식에서 쿼리가 실행되는 시기를 구성합니다. 사전 정의된 옵션 중에서 선택하거나 사용자 지정 cron 표현식을 입력합니다. 1. **생성 시 유효**에서 일정이 활성화되는 시기를 지정합니다. YYYY/MM/DD 형식을 사용하여 즉시 또는 특정 날짜 및 시간에 시작하도록 선택합니다. 1. **시간 범위에서** 각 쿼리 실행의 룩백 기간을 지정합니다. 쿼리할 실행 시간과 얼마나 멀어지는지 정의하는 지속 시간을 분 단위로 입력합니다. 1. **무기한 계속**에서 일정이 종료되는 시간을 지정합니다. YYYY/MM/DD 형식을 사용하여 무기한 또는 특정 날짜 및 시간까지 실행하도록 선택합니다. 1. 콘솔에는 구성에 따라 예약된 다음 세 개의 쿼리 실행이 표시되며 쿼리가 실행되는 정확한 날짜와 시간이 UTC 단위로 표시됩니다. 1. **쿼리 결과를 S3에 게시 - 선택** 사항 섹션에서(S3 대상을 사용하는 경우): 1. **Amazon S3 URI**에 결과를 저장할 Amazon S3 버킷과 접두사(예: `s3://my-bucket/query-results/`)를 입력합니다. 1. **Amazon S3 보기를** 선택하여 새 탭에서 Amazon S3 콘솔을 열고 버킷 구성을 확인합니다. 1. **Amazon S3 브라우저**를 사용하여 기존 Amazon S3 위치를 선택하려면 Amazon S3 찾아보기를 선택합니다. 1. **Amazon S3에 쿼리 결과를 게시하기 위한 IAM 역할** 섹션에서: 1. **IAM 역할 선택**에서 필요한 정책이 있는 기존 IAM 역할을 선택하거나 **IAM 콘솔에서 새 역할 생성을** 선택하여 새 역할을 생성합니다. 1. 검색 필드를 사용하여 목록에서 적절한 IAM 역할을 찾아 선택합니다. 1. **예약된 쿼리 실행을 위한 IAM 역할** 섹션에서: 1. **IAM 역할 선택**에서 필요한 정책이 있는 기존 IAM 역할을 선택하거나 **IAM 콘솔에서 새 역할 생성을** 선택하여 새 역할을 생성합니다. 1. 검색 필드를 사용하여 목록에서 적절한 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. [https://us-east-1.console.aws.amazon.com/cloudwatch/home?region=us-east-1\$1logsV2:logs-insights](https://us-east-1.console.aws.amazon.com/cloudwatch/home?region=us-east-1#logsV2:logs-insights) CloudWatch Logs 콘솔을 엽니다. 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" } } } ``` ------ # 예약된 쿼리에 대한 S3 대상 구성 장기 보존 및 분석을 위해 예약된 쿼리 결과를 JSON 파일로 저장할 대상으로 Amazon S3를 구성합니다. Amazon S3를 대상으로 사용하는 경우 쿼리 결과는 지정된 버킷 및 접두사에 JSON 파일로 저장됩니다. 이 옵션은 결과를 아카이빙하거나, 배치 분석을 수행하거나, S3 데이터를 처리하는 다른 AWS 서비스와 통합하는 데 적합합니다. Amazon S3 대상 구성에는 다음 옵션이 포함됩니다. **Amazon S3 URI** 결과가 저장될 버킷 및 선택적 접두사(예: `s3://my-bucket/query-results/`). 상자에 전체 Amazon S3 URI를 입력합니다. **Amazon S3 보기** 이 옵션을 선택하면 새 탭에서 Amazon S3 콘솔을 열어 버킷이 존재하는지 확인하고 구성을 확인할 수 있습니다. **Amazon S3 찾아보기** 이 옵션을 선택하면 URI를 수동으로 입력하지 않고도 기존 Amazon S3 위치를 탐색하고 선택할 수 있는 Amazon S3 브라우저가 열립니다. Amazon S3 대상에 필요한 IAM 권한: + `s3:PutObject` - 지정된 Amazon S3 버킷에 쿼리 결과 파일을 쓸 수 있는 권한 Amazon S3에 쿼리 결과를 게시하기 위한 IAM 역할은 예약된 쿼리 실행을 위한 IAM 역할과 별도로 구성해야 합니다. 이렇게 분리하면 세분화된 액세스 제어가 가능하므로 Amazon S3 역할이 특히 결과 전송을 처리하는 동안 실행 역할이 쿼리를 실행할 수 있습니다. # 예약된 쿼리 문제 해결 이러한 문제 해결 주제를 사용하여 예약된 쿼리와 관련된 일반적인 문제를 해결합니다. ## 권한 오류와 함께 쿼리 실행 실패 예약된 쿼리가 실행되거나 대상에 결과를 전달하지 못하게 하는 권한 오류를 해결합니다. 권한 오류는 실행 역할에 로그 그룹에서 읽거나 대상 리소스에 쓰는 데 필요한 권한이 없는 경우에 발생합니다. **권한 오류를 해결하려면** 1. 실행 역할에 대상 로그 그룹에 대한 `logs:StartQuery``logs:GetQueryResults`, 및 `logs:DescribeLogGroups` 권한이 있는지 확인합니다. 1. 실행 역할에 대상 리소스(예: S3 버킷)`s3:PutObject`에 대한 쓰기 권한이 있는지 확인합니다. 1. 신뢰 정책에서 CloudWatch Logs가 실행 역할을 수임하도록 허용하는지 확인합니다. 역할은 신뢰 정책에서 로그 서비스 보안 주체(`logs.amazonaws.com`)를 신뢰해야 합니다. 일반적인 원인으로는 IAM 권한 누락, 정책의 잘못된 리소스 ARNs 또는 신뢰 정책 구성 문제가 있습니다. 권한 오류를 방지하려면 프로덕션에 예약된 쿼리를 배포하기 전에 실행 역할을 생성할 때 최소 권한 원칙을 사용하고 권한을 테스트합니다. ## 쿼리 제한 시간 예약된 쿼리가 최대 실행 시간 제한을 초과할 때 발생하는 제한 시간 오류를 해결합니다. 쿼리 제한 시간은 쿼리가 지정된 데이터 범위를 처리하는 데 60분 이상 걸릴 때 발생합니다. 이는 종종 대규모 데이터 세트 또는 복잡한 쿼리 로직으로 인해 발생합니다. **제한 시간 오류를 해결하려면** 1. 실행당 더 적은 데이터를 처리하도록 시작 시간 오프셋을 줄여 시간 범위를 줄입니다. 1. 쿼리 초기에 필터를 추가하여 처리되는 데이터의 양을 줄여 쿼리를 최적화합니다. 필터 인덱스를 사용하여 데이터 스캔 크기를 줄입니다. 1. 복잡한 쿼리를 더 간단하고 집중적인 쿼리로 나누는 것이 좋습니다. 일반적인 원인으로는 대규모 시간 범위 쿼리, 대용량 로그 그룹 처리 또는 적절한 필터링 없이 복잡한 집계 사용 등이 있습니다. 제한 시간을 방지하려면 CloudWatch Logs Insights에서 예상 데이터 볼륨으로 쿼리를 수동으로 테스트하고 예약 전에 성능을 최적화합니다. ## 대상 처리 실패 예약된 쿼리 결과를 구성된 대상으로 전송할 수 없을 때 발생하는 실패를 해결합니다. 대상 Amazon S3 버킷 또는 EventBridge 이벤트 버스에 액세스할 수 없거나 잘못 구성된 경우 대상 처리 실패가 발생합니다. **쿼리 결과가 대상에 게시되지 않는 실패를 해결하려면** 1. 지정된 Amazon S3 버킷이 존재하고 액세스할 수 있는지 확인합니다. 1. 대상 구성에서 올바른 URIs 확인합니다. 1. 실행 역할에 대상에 쓰는 데 필요한 권한이 있는지 확인합니다. 일반적인 원인으로는 삭제되거나 이름이 변경된 대상 리소스, 잘못된 대상 URIs 또는 네트워크 연결 문제가 있습니다. 대상 장애를 방지하려면 대상 구성을 정기적으로 검증하고 대상 리소스 가용성을 모니터링합니다. ## 잘못된 쿼리 오류 성공적인 실행을 방해하는 예약된 쿼리 문자열의 구문 및 로직 오류를 해결합니다. 쿼리 문자열에 구문 오류가 포함되거나 존재하지 않는 필드를 참조하거나 지원되지 않는 쿼리 언어 기능을 사용할 때 잘못된 쿼리 오류가 발생합니다. **잘못된 쿼리 오류를 해결하려면** 1. CloudWatch Logs Insights에서 쿼리를 수동으로 테스트하여 구문과 로직을 확인합니다. 1. 참조된 모든 로그 필드가 대상 로그 그룹에 존재하는지 확인합니다. 1. 사용 중인 쿼리 언어 기능이 예약된 쿼리에 대해 지원되는지 확인합니다. 일반적인 원인으로는 필드 이름의 오타, 잘못된 쿼리 구문 또는 예약된 실행 환경에서 지원되지 않는 쿼리 기능 사용이 있습니다. 잘못된 쿼리 오류를 방지하려면 예약하기 전에 항상 대화형으로 쿼리를 테스트하고 필드 검색 기능을 사용하여 필드 이름을 확인합니다. ## 동시성 오류 쿼리 예약된 쿼리가 Cloudwatch Logs 인사이트 쿼리와 동일한 할당량을 사용하므로 동시성 오류가 표시될 때 유의해야 할 몇 가지 중요한 사항이 아래에 나와 있습니다. 동시성 한도에 도달하지 않도록 일정을 분산하는 것이 좋습니다. + **할당량:** AWS 계정당 최대 100개의 동시 CloudWatch Logs Insights 쿼리를 실행할 수 있습니다. + **대시보드:** CloudWatch 대시보드에 추가된 쿼리도이 동시성 제한에 포함됩니다. 대시보드가 로드되거나 새로 고쳐질 때 실행되기 때문입니다. + **OpenSearch Service PPL/SQL:** AWS 계정당 최대 15개의 동시 OpenSearch PPL 또는 OpenSearch SQL 쿼리를 실행할 수 있습니다. + **교차 계정 쿼리:** 동시성 할당량은 단일 및 교차 계정 쿼리 모두에 적용됩니다. CloudWatch 교차 계정 관찰성을 사용하는 경우 연결된 소스 계정에 대해 모니터링 계정에서 시작된 쿼리도 모니터링 계정의 동시성 한도에 포함됩니다. + **빈번하지 않은 액세스 로그 그룹:** 빈번하지 않은 액세스 로그 클래스의 로그 그룹의 경우 동시 Logs Insights 쿼리의 최대 수는 5개로 제한됩니다.