Docker 컨테이너의 CPU와 메모리 사용량을 한눈에 확인하려면 cAdvisor, Prometheus, Grafana를 함께 구성하면 됩니다. 이 글은 Linux 서버에 Docker와 Docker Compose가 설치되어 있고, 터미널 명령을 실행할 수 있다고 가정합니다. 구성에 사용할 8080, 9090, 3000 포트가 다른 서비스에서 사용 중이면 충돌이 발생할 수 있으므로 테스트 환경에서 먼저 확인하세요.
목차
모니터링 구조와 준비물
cAdvisor는 컨테이너의 CPU, 메모리, 네트워크, 파일 시스템 사용량을 수집합니다. Prometheus는 이 메트릭(측정 가능한 운영 수치)을 일정 간격으로 가져와 저장하고, Grafana는 저장된 데이터를 그래프로 보여줍니다.
작업 폴더에 docker-compose.yml, prometheus.yml, rules.yml 파일을 준비합니다. 아래 구성은 세 서비스를 같은 Docker 네트워크에서 실행하므로 Prometheus가 cadvisor:8080이라는 서비스 이름으로 cAdvisor에 접근합니다.
아래 예시는 특정 버전으로 검증한 구성입니다. 실제 운영 환경에서는 각 프로젝트의 최신 안정 버전과 호환성을 확인한 뒤 적용하세요.
cAdvisor와 Prometheus 구성
먼저 Compose 파일을 작성합니다. cAdvisor가 호스트와 컨테이너 정보를 읽도록 일부 시스템 디렉터리를 읽기 전용으로 연결합니다.
services:
cadvisor:
image: gcr.io/cadvisor/cadvisor:v0.49.1
ports:
- "8080:8080"
volumes:
- /:/rootfs:ro
- /var/run:/var/run:ro
- /sys:/sys:ro
- /var/lib/docker/:/var/lib/docker:ro
prometheus:
image: prom/prometheus:v2.53.0
ports:
- "9090:9090"
volumes:
- ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
- ./rules.yml:/etc/prometheus/rules.yml:ro
volumes:
grafana_data:
prometheus.yml에서는 cAdvisor를 스크랩(메트릭을 주기적으로 수집하는 작업) 대상으로 지정합니다.
global:
scrape_interval: 15s
rule_files:
- /etc/prometheus/rules.yml
scrape_configs:
- job_name: cadvisor
static_configs:
- targets: ["cadvisor:8080"]
docker compose up -d
Prometheus 화면의 Status와 Targets에서 cAdvisor 상태가 UP인지 확인합니다. DOWN이면 컨테이너 이름, 포트, Compose 네트워크 연결을 먼저 점검하세요.
Grafana 대시보드와 알림 설정
Grafana를 추가하려면 Compose 파일에 다음 서비스를 넣고 다시 실행합니다.
grafana:
image: grafana/grafana:11.1.0
ports:
- "3000:3000"
volumes:
- grafana_data:/var/lib/grafana
depends_on:
- prometheus
브라우저에서 서버주소:3000으로 접속한 뒤 Grafana의 Connections → Data sources → Add data source → Prometheus 메뉴로 이동합니다. URL에는 http://prometheus:9090을 입력하고 저장합니다. 그런 다음 대시보드에서 새 대시보드를 만들고 패널을 추가한 뒤 쿼리 입력란에 container_memory_working_set_bytes나 rate(container_cpu_usage_seconds_total[5m])를 입력하면 컨테이너별 메모리와 CPU 변화를 표시할 수 있습니다.
알림 규칙은 rules.yml에 작성하며 Prometheus가 이 규칙을 평가합니다. 예를 들어 이 규칙은 각 컨테이너의 메모리 사용량이 약 1GB를 초과한 상태가 5분 이상 지속되는 경우 알림 대상으로 만듭니다.
groups:
- name: container-alerts
rules:
- alert: ContainerMemoryHigh
expr: container_memory_working_set_bytes > 1e9
for: 5m
labels:
severity: warning
annotations:
summary: "컨테이너 메모리 사용량 확인"
Prometheus 설정이나 rule 파일을 변경한 뒤에는 docker compose restart prometheus로 Prometheus를 재시작해 변경 사항을 적용합니다. rules.yml에 정의한 규칙만으로는 알림이 실제로 발송되지 않습니다 — Alertmanager 연결까지 마쳐야 합니다.
알림을 실제로 받기 (Alertmanager 설정)
앞서 만든 알림 규칙은 Prometheus 안에서 경보 상태로만 표시될 뿐, 실제로 누군가에게 전달되지는 않습니다. 알림을 Slack이나 이메일로 받으려면 Alertmanager를 추가로 구성해야 합니다.
Compose 파일에 Alertmanager 서비스를 추가합니다.
alertmanager:
image: prom/alertmanager:v0.27.0
ports:
- "9093:9093"
volumes:
- ./alertmanager.yml:/etc/alertmanager/alertmanager.yml:ro
Prometheus가 Alertmanager로 경보를 전달하도록 prometheus.yml에 연결 정보를 추가합니다.
alerting:
alertmanagers:
- static_configs:
- targets: ["alertmanager:9093"]
alertmanager.yml에서 수신자와 전달 경로를 정의합니다. 아래는 Slack Webhook으로 알림을 보내는 예시입니다.
route:
receiver: slack-default
group_wait: 30s
group_interval: 5m
repeat_interval: 4h
receivers:
- name: slack-default
slack_configs:
- api_url: "https://hooks.slack.com/services/xxx/xxx/xxx"
channel: "#alerts"
send_resolved: true
api_url은 Slack 워크스페이스에서 발급받은 Incoming Webhook 주소로 바꿔야 합니다. 이메일로 받고 싶다면 slack_configs 대신 email_configs에 SMTP 서버 정보를 넣으면 됩니다.
설정 파일을 저장한 뒤 Alertmanager와 Prometheus를 재시작해 반영합니다.
docker compose up -d alertmanager
docker compose restart prometheus
Alertmanager 화면(서버주소:9093)의 Status에서 설정이 정상적으로 로드됐는지 확인하고, Alerts 탭에서 실제로 들어오는 경보를 볼 수 있습니다. Grafana Alerting을 대신 쓰고 싶다면 Alertmanager 없이 Grafana의 Alerting → Contact points에서 Slack이나 이메일 채널을 등록하고 대시보드 패널에서 알림 규칙을 직접 만들면 됩니다 — 이 경우 rules.yml의 Prometheus 규칙과는 별개로 관리됩니다.
문제 확인 방법
cAdvisor가 실행 중인데 메트릭이 비어 있다면 호스트 볼륨 권한이나 Docker 데이터 경로가 환경과 맞지 않을 수 있습니다. docker compose logs cadvisor에서 권한 오류를 확인하고, docker inspect로 마운트 경로를 점검한 뒤 컨테이너를 재생성하세요.
결론
cAdvisor로 수집하고 Prometheus로 저장한 뒤 Grafana에서 시각화하면 Docker 컨테이너 상태를 지속적으로 확인할 수 있습니다. CPU·메모리 기준의 알림까지 추가하면 장애를 확인하는 시간이 짧아집니다.