AWS CloudWatch Agent로 서버 메트릭과 로그를 수집하다 보면, 어느 날부터인가 설정이 더 이상 반영되지 않는 것처럼 보이거나, 직접 수정한 amazon-cloudwatch-agent.json 파일이 사라진 것처럼 느껴지는 순간이 있습니다.
“분명 json을 고쳤는데, 왜 Agent는 예전 설정대로만 동작할까?”
이 현상은 대개 CloudWatch Agent가 실제로는 .toml 파일을 기준으로 실행된다는 점과, fetch-config 명령의 동작 방식을 정확히 이해하지 못한 데서 시작됩니다.
이 글에서는 CloudWatch Agent 설정 파일 구조(json vs toml), fetch-config의 작동 방식, json 파일이 사라지거나 무시되는 것처럼 보이는 이유를 정리하고, 운영 환경에서 안전하게 설정을 관리하는 방법까지 함께 살펴보겠습니다.
구조 이해: JSON vs TOML
CloudWatch Agent는 설정 파일로 두 가지 포맷을 사용할 수 있습니다:
| 파일명 | 용도 | 생성 방식 |
|---|---|---|
amazon-cloudwatch-agent.json | 사용자가 작성하거나 위저드로 생성한 입력 파일 | 수동 작성 또는 amazon-cloudwatch-agent-config-wizard 사용 |
amazon-cloudwatch-agent.toml | Agent가 실제 실행 시 사용하는 실행 설정 파일 | fetch-config 실행 시 자동 생성됨 |
동작 흐름
CloudWatch Agent를 실행할 때 다음과 같은 명령을 많이 사용합니다.
sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl \
-a fetch-config \
-m ec2 \
-c file:/opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.json \
-s
이 명령은 다음과 같이 작동합니다:
.json 파일을 읽어 구성 내용을 검증
.toml 파일로 변환하여 저장
Agent는 .toml 파일을 기반으로 실행
즉, .json은 구성 입력용, .toml은 실행용입니다.
.json 파일이 사라지는 이유?
일반적으로는 사라지지 않지만 다음과 같은 상황에서 삭제될 수 있습니다:
amazon-cloudwatch-agent.json 대신 .toml을 직접 실행 대상으로 지정한 경우
권한 또는 스크립트 오류로 인해 fetch-config 명령 수행 후 덮어씌움 발생
사용자 스크립트가 파일을 정리하는 과정에서 의도치 않게 삭제
권장 방식
항상 .json 원본을 백업
CloudWatch Agent 설정은 아래 두 단계로 진행하세요:
# 1단계: 기존 Agent 중지
sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a stop
# 2단계: .json 구성 파일을 사용해 설정 적용
sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl \
-a fetch-config \
-m ec2 \
-c file:/opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.json \
-s
.json 파일이 사라졌다면 다시 복사하거나 생성 후 위 단계를 반복하면 됩니다.
마무리
CloudWatch Agent는 구성 파일을 직접 실행하지 않고, 내부적으로 .toml 파일을 기반으로 작동합니다.
.json은 임시이자 입력용이므로 혼동하지 않도록 주의가 필요합니다.
실제 운영 환경에서는
.json을 별도로 저장하고, 변경 이력을 관리하는 것이 안정적입니다.
참고 링크
CloudWatch 에이전트를 사용하여 지표, 로그, 추적 수집
https://docs.aws.amazon.com/ko_kr/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html
CloudWatch 에이전트 문제 해결
https://docs.aws.amazon.com/ko_kr/AmazonCloudWatch/latest/monitoring/troubleshooting-CloudWatch-Agent.html
위 내용 외에도 기타 문의여부나 기술지원 등은 NDS 클라우드기술팀으로 요청 부탁드립니다.
SA 오승우