Docker 컨테이너 모니터링: 리소스, 상태 확인, 로그

docker stats의 수치를 올바르게 읽고 상태 확인과 재시작을 구분합니다. 로그 드라이버와 순환 설정, cAdvisor·Prometheus·Guance를 이용한 지속 수집 조건도 살펴봅니다.

모범 사례
항구에 배치된 컨테이너 모듈을 표현한 일러스트

컨테이너가 실행 중이어도 애플리케이션이 요청에 응답하지 못할 수 있습니다. CPU 수치가 높아 보이는 이유는 작업에 따라 다르고, 네트워크 누적값이 커졌다고 현재 전송 속도를 알 수 있는 것도 아닙니다. 리소스 통계, 애플리케이션 상태, 로그는 각각 다른 질문에 답합니다.

현재 상태는 docker stats와 docker inspect로 확인하고, 특정 응답 조건은 HEALTHCHECK로 검사합니다. 이력 조회와 알림이 필요하다면 지속 수집과 저장을 구성해야 합니다. 메트릭은 cAdvisor와 Prometheus로 수집할 수 있으며, 로그에는 별도의 수집 경로와 보존 설정이 필요합니다.

docker stats로 현재 리소스 확인하기

다음 예시는 Linux Docker Engine을 대상으로 하며, 해당 daemon에 접근할 권한이 필요합니다.

docker stats                    # 기본값은 실행 중인 컨테이너의 통계 스트림
docker stats web db             # 특정 컨테이너 지정
docker stats --no-stream        # 한 번만 조회

CPU 비율, 메모리 사용량과 한도, 네트워크 I/O, 블록 I/O, PIDS를 보여 줍니다. 값을 비교하기 전에 단위와 범위를 확인해야 합니다.

  • Linux CPU 비율은 100%를 넘을 수 있습니다. 약 100%는 논리 CPU 하나를 모두 사용하는 수준입니다. 여러 CPU에서 병렬로 작업하면 이보다 커질 수 있습니다. 컨테이너에 할당한 CPU 쿼터 대비 사용률은 아닙니다.
  • Linux CLI 메모리 값은 파일 캐시 일부를 제외합니다. 따라서 API가 반환하는 전체 사용량과 같지 않습니다. 현재 문서는 cgroup v1의 total_inactive_file, v2의 inactive_file을 기준으로 설명합니다. Docker 19.03 이하에서는 다른 캐시 필드를 사용했습니다.
  • NET I/O와 BLOCK I/O는 누적 바이트 수입니다. 초당 전송량이 아닙니다. 속도를 구하려면 같은 카운터의 두 표본 사이 차이를 경과 시간으로 나누고 카운터 초기화도 처리해야 합니다. PIDS에는 커널 스레드도 포함됩니다.

기본 목록에는 실행 중인 컨테이너만 나옵니다. --all로 중지된 컨테이너도 표시할 수 있지만, 중지된 컨테이너에서는 실시간 리소스 데이터를 얻을 수 없습니다. docker stats 공식 설명

애플리케이션 응답 확인하기

HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD curl -f http://localhost:8080/healthz || exit 1

검사는 컨테이너 안에서 실행됩니다. 이 예시에는 이미지 내 shell과 curl, 컨테이너 내부 8080 포트의 /healthz 엔드포인트가 필요합니다. 주소는 애플리케이션에 맞게 바꿉니다. docker ps에는 일반 실행 상태와 별도로 starting, healthy, unhealthy가 표시됩니다. 이 엔드포인트 검사에 통과했다고 성능이나 업무 처리의 정확성까지 확인된 것은 아닙니다. HEALTHCHECK 명세

Compose에서 depends_on의 condition: service_healthy를 사용하면 의존 서비스가 정상 상태가 될 때까지 시작을 기다릴 수 있습니다. 의존 순서만 선언하면 준비 완료까지 기다리지 않으며, 시작 이후 의존 서비스가 unhealthy가 됐다는 이유만으로 자동 재시작하지도 않습니다. 상태 검사 결과와 주 프로세스 종료는 서로 다른 조건입니다. Compose 시작 순서

Kubernetes는 이미지의 Docker HEALTHCHECK 대신 Pod 명세의 프로브를 사용합니다. liveness 또는 startup 프로브가 실패 임계값에 도달하면 kubelet은 해당 컨테이너를 종료하고 재시작 정책에 따라 처리합니다. readiness 실패는 Pod가 준비된 서비스 엔드포인트로 취급되지 않게 하며, 그 자체로 컨테이너를 재시작하지 않습니다. 세 프로브를 모두 Pod 자동 교체 기능으로 이해하면 안 됩니다. Kubernetes 프로브 동작

로그 드라이버를 확인하고 로그 읽기

docker logs --tail 100 -f web
docker logs --since 10m web

이 명령은 컨테이너의 표준 출력과 표준 오류에서 아직 읽을 수 있는 로그를 가져옵니다. 애플리케이션이 컨테이너 내부의 임의 파일에 쓴 로그를 자동으로 읽지는 않습니다. 로컬 조회 가능 여부는 드라이버에도 달려 있습니다. json-file, local, journald는 읽기를 지원합니다. 읽기를 지원하지 않는 원격 드라이버는 보통 Docker의 dual logging 로컬 캐시를 이용합니다. 이 캐시를 끄면 docker logs가 읽기 미지원 오류를 반환할 수 있습니다. 순환 처리로 이미 삭제된 기록도 --since로 복구할 수는 없습니다. docker logs · dual logging

Docker의 기본 드라이버는 json-file이며 기본 설정에서는 로그를 순환하지 않습니다. 계속 사용한다면 디스크가 차지 않도록 max-size와 max-file을 설정합니다. 다음은 기존 daemon 로그 설정에 병합할 수 있는 예시입니다.

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

