CloudFormation으로 CloudWatch Agent 메트릭을 감시할 때 마주치는 Host Dimension 문제

안녕하세요 클래스메소드 김재욱(Kim Jaewook) 입니다. 이번 블로그에서는 CloudFormation으로 CloudWatch Agent 메트릭을 감시할 때 마주치는 Host Dimension 문제에 대해서 살펴봤습니다.

Dimension?

CloudWatch에서 메트릭을 식별하고 필터링하기 위해 사용하는 속성을 Dimension이라고 합니다.

CloudWatch Agent는 수집한 메트릭에 추가 정보를 포함할 수 있으며, append_dimensions 설정을 통해 EC2 인스턴스 정보 등을 Dimension으로 추가할 수 있습니다.

설정 가능한 주요 Dimension 값은 다음과 같습니다.

예를 들어 InstanceId를 추가하면 동일한 메트릭이라도 인스턴스별로 구분하여 조회하거나 알람을 설정할 수 있습니다.

실무에서는 일반적으로 InstanceId를 가장 많이 사용하며, 환경에 따라 hostname이나 AutoScalingGroupName을 함께 활용하기도 합니다.

InstanceId를 사용하는 경우

InstanceId를 사용하는 경우에는 append_dimensions에 InstanceId를 추가하여 메트릭을 수집할 수 있습니다.

sudo vi /opt/aws/amazon-cloudwatch-agent/bin/config.json

{
  "metrics": {
    "append_dimensions": {
      "InstanceId": "${aws:InstanceId}"
    },
    "metrics_collected": {
      "mem": {
        "metrics_collection_interval": 300,
        "measurement": ["mem_used_percent"]
      },
      "disk": {
        "metrics_collection_interval": 300,
        "measurement": ["disk_used_percent"],
        "resources": ["/"]
      }
    }
  }
}

이렇게 설정하면 CloudWatch에서 InstanceId Dimension이 포함된 메트릭이 생성됩니다.

메트릭 상세 화면에서는 다음과 같이 InstanceId를 기준으로 조회할 수 있습니다.

동일한 disk_used_percent 메트릭이라도 어떤 Dimension을 사용하느냐에 따라 CloudWatch에서는 별도의 메트릭으로 취급됩니다.

disk_used_percent라는 지표 이름은 같지만, Dimension 구성이 다르므로 CloudWatch 내부에서는 서로 다른 메트릭으로 저장됩니다.

따라서 메트릭을 조회하거나 CloudWatch Alarm을 생성할 때는 메트릭이 생성된 Dimension과 정확히 일치하는 Dimension을 사용해야 합니다.

InstanceId와 host에서 확인할 수 있는 항목을 비교해 보겠습니다.

같은 disk_used_percent 메트릭이라도 Dimension에 따라 포함되는 속성이 달라지는 것을 확인할 수 있습니다.

CloudFormation에서도 Dimensions에 InstanceId를 지정하여 알람을 생성할 수 있습니다.

예를 들어 EC2 인스턴스 ID를 다른 스택에서 Export한 경우에는 다음과 같이 Fn::ImportValue를 사용하여 메트릭 알람을 생성할 수 있습니다.

  EC2MemoryAlarm:
    Type: AWS::CloudWatch::Alarm
    Properties:
      AlarmName: !Sub ${SystemName}-${EnvName}-ec2-memory-used-percent
      AlarmDescription: "EC2 mem_used_percent"
      Namespace: CWAgent
      MetricName: mem_used_percent
      Dimensions:
        - Name: InstanceId
          Value:
            Fn::ImportValue: !Sub ${SystemName}-${EnvName}-web

InstanceId는 CloudFormation에서 직접 참조할 수 있는 값이므로, 메트릭 수집에 사용한 Dimension과 동일한 값을 알람에도 쉽게 지정할 수 있습니다.

따라서 InstanceId를 사용하는 경우에는 CloudWatch Agent의 메트릭 수집부터 CloudWatch Alarm 생성까지 모두 CloudFormation으로 관리할 수 있습니다.

InstanceId Dimension을 사용하여 생성한 알람은 정상적으로 메트릭을 수집하며, 상태 또한 OK로 표시되는 것을 확인할 수 있습니다.

Host 사용 시 문제점

host Dimension을 사용하려면 CloudWatch Agent 설정에서 append_dimensions에 hostname을 지정할 수 있습니다.

