Amazon CloudWatch 어노테이션

Amazon CloudWatch 어노테이션 (Amazon CloudWatch annotations)

어노테이션은 그래프 위에 풍부한 이벤트 정보를 겹쳐 표시해요. Amazon CloudWatch 데이터 소스에서 어노테이션은 CloudWatch 알람 히스토리를 기반으로 해요. 대시보드 시간 범위 내의 각 알람 히스토리 항목(상태 변경, 구성 업데이트, 액션 등)이 어노테이션이 되어 알람 활동을 나머지 대시보드 데이터와 상관관계로 분석할 수 있어요.

출처: 문서

본문

시작하기 전에

CloudWatch 어노테이션 동작 방식

자유 형식 쿼리로 어노테이션을 만드는 데이터 소스와 달리, CloudWatch 어노테이션은 기존 CloudWatch 알람을 쿼리하고 상태 변경 히스토리를 반환해요. Grafana는 두 가지 방법 중 하나로 일치하는 알람을 찾아 cloudwatch:DescribeAlarmHistory로 각 알람의 히스토리를 가져오고 모든 히스토리 항목을 어노테이션으로 렌더링해요:

  • 메트릭으로 알람 일치: Grafana가 cloudwatch:DescribeAlarmsForMetric을 호출해 특정 메트릭에 연결된 알람을 찾아요.
  • 접두사로 알람 일치: Grafana가 알람 이름과 액션 접두사로 cloudwatch:DescribeAlarms를 호출해, AWS가 그 접두사로 시작하는 이름·액션을 가진 알람만 반환하게 해요. Grafana는 반환된 알람을 지정한 네임스페이스·메트릭 이름·차원·통계·기간으로 필터링해요.

각 어노테이션에는 알람 이름이 제목으로, 알람 히스토리 항목 유형이 태그(예: StateUpdate, ConfigurationUpdate, Action)로, 히스토리 요약이 텍스트로 포함돼요.

어노테이션 쿼리 만들기

  1. 어노테이션을 추가할 대시보드를 열어요.
  2. Edit을 클릭한 뒤 상단 네비게이션에서 Settings를 클릭해요.
  3. Annotations 탭을 선택해요.
  4. Add annotation query를 클릭해요.
  5. 어노테이션의 Name(예: CloudWatch alarms)을 입력해요.
  6. Amazon CloudWatch 데이터 소스를 선택해요.
  7. 다음 섹션에 설명된 쿼리 필드를 구성해요.
  8. Save dashboard를 클릭해요.

어노테이션 쿼리 편집기 필드:

Field Description
Region 알람을 쿼리할 AWS 리전.
Namespace 메트릭 네임스페이스 (예: AWS/EC2).
Metric name 알람이 관찰하는 메트릭 이름 (예: CPUUtilization).
Statistic 알람이 사용하는 통계 (예: Average).
Dimensions 리소스를 식별하는 차원 (예: InstanceId).
Period 선택. 데이터 포인트 간 최소 간격(초). 접두사 일치 비활성 시 기본 300.
Enable Prefix Matching 선택. 메트릭 대신 이름·액션 접두사로 알람 일치.
Action 액션이 이 접두사로 시작하는 알람만 일치. 접두사 일치 활성화 시 사용 가능하며 쿼리 실행에 필요.
Alarm Name 이름이 이 접두사로 시작하는 알람만 일치. 접두사 일치 활성화 시 사용 가능하며 쿼리 실행에 필요.

메트릭으로 알람 일치

Enable Prefix Matching이 꺼져 있을 때의 기본 동작이에요. Grafana는 지정한 메트릭에 연결된 모든 알람에 대한 어노테이션을 반환해요. 메트릭으로 일치할 때 Region·Namespace·Metric name·Statistic이 모두 필요해요. 하나라도 없으면 쿼리가 invalid annotations query 오류를 반환해요. Dimensions는 선택이지만 추가하면 특정 리소스의 알람으로 결과를 좁혀요. 예를 들어 단일 EC2 인스턴스의 CPU 활용 알람 히스토리를 어노테이션하려면: Region us-east-1, Namespace AWS/EC2, Metric name CPUUtilization, Statistic Average, Dimensions InstanceId = i-0123456789abcdef0.

접두사로 알람 일치

Enable Prefix Matching을 켜면 특정 메트릭 대신 이름·액션 접두사로 알람을 찾아요. Grafana는 Alarm Name과 Action 접두사를 사용해 cloudwatch:DescribeAlarms에서 최대 100개 알람을 요청한 뒤, 지정한 네임스페이스·메트릭 이름·차원·통계·기간으로 반환된 알람을 필터링해요. 쿼리가 실행되려면 Alarm Name 접두사와 Action 접두사를 모두 제공해야 해요. 접두사 일치는 관련 알람 그룹을 표시하려고 할 때 사용해요 — 예를 들어 특정 SNS 액션을 트리거하는 모든 프로덕션 알람. 이를 위해 Enable Prefix Matching을 켜고 Alarm Name을 prod-로, Action을 arn:aws:sns:us-east-1:123456789012:prod- 같은 SNS 토픽 ARN 접두사로 설정해요.

필수 권한

어노테이션 쿼리는 데이터 소스를 실행하는 역할 또는 사용자에 연결된 IAM 정책에 다음 CloudWatch API 액션을 요구해요:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowReadingAlarmsFromCloudWatch",
      "Effect": "Allow",
      "Action": ["cloudwatch:DescribeAlarms", "cloudwatch:DescribeAlarmsForMetric", "cloudwatch:DescribeAlarmHistory"],
      "Resource": "*"
    }
  ]
}

구성 페이지의 metrics IAM 정책은 이미 이 액션을 포함해요.

어노테이션 문제 해결

어노테이션이 나타나지 않음:

  • 대시보드 시간 범위 내에 알람 상태 변경이 있는지 확인해요. 어노테이션은 알람 히스토리에서 오므로, 상태가 한 번도 변경되지 않은 알람은 어노테이션을 만들지 않아요.
  • Region·Namespace·Metric name·Statistic·Dimensions가 기존 알람과 정확히 일치하는지 확인해요.
  • IAM 역할·사용자가 cloudwatch:DescribeAlarms, cloudwatch:DescribeAlarmsForMetric, cloudwatch:DescribeAlarmHistory 권한을 가졌는지 확인해요.

invalid annotations query 오류:

  • 이 오류는 접두사 일치가 비활성화되고 쿼리가 빈 Region·Namespace·Metric name·Statistic으로 백엔드에 도달할 때 나타나요. 네 필드를 모두 제공하거나 Enable Prefix Matching을 활성화하세요.
  • 대시보드 어노테이션 편집기에서 불완전한 메트릭 쿼리는 오류를 반환하는 대신 조용히 건너뛰어 어노테이션이 만들어지지 않는 경우가 많아요. 어노테이션이 보이지 않으면 모든 필수 필드가 설정됐는지 확인하세요.

관련 리소스

더 알아보기 (Learn more)