옵션 값은 문자열이어야 합니다. daemon 기본값 변경은 Docker Engine을 재시작한 뒤 새로 생성하는 컨테이너부터 적용됩니다. 기존 컨테이너는 자동으로 변경되지 않습니다. Docker는 적합한 환경에서 기본적으로 로그를 순환하는 local 드라이버도 권장합니다. 다만 저장 형식이 다르므로 JSON 파일용 수집 설정을 그대로 적용할 수는 없습니다. 로그 드라이버 설정 · json-file 순환 옵션

여러 컨테이너의 로그를 Guance에서 검색하려면, 지원되는 Docker 환경에서 DataKit의 컨테이너 수집기(영어 문서)를 사용할 수 있습니다. 컨테이너 메트릭, 객체, 표준 출력 로그를 수집합니다. 독립 Docker 환경에서는 공식 문서에 따라 호스트에 DataKit을 설치하고, 접근 가능한 런타임 endpoint를 설정합니다. 일반적인 주소는 unix:///var/run/docker.sock이며 로그 경로와 읽기 권한도 확인해야 합니다. 모든 드라이버가 읽을 수 있는 JSON 파일을 만든다고 가정하면 안 됩니다. Docker가 관리하는 파일을 임의로 수정하거나 순환 처리하지 마세요.

애플리케이션이 별도 파일에 쓰는 로그는 접근 가능한 볼륨 경로와 DataKit 로그 수집 설정(영어 문서)으로 연결합니다. 실제로 수집한 컨테이너 ID, 서비스, 환경 등의 식별자를 보존하고, 같은 서비스와 시간 범위로 재시작 전후 오류를 검색합니다. 컨테이너가 교체되면 ID가 달라집니다. 이전 기록을 검색할 수 있는지는 당시 수집 여부와 보존 정책에 달려 있습니다. 이미 삭제됐고 수집하지도 않았던 로그를 플랫폼 설정만으로 되살릴 수는 없습니다.

자주 묻는 질문

docker stats로 과거 데이터를 볼 수 있나요?

명령 자체는 장기간 조회할 수 있는 이력을 만들지 않습니다. 추세를 보려면 시계열 모니터링 백엔드로 계속 수집하고, docker stats는 현재 상태를 확인할 때 사용합니다.

이미 Prometheus를 운영한다면 cAdvisor가 컨테이너 리소스 통계를 수집하고 /metrics로 노출하도록 구성할 수 있습니다. 환경에 맞는 호스트 마운트, 런타임 접근, 권한이 필요합니다. container_cpu_usage_seconds_total은 누적 CPU 시간이므로 CPU 사용 속도를 구할 때는 rate로 초당 CPU 시간을 계산합니다. container_memory_working_set_bytes는 현재 working set을 나타내며, 애플리케이션 힙 사용량이나 Docker CLI 메모리 열과 항상 같은 값은 아닙니다.

id, 사용 가능한 name과 image, 실제로 노출된 컨테이너 레이블로 대상을 구분합니다. 불필요한 레이블을 제한해 컨테이너가 재생성됐을 때 서로 다른 대상을 섞거나 시계열 수가 계속 증가하지 않게 합니다. cAdvisor는 수집과 메트릭 엔드포인트를 제공하고, 장기 보존·쿼리·알림은 Prometheus 같은 백엔드에서 설정합니다. 애플리케이션 로그를 대신 집계해 주는 것은 아닙니다. cAdvisor 메트릭 · 실행 및 레이블 옵션

상태 확인에 실패하면 컨테이너가 자동으로 재시작하나요?

독립 Docker 컨테이너는 unhealthy로 표시될 뿐입니다. --restart는 주 프로세스 종료 등의 재시작 조건을 처리하며 unhealthy 상태만으로 재시작하지 않습니다. Swarm은 서비스 작업의 상태 확인이 실패하면 대체 작업을 만들 수 있지만 서비스 설정과 스케줄링 조건을 따릅니다. Kubernetes는 자체 liveness/startup 프로브와 컨테이너 재시작 정책을 적용하고, readiness 실패는 재시작을 유발하지 않습니다. 실제 배포 방식에 맞춰 알림과 통제된 복구 절차를 구성해야 합니다. Docker 재시작 정책 · Swarm 작업 수명주기

컨테이너 안과 호스트의 CPU 값이 다른 이유는 뭔가요?

대상 범위와 분모가 다를 수 있습니다. 호스트 전체 CPU, 컨테이너 쿼터, CPU affinity, 논리 CPU 수는 서로 다른 기준입니다. cgroup 설정은 컨테이너에서 보이는 자원에 영향을 줍니다. 오래된 JDK나 런타임은 쿼터를 잘못 인식해 스레드 풀 크기를 잘못 설정할 수도 있습니다. cgroup v1/v2와 쿼터를 제대로 인식하는지는 실제 런타임, 버전, 설정을 확인해야 합니다. 컨테이너에서 실행한다는 사실만으로 판단할 수는 없습니다. Docker 리소스 제한 · JDK 컨테이너 지원 옵션

공식 참고 자료

이 글은 공식 문서를 바탕으로 작성했습니다. 예시를 실제로 실행해 검증하지는 않았습니다. 프로덕션 적용 전에는 사용 버전, 권한, 실제 부하에 맞춰 확인하세요.

함께 읽기

맞춤형 플랜 상담

문의하기

커뮤니티 가입

WeChat으로 스캔하여
커뮤니티에 가입하세요

Guance 사용해 보기

온라인에서 바로 시작하고 사용한 만큼만 결제하세요.

시작하기

Guance 요금제 선택

코드 저장소