# 로그 경보
로그 경보는 [예약된 쿼리](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/ScheduledQueries.html)를 사용하여 일정에 따라 실행되는 CloudWatch Logs Insights 쿼리의 결과를 모니터링합니다. 경보는 집계 표현식을 쿼리 결과에 적용하여 숫자 값을 생성하고, 집계된 값이 구성된 임곗값을 위반하면 경보가 `ALARM` 상태로 전환되고 구성된 작업을 실행합니다.
중간 단계로 지표 필터를 요구하는 지표 경보와 달리 로그 경보는 임시 분석에 사용하는 것과 동일한 Logs Insights 쿼리 언어를 사용하여 로그 데이터를 직접 평가합니다.
## 로그 경보 작동 방식
다음 단계에서는 로그 경보의 작동 방식을 설명합니다.
1. 쿼리, 집계 표현식, 일정 및 임곗값을 사용하여 로그 경보를 생성합니다.
1. CloudWatch는 지정된 일정에 따라 쿼리를 실행하는 AWS 관리형 예약된 쿼리를 자동으로 생성합니다.
1. 각 쿼리 실행은 집계된 결과(단일 값 또는 여러 기여자 값)를 생성합니다.
1. CloudWatch는 최근 쿼리 실행에 N 중 M 평가를 사용하여 임곗값에 대해 집계된 결과를 평가합니다.
1. 임곗값이 위반되면 경보가 `ALARM` 상태로 전환되고 구성된 작업(예: Amazon SNS 알림)을 실행합니다.
**참고**
로그 경보는 마지막 N개의 쿼리 실행을 평가합니다. 이러한 N개의 실행 중 M개가 임곗값을 위반하면 경보가 `ALARM` 상태로 전환됩니다.
로그 경보를 생성하려면 [로그 경보 생성](Alarm-On-Logs.md#Create_Log_Alarm) 섹션을 참조하세요.
## 관리형 예약된 쿼리 수명 주기
로그 경보를 생성하면 CloudWatch는 지정된 일정에 따라 쿼리를 실행하는 AWS 관리형 예약된 쿼리를 자동으로 생성합니다. 예약된 쿼리를 별도로 생성할 필요는 없습니다.
AWS 관리형 예약된 쿼리는 다음과 같은 특징을 가지고 있습니다.
+ 이 쿼리는 CloudWatch Logs 콘솔의 예약된 쿼리 아래에 표시됩니다.
+ 직접 수정할 수는 없습니다. 쿼리 또는 해당 구성을 변경하려면 로그 경보를 업데이트합니다.
+ 경보를 삭제하면 CloudWatch가 AWS 관리형 예약된 쿼리를 삭제합니다.
## 로그 경보 구성
로그 경보는 다음 파라미터로 구성됩니다.
+ **QueryString**은 실행할 CloudWatch Logs Insights 쿼리입니다.
+ **LogGroupIdentifiers**는 쿼리할 로그 그룹입니다. 로그 그룹 이름 또는 로그 그룹 ARN을 지정합니다.
+ **ScheduledQueryRoleARN**은 CloudWatch Logs가 사용자를 대신하여 예약된 쿼리를 실행하도록 허용하는 IAM 역할의 ARN입니다.
+ **AggregationExpression**은 쿼리 결과를 임곗값 평가를 위한 숫자 값으로 집계하는 방법을 정의합니다.
+ **ScheduleExpression**은 쿼리 실행 빈도를 정의합니다(예: `rate(5 minutes)`).
+ **StartTimeOffset**은 각 쿼리 실행에 대한 룩백 기간을 초 단위로 정의합니다.
+ **EndTimeOffset**은 현재 시간을 기준으로 초 단위의 오프셋으로 쿼리 시간 범위의 끝을 정의합니다.
+ **ComparisonOperator**는 집계된 결과를 임곗값과 비교하는 방법입니다. 유효한 값: `GreaterThanThreshold`, `GreaterThanOrEqualToThreshold`, `LessThanThreshold`, `LessThanOrEqualToThreshold`.
+ **Threshold**는 비교할 숫자 값입니다.
+ **QueryResultsToEvaluate**는 평가할 최근 쿼리 실행 횟수입니다(N 중 M의 N).
+ **QueryResultsToAlarm**은 `ALARM` 트리거에 필요한 위반 결과 수입니다(N 중 M의 M).
+ **TreatMissingData**는 평가 중 누락된 쿼리 결과를 처리하는 방법을 정의합니다.
전체 파라미터 목록 및 생성 지침은 [로그 경보 생성](Alarm-On-Logs.md#Create_Log_Alarm) 섹션을 참조하세요.
## 로그 쿼리
로그 경보 쿼리는 평가할 로그 데이터를 선택하고 필터링하는 CloudWatch Logs Insights 쿼리입니다. 쿼리는 `StartTimeOffset` 및 `EndTimeOffset`에서 정의한 시간 범위 동안 `LogGroupIdentifiers`에 지정된 로그 그룹에서 실행됩니다.
이 쿼리는 [CloudWatch Logs Insights 쿼리 구문](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html)을 사용합니다. 로그 경보에 대한 효율적인 쿼리 작성 지침은 [모범 사례 및 문제 해결](#log-alarm-best-practices) 섹션을 참조하세요.
## 집계 표현식
집계 표현식은 CloudWatch가 쿼리 결과를 임곗값 평가를 위한 숫자 값으로 요약하는 방법을 정의합니다. 표현식은 CloudWatch Logs Insights의 `stats` 명령과 동일한 구문을 사용합니다.
집계 표현식의 구문은 다음과 같습니다.
```
statistic_func_expression [by field1, field2, ...] [| sort asc|desc]
```
단일 집계 표현식만 지정할 수 있습니다. 다음 표에는 지원되는 집계 함수가 나열되어 있습니다.
| 함수 | 설명 | 예제 |
| --- | --- | --- |
| count(\*) | 일치하는 모든 로그 라인의 개수입니다. | count(\*) |
| avg(field) | 지정된 필드의 평균값입니다. | avg(duration) |
| sum(field) | 지정된 필드의 합계입니다. | sum(bytesSent) |
| min(field) | 지정된 필드의 최솟값입니다. | min(latency) |
| max(field) | 지정된 필드의 최댓값입니다. | max(latency) |
집계 표현식 `by` 절에서는 `bin()` 함수가 지원되지 않습니다. 그러나 쿼리 문자열 자체에서 `bin()`를 사용할 수 있습니다.
## 다중 기여자 경보
집계 표현식에 `by` 절을 포함하면 경보는 고유한 필드 값 조합(*기여자*라고 함)을 각각 독립적으로 평가합니다. 기여자가 임곗값을 위반하면 경보가 `ALARM` 상태로 전환됩니다.
예를 들어 다음 표현식은 서비스 이름별로 오류 수를 그룹화합니다.
```
count(*) by serviceName
```
`serviceName`의 각 고유 값은 임곗값에 대해 독립적으로 평가됩니다. N번의 쿼리 실행 중 M번에서 어떤 서비스라도 임곗값을 초과하면 경보가 `ALARM` 상태로 전환됩니다.
다중 기여자 경보에는 다음 제한이 적용됩니다.
+ `by` 절에는 최대 5개의 필드를 지정할 수 있습니다.
+ 쿼리 실행당 반환되는 기여자 결과는 최대 500개입니다.
+ `ALARM` 상태에서 동시에 추적되는 기여자는 최대 100명입니다.
기본적으로 기여자는 알파벳순으로 정렬되며 쿼리 실행당 처음 500개만 반환됩니다. 대신 집계된 값을 기준으로 기여자를 정렬하려면 집계 표현식에 `| sort asc` 또는 `| sort desc`를 지정합니다(예: `avg(latency) by serviceName | sort desc`). 값 기반 정렬을 사용하면 총 수가 500개를 초과할 때 가장 중요한 기여자가 먼저 평가됩니다.
다중 기여자 경보의 경우 Amazon SNS 및 Lambda 작업은 기여자 수준에서 실행됩니다(위반하는 기여자당 한 번씩). Systems Manager OpsItem 작업은 경보 수준에서 실행됩니다.
**참고**
로그 경보에는 Systems Manager Incident Manager 및 조사 작업이 지원되지 않습니다.
기여자가 쿼리 결과에서 사라지면(예: 임시 리소스가 종료됨) 해당 기여자는 누락된 데이터 처리 설정에 관계없이 `OK` 상태로 전환됩니다.
## 누락 데이터 처리
예약된 쿼리 실행이 임곗값에 대해 평가할 수 있는 값을 생성하지 않을 때 데이터 누락이 발생합니다. 이 동작은 다음과 같은 경우에 발생합니다.
**로그 없음** - 로그 그룹에 쿼리 시간 범위의 로그 이벤트가 없습니다.
**쿼리가 적용 가능한 결과를 반환하지 않음** - 로그가 있지만 집계 표현식이 값을 생성할 수 없습니다. 이러한 현상은 다음과 같은 경우에 발생합니다.
+ 쿼리 필터 조건에 부합하는 쿼리 결과가 존재하지 않는 경우
+ 집계 표현식에서 참조되는 필드가 쿼리 결과에 존재하지 않는 경우 (예: `count(error-codes)`에서 반환된 로그 이벤트에 `error-codes`가 존재하지 않음)
빈 결과 집합에서 `count(*)`를 실행하면 0이 반환되는데, 이는 유효한 데이터 포인트이며 누락된 데이터로 간주되지 않습니다.
`TreatMissingData` 파라미터를 사용하여 경보가 누락된 데이터를 처리하는 방식을 구성할 수 있습니다. 다음 표에서는 사용 가능한 옵션을 설명합니다.
| 값 | 동작 |
| --- | --- |
| missing | 데이터 포인트를 누락으로 처리합니다. 이 값이 기본값입니다. |
| notBreaching | 누락 데이터 포인트를 임곗값을 위반하지 않은 것으로 처리합니다. |
| breaching | 누락 데이터 포인트를 임곗값을 위반한 것으로 처리합니다. |
| ignore | 누락된 데이터 포인트를 무시하고 사용 가능한 데이터만 평가합니다. |
## 평가 상태
로그 경보는 표준 `OK`, `ALARM` 및 `INSUFFICIENT_DATA` 상태 외에도 `EvaluationState` 필드에 다음 평가 상태를 보고할 수 있습니다. 이러한 상태는 경보가 현재 상태에 있는 이유에 대한 추가 컨텍스트를 제공합니다.
| State | 설명 |
| --- | --- |
| EVALUATION\_FAILURE | 일시적인 CloudWatch 서비스 문제로 인해 평가가 이루어지지 않았습니다. 서비스 오류로 인해 서비스에서 쿼리 결과를 평가하는 데 문제가 있거나 일부(전부는 아님) 쿼리 결과가 실패한 경우 이러한 현상이 발생할 수 있습니다. 경보가 INSUFFICIENT\_DATA로 전환됩니다. 문제가 해결될 때까지 수동 모니터링을 사용하는 것이 좋습니다. |
| EVALUATION\_ERROR | 클라이언트 구성 오류로 인해 평가가 이루어지지 않았습니다. 권한 부족, 잘못된 쿼리 또는 모든 쿼리 결과가 실패한 경우 이러한 현상이 발생할 수 있습니다. 경보는 즉시 INSUFFICIENT\_DATA로 전환됩니다. 자세한 내용은 StateReason 필드를 참조하세요. |
| PARTIAL\_DATA | 쿼리는 최대 500개의 기여자 그룹을 반환했지만, 실제로는 더 많은 그룹이 일치했습니다. 경보는 사용 가능한 기여자를 평가하지만 결과가 불완전할 수 있습니다. |
## 경보 업데이트
로그 경보의 쿼리, 집계 표현식, 일정 또는 로그 그룹을 업데이트하면 충분한 새 데이터 포인트가 수집될 때까지 경보가 `INSUFFICIENT_DATA`로 전환됩니다. 임곗값 또는 N 중 M 값을 변경해도 이 재설정이 트리거되지 않습니다.
## 작업 및 알림
로그 경보는 다음 작업을 지원합니다.
+ Amazon SNS 알림
+ Lambda 함수 간접 호출
+ Systems Manager OpsItem 생성
전체 작업 지원 매트릭스는 [경보 작업](alarm-actions.md) 섹션을 참조하세요.
로그 경보 상태가 전환되면 작업 알림에 다음 정보가 포함됩니다.
+ 표준 경보 구성 변경 정보(경보 이름, 설명, 구성 세부 정보)
+ 상태 변경 정보(새 상태, 상태 이유, 타임스탬프)
+ Amazon SNS 이메일 알림에는 전체 쿼리 결과를 보여주는 CloudWatch Logs Insights 콘솔에 대한 딥 링크도 포함되어 있습니다.
다음 예제에서는 단일 값 로그 경보(`BY` 절 없음)에 대한 Amazon SNS 이메일 알림을 보여줍니다.
```
{
"AlarmName": "HighErrorCount",
"NewStateValue": "ALARM",
"NewStateReason": "Threshold Crossed: 3 out of the last 5 query results [142.0 (10/06/26 12:15:00), 135.0 (10/06/26 12:10:00), 120.0 (10/06/26 12:05:00)] were greater than the threshold (100.0) (minimum 3 datapoints for OK -> ALARM transition).",
"NewStateReasonData": {
"version": "1.0",
"queryDate": "2026-06-10T12:15:30.000+0000",
"threshold": 100.0,
"queryResultsToEvaluate": 5,
"queryResultsToAlarm": 3,
"results": [
{
"queryResultId": "scheduled-query-execution-id-3",
"status": "COMPLETE",
"timestamp": "2026-06-10T12:15:00.000+0000",
"value": 142.0
}
// Additional results...
]
},
"StateChangeTime": "2026-06-10T12:15:30.000+0000",
"OldStateValue": "OK"
// Additional fields...
}
```
다음 예제에서는 다중 기여자 로그 경보(`BY` 절 있음)에 대한 Amazon SNS 이메일 알림을 보여줍니다. 위반하는 각 기여자는 별도의 알림을 생성합니다.
```
{
"AlarmName": "EndpointLatency",
"NewStateValue": "ALARM",
"NewStateReason": "5 out of 10 contributors evaluated to ALARM",
"StateChangeTime": "2026-06-10T12:20:15.000+0000",
"OldStateValue": "OK",
"AlarmContributorId": "a1b2c3d4e5f6g7h8",
"AlarmContributorAttributes": {
"endpoint": "/api/orders"
}
// Additional fields...
}
```
### 알림에 로그 라인 포함
필요에 따라 `ActionLogLineCount` 파라미터를 1에서 50 사이의 값으로 설정하여 경보 알림에 원시 쿼리 결과 로그 라인을 포함할 수 있습니다. 집계된 값이 아니라 집계 표현식이 평가되는 기본 로그 이벤트입니다. 기본값은 0입니다. 즉, 로그 라인이 포함되지 않습니다.
**참고**
로그 라인은 Amazon SNS 이메일 알림에만 포함됩니다. Lambda 작업은 페이로드에 로그 라인을 포함하지 않습니다.
**중요**
알림에 로그 라인을 포함하면 Amazon SNS 메시지에 로그의 민감한 데이터가 노출될 수 있습니다. 이 기능을 활성화하기 전에 로그 콘텐츠를 검토하십시오.
로그 라인을 포함하려면 로그 라인 역할에 `logs:GetQueryResults` 권한이 있어야 합니다. 알림에 포함된 로그 라인 수는 요청된 수, 사용 가능한 총 결과 및 Amazon SNS 페이로드 크기 제한에 따라 제한됩니다.
## 모범 사례 및 문제 해결
### 모범 사례
**쿼리 최적화**
+ CloudWatch Logs Insights에서 수동으로 쿼리를 테스트한 후 로그 경보에서 쿼리를 사용하여 성능과 예상 결과를 확인합니다.
+ 쿼리 초기에 필터 명령을 사용하여 처리되는 데이터 양을 줄입니다.
+ 대용량 로그 그룹의 제한 시간을 방지하려면 쿼리 시간 범위(StartTimeOffset)를 제한합니다.
+ 필드 인덱스를 사용하여 쿼리 성능을 최적화합니다.
**일정 계획**
+ 다음 실행 전에 쿼리를 완료할 수 있는 일정 빈도를 선택합니다. 대용량 로그 그룹의 경우 더 긴 간격(예: 5분 대신 10분)을 사용합니다.
+ StartTimeOffset 설정 시 로그 수집 지연을 고려합니다. EndTimeOffset과 현재 시간 사이의 간격이 짧으면 불완전한 데이터 평가를 방지하는 데 도움이 됩니다.
+ 예약된 쿼리 동시성 한도에 도달하지 않도록 계정 전체에 로그 경보 일정을 분산합니다. 계정 전체에서 동시 쿼리 실행은 100을 초과할 수 없습니다. 일정이 겹치는 여러 로그 경보를 생성할 때 이 할당량을 고려하십시오.
**임곗값 조정**
+ 일시적인 급증으로 인한 경보 노이즈를 줄이려면 더 높은 QueryResultsToEvaluate(N) 값으로 시작하십시오.
+ 희소 이벤트(예: 드물게 발생하는 오류)의 경우 로그가 일치하지 않을 때 경보를 OK 상태로 유지하려면 TreatMissingData를 `notBreaching`으로 설정합니다.
+ 연속 신호(예: 트래픽 로그)의 경우 예상되는 로그 데이터의 수신이 중단되었을 때 이를 감지할 수 있도록 TreatMissingData를 `breaching`으로 설정하는 것을 고려하십시오.
**다중 기여자 설계**
+ 독립적으로 모니터링하려는 고유한 리소스 또는 차원을 나타내는 BY 절의 의미 있는 필드를 선택합니다.
+ 쿼리 실행당 처음 500개의 기여자만 반환된다는 점에 유의하세요. 더 많은 결과를 원하면 쿼리 범위를 좁히거나 더 적은 BY 절 필드를 사용합니다.
+ 집계 표현식에서 `| sort desc` 또는 `| sort asc` 접미사를 사용하여 500 기여자 한도에 도달하면 비교 연산자를 기반으로 가장 높거나 가장 낮은 값의 우선 순위를 지정합니다.
### 문제 해결
**경보가 INSUFFICIENT\_DATA에 유지됨**
| 가능한 원인 | 해결 방법 |
| --- | --- |
| 예약된 쿼리 실행 역할에 권한이 없음 | 역할에 올바른 로그 그룹으로 범위가 지정된 logs:StartQuery, logs:StopQuery, logs:GetQueryResults 및 logs:DescribeLogGroups 권한이 있는지 확인합니다. |
| 로그 그룹이 존재하지 않거나 삭제되었습니다. | 경보 구성의 로그 그룹 ARN이 올바르고 액세스 가능한지 확인합니다. |
| 최근에 생성되거나 업데이트된 경보 | 생성 또는 구성 업데이트 후 N 중 M 평가 기간을 충족하기에 충분한 쿼리 실행이 완료될 때까지 경보는 INSUFFICIENT\_DATA에 남아 있습니다. |
| 예약된 쿼리가 실행되고 있음 | CloudWatch Logs 콘솔에서 AWS 관리형 예약된 쿼리를 확인하여 일정에 따라 실행되고 있는지 확인합니다. |
| 쿼리 결과에 집계 필드가 없음 | 집계 표현식에서 참조되는 필드가 쿼리 결과에 존재해야 합니다. 예를 들어 집계가 avg(latency)인 경우 쿼리가 latency 필드를 생성하는지 확인합니다. 필드가 없으면 결과가 누락된 데이터로 처리됩니다. |
| 로그 수집 지연 | 예약된 쿼리는 실행 시간에 따라 수집된 로그 이벤트만 평가할 수 있습니다. `StartTimeOffset`과 `EndTimeOffset`은 실행 시간 T를 기준으로 쿼리 기간을 정의합니다([T − StartTimeOffset, T − EndTimeOffset]). 그러나 수집 지연은 고려하지 않습니다. 쿼리하는 기간에 대해 이벤트가 계속 수집되는 경우 쿼리는 이벤트가 사용 가능해지기 전에 실행되어 해당 이벤트를 건너뜁니다.
`EndTimeOffset`을 사용하여 전체 범위에서 수집이 완료될 만큼 기간을 뒤로 이동합니다.
예: 이벤트가 발생한 후 로그를 쿼리할 수 있게 되는 데 최대 2분이 걸린다고 가정합니다.+ `StartTimeOffset=60, EndTimeOffset=0` – 기간 [T−60s, T]. 기간은 실행 시점에 종료되므로 최근 이벤트는 아직 수집되지 않아 누락됩니다.
+ `StartTimeOffset=180, EndTimeOffset=120` - 창 [T−180s, T−120s]. 기간은 2분 전에 종료되며 이때까지 모든 이벤트가 수집되어 평가 가능합니다. |
**경보에 EVALUATION\_ERROR 표시**
이는 클라이언트 구성 문제를 나타냅니다. 자세한 내용은 StateReason 필드를 확인하세요. 일반적인 원인:
+ 쿼리 구문이 잘못되었거나 형식이 잘못되었습니다.
+ 예약된 쿼리 실행 역할에 대한 권한이 부족합니다.
+ 모든 쿼리 실행이 실패했습니다(예: 로그 그룹 권한이 취소됨).
**경보에 EVALUATION\_FAILURE 표시**
이는 일시적인 CloudWatch 서비스 문제를 나타냅니다. 문제가 해결되면 경보가 자동으로 복구됩니다. 몇 분 이상 지속되면 CloudWatch 서비스 상태 대시보드를 확인하세요.
**경보에 PARTIAL\_DATA 표시**
쿼리는 최대 500개의 기여자 그룹을 반환했지만 더 많은 그룹이 일치했습니다. 경보는 사용 가능한 기여자를 평가하지만 결과가 불완전할 수 있습니다. 쿼리 범위를 좁히거나 BY 절 필드 수를 줄이는 것을 고려하십시오.
**알림에 로그 라인이 표시되지 않음**
+ `ActionLogLineCount`가 1에서 50 사이의 값으로 설정되어 있는지 확인합니다.
+ 로그 라인 역할에 올바른 로그 그룹으로 범위가 지정된 `logs:GetQueryResults` 권한이 있는지 확인합니다.
+ 로그 라인은 Amazon SNS 이메일 알림에만 포함됩니다. 다른 작업 유형에는 로그 라인이 포함되지 않습니다.
+ `unmask()`를 사용하는 쿼리는 알림에 로그 라인을 포함할 수 없습니다(생성 시 거부됨).
쿼리 최적화, 모니터링 및 권한 부여에 대한 추가 모범 사례는 *Amazon CloudWatch Logs 사용 설명서*의 [예약된 쿼리 모범 사례](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/scheduled-queries-best-practices.html)를 참조하세요.