Docker 로그 확인과 용량 관리: compose logs부터 로그 로테이션까지

서비스에 오류가 생겼을 때 로그를 열면 너무 많은 내용이 쏟아지고, 정작 필요한 시간의 기록은 찾기 어려울 수 있습니다. 반대로 로그가 계속 쌓여 서버 디스크를 차지하는 문제도 있습니다. 로그를 읽는 방법과 얼마나 보관할지는 함께 정해야 합니다.

이번 글에서는 Docker Compose에서 서비스와 시간 범위를 좁혀 로그를 확인하는 방법, 로그 드라이버의 역할, json-file 로테이션 예시를 살펴봅니다. 헬스체크와 시작 순서 글에서 확인한 오류를 더 자세히 추적할 때 이어서 사용할 수 있는 내용입니다.

1. Docker logs는 어떤 로그를 보여줄까?

일반적으로 Docker가 수집하는 로그는 컨테이너 프로세스의 표준 출력(stdout)과 표준 오류(stderr)에서 나옵니다. json-file 드라이버는 여기에 시간과 출력 구분을 붙여 저장합니다. JSON File 로깅 문서가 이 저장 방식을 설명합니다.

프로그램이 /app/logs/service.log 같은 자체 파일에만 내용을 쓰고 있다면, 그 파일 내용이 자동으로 compose logs에 나타나는 것은 아닙니다. 로그가 없을 때는 서비스가 조용한지, 출력 위치가 다른지, 다른 로그 드라이버를 쓰는지 먼저 나누어 봅니다.

직접 제작한 로그 흐름도. Docker가 수집하는 표준 출력과 프로그램이 자체 파일에 저장하는 로그를 분리해 표시했습니다.

2. 서비스와 시간 범위를 먼저 줄입니다

다음은 서비스 이름이 web과 db인 프로젝트를 가정한 조회 예시입니다. 자신의 Compose 파일에서 서비스 이름이 다르면 바꿔서 사용합니다. 실제 운영 서버에서 가져온 로그는 포함하지 않았습니다.

# web 컨테이너마다 마지막 100줄
docker compose logs --tail=100 web

# 최근 10분, 시간 표시, 두 서비스 비교
docker compose logs --since=10m --timestamps web db

# 최근 50줄부터 새 로그를 계속 관찰
docker compose logs --tail=50 --follow web

--tail은 컨테이너별 마지막 줄 수를 제한하고, --since는 조회 시작 시점을 좁힙니다. --timestamps는 시간을 표시하고 --follow는 새 출력을 따라갑니다. 조회를 끝내려면 터미널에서 Ctrl+C로 로그 추적을 종료합니다. 옵션은 Compose logs 공식 참조에서 확인할 수 있습니다.

예를 들어 오후 3시 10분에 오류가 발생했다면, 그 시간 주변의 web과 db 기록을 함께 살펴봅니다. “DB 연결 실패”가 반복된 횟수만 세기보다, 직전에 DB가 초기화되었는지 또는 웹 설정이 바뀌었는지 확인하는 것입니다. 여러 기록을 맞출 때는 시간대도 함께 적습니다.

증상	먼저 볼 기록	다음 질문
시작 직후 오류	web·db의 시작 시간	준비 전에 연결했는가?
특정 요청만 실패	요청 시간·경로·오류	재현 조건이 같은가?
아무 기록도 없음	출력 위치·로그 드라이버	자체 파일에만 쓰는가?

3. 조회 줄 수를 줄여도 저장량은 줄지 않습니다

--tail=100은 화면에 보여 주는 범위를 정할 뿐, 디스크에 100줄만 남기라는 보관 정책이 아닙니다. 이 차이를 놓치면 조회 화면은 짧아졌지만 저장 공간은 계속 늘어날 수 있습니다.

Docker의 기본 json-file 드라이버는 별도 설정이 없으면 로그를 자동으로 교체하지 않습니다. 공식 문서는 일반적인 상황에서 자동 로테이션과 효율적인 형식을 제공하는 local 드라이버도 권장합니다. 다만 기존 수집 도구와의 호환성을 확인해 선택해야 합니다. 로그 드라이버 설정 안내를 참고하세요.