sudo vi /opt/aws/amazon-cloudwatch-agent/bin/config.json

{
  "metrics": {
    "append_dimensions": {
      "host": "${aws:hostname}"
    },
    "metrics_collected": {
      "mem": {
        "metrics_collection_interval": 300,
        "measurement": ["mem_used_percent"]
      },
      "disk": {
        "metrics_collection_interval": 300,
        "measurement": ["disk_used_percent"],
        "resources": ["/"]
      }
    }
  }
}

이렇게 설정하면 메트릭은 hostname 값을 기준으로 CloudWatch에 수집됩니다.

이 상태에서 host Dimension을 기준으로 CloudWatch Alarm을 설정하려고 하면 다음과 같은 형태가 됩니다.

EC2MemoryAlarm:
  Type: AWS::CloudWatch::Alarm
  Properties:
    AlarmName: !Sub ${SystemName}-${EnvName}-ec2-memory
    AlarmDescription: "EC2 Memory Used Percent"
    Namespace: CWAgent
    MetricName: mem_used_percent
    Dimensions:
      - Name: host
        Value: ???  # ← 여기에서 문제가 발생한다
    Statistic: Average
    Period: 300
    EvaluationPeriods: 1
    Threshold: 80
    ComparisonOperator: GreaterThanOrEqualToThreshold
    AlarmActions:
      - Fn::ImportValue: !Sub ${EnvName}-sns-alert-mail

이 구조를 보면 두 방식의 차이가 명확하게 드러납니다.

즉, InstanceId는 CloudFormation 단계에서 충분히 다룰 수 있는 값이지만, host는 실행 환경이 준비된 이후에야 결정되는 값이라는 차이가 있습니다.

이 차이 때문에 CloudFormation 기반으로 Alarm을 구성할 때는 host Dimension을 그대로 사용하기가 어렵습니다.

결론

CloudFormation으로 CloudWatch Alarm을 생성할 계획이라면, host보다는 InstanceId를 사용하는 것이 더 적합합니다.

host Dimension은 EC2 실행 이후에 결정되는 값이기 때문에 CloudFormation 단계에서 안정적으로 참조하기 어렵습니다. 반면 InstanceId는 생성 시점에 확정되므로 알람 구성과 자동화 측면에서 훨씬 유리합니다.

따라서 CloudWatch Agent 메트릭을 CloudFormation과 함께 관리한다면 InstanceId 기반으로 설계하는 것이 일반적인 패턴입니다.

이렇게 구성하면 메트릭 수집부터 알람 설정까지 CloudFormation 기반으로 일관되게 관리할 수 있습니다.

마무리

이번 글에서는 CloudWatch Agent를 CloudFormation과 함께 사용할 때 발생할 수 있는 host Dimension의 문제와, 이를 InstanceId로 해결하는 방법에 대해 정리해봤습니다.

CloudWatch Agent는 설정에 따라 host, InstanceId, AutoScalingGroupName 등 다양한 Dimension을 메트릭에 추가할 수 있습니다. 이 Dimension은 단순한 구분값이 아니라, CloudWatch에서 메트릭을 식별하고 알람을 생성하는 기준이 되기 때문에 설계 단계에서 매우 중요한 요소입니다.

특히 host Dimension은 EC2 인스턴스가 실제로 실행된 이후에 결정되는 값이기 때문에, CloudFormation과 같이 배포 시점에 인프라를 정의하는 IaC 방식과는 궁합이 좋지 않습니다. 반면 InstanceId는 생성 시점에 확정되는 값이므로 CloudFormation과 함께 사용하기에 훨씬 안정적입니다.

결국 CloudWatch Agent 메트릭을 설계할 때는 “어떤 Dimension을 기준으로 모니터링할 것인가”를 먼저 결정해야 하며, 이는 단순한 설정 문제가 아니라 전체 모니터링 구조를 결정하는 요소라고 볼 수 있습니다.

이번 사례처럼 CloudFormation 기반으로 알람까지 자동화하려는 경우라면, host보다는 InstanceId 또는 AutoScalingGroupName 기반으로 설계하는 것이 일반적인 패턴입니다.

이렇게 구성하면 메트릭 수집부터 알람 생성까지 CloudFormation 기반으로 일관되게 관리할 수 있습니다.