현재 드라이버와 옵션은 다음처럼 해당 서비스 컨테이너의 설정만 조회할 수 있습니다. 첫 명령에서 얻은 web 컨테이너 ID를 두 번째 명령의 CONTAINER_ID 자리에 넣습니다. 여러 복제본이 있다면 각각 확인합니다.

docker compose ps -q web
docker inspect --format '{{json .HostConfig.LogConfig}}' CONTAINER_ID

설정 파일의 기본값과 이미 실행 중인 컨테이너의 값이 같다고 가정하지 않는 것이 좋습니다. 오래전에 만들어진 컨테이너가 이전 로그 정책을 계속 쓰고 있을 수 있기 때문입니다.

4. json-file 로테이션 구성 예시

아래는 web 서비스 하나에 로그 파일 크기와 개수를 지정하는 설명용 구성입니다. 이미 json-file을 사용하는 환경에서 두 옵션의 관계를 보여 주기 위한 예이며, 모든 서비스에 같은 수치를 권장하는 것은 아닙니다.

services:
  web:
    image: nginx:stable-alpine
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

max-size는 파일을 교체할 크기 기준이고, max-file은 유지할 파일 개수입니다. max-file은 max-size와 함께 설정해야 의미가 있습니다. 이 예시는 컨테이너마다 약 10m 크기의 파일을 최대 3개 관리하는 정책이며, 오래된 파일은 교체 과정에서 제거됩니다. 정확한 옵션 의미는 앞서 연결한 JSON File 문서를 참고하세요.

이것은 “3일 보관” 같은 시간 정책이 아닙니다. 로그가 급증하면 같은 크기 안에 남는 시간 범위가 짧아집니다. 가령 평소에는 수시간 전 오류를 찾을 수 있어도 장애가 반복되는 동안에는 최근 기록만 남을 수 있습니다. 필요한 조사 기간이 있다면 실제 발생량을 측정하고 별도 수집·보관 범위를 정해야 합니다.

또한 이 제한은 해당 컨테이너의 Docker 로그에 대한 설정입니다. 업로드 파일, DB 데이터, 프로그램 자체 로그, 다른 컨테이너의 로그까지 합친 서버 전체 사용량의 상한은 아닙니다. 저장 공간을 판단할 때는 어떤 경로가 증가하는지 구분합니다.

5. 적용과 보관은 마지막까지 확인합니다

로그 드라이버 설정 변경은 기존 컨테이너에 자동으로 소급 적용되지 않습니다. 원하는 옵션으로 컨테이너를 재생성한 뒤 실제 LogConfig를 다시 확인해야 합니다. 운영 중이라면 필요한 장애 기록을 먼저 보관하고 재생성의 서비스 영향을 검토합니다.

Docker가 관리하는 json-file 로그 파일을 외부 도구로 직접 지우거나 비우는 방식은 로깅 동작을 방해할 수 있으므로 피합니다. 프로그램이 직접 만든 파일 로그는 별도의 보관·교체 정책을 확인해야 합니다. 또한 볼륨에 데이터를 보관하는 것과 로그를 필요한 기간 남기는 것은 각각 검증해야 할 작업입니다.

공유할 기록에는 발생 시간, 서비스 이름, 재현 조건, 관련 오류 몇 줄을 남기는 편이 좋습니다. 비밀번호·토큰·사용자 입력 원문은 그대로 붙이지 않습니다. 로그 조회 범위와 보관 정책을 함께 정하면, 화면에 쏟아지는 출력과 디스크에 쌓이는 데이터를 각각 관리할 수 있습니다.

자료 확인일: 2026년 9월 8일. 공식 문서에 근거한 조회·설정 예시입니다. 실제 서비스 로그를 사용하지 않았으며 로테이션 실행 시험이나 디스크 절감량 측정은 수행하지 않았습니다.