Docker logs 명령어 완벽 가이드: 컨테이너 문제를 빠르게 찾는 7가지 팁

docker logs payment-service를 입력하고 Enter를 누르자 화면에 INFO 레벨 로그가 수만 줄 쏟아집니다. 운영 환경의 결제 서비스가 막 중단됐는데, 문제 해결의 열쇠인 ERROR 메시지는 이 로그 흐름의 어디에 숨어 있을까요?

너무 많은 로그 출력, 실시간 모니터링, 시간대별 필터링, 오류 정보 빠르게 찾기 같은 문제는 중요한 순간에 생각보다 다루기 어렵습니다. 이 글에서는 기본부터 고급 활용법까지 실용적인 docker logs 팁 7가지를 소개해 컨테이너 문제를 빠르게 진단할 수 있도록 돕습니다.

기본 로그 확인

1. 가장 기본적인 로그 확인

먼저 가장 기본적인 사용법부터 살펴보겠습니다. 아마 이 명령어를 본 적이 있을 것입니다.

docker logs <컨테이너명>
# 또는 컨테이너 ID 사용
docker logs abc123def456

이 명령어는 컨테이너가 시작된 시점부터 현재까지의 모든 로그를 터미널에 출력합니다. 듣기에는 좋아 보이지만, 실제로 사용해 보면 로그가 폭포처럼 쏟아져 내용을 제대로 확인하기 어렵습니다.

제가 처음 이 문제를 겪었을 때 해당 컨테이너는 이미 사흘 동안 실행 중이었고 로그도 수만 줄에 달했습니다. 터미널이 빠르게 스크롤되는 동안 한참을 지켜봤지만 ERROR 하나도 찾지 못했습니다. 나중에야 이런 상황에서는 옵션 없는 기본 명령어를 사용하면 안 된다는 사실을 알았습니다.

그렇다면 이 기본 명령어는 언제 사용해야 할까요?

솔직히 다음 두 가지 경우뿐입니다.

• 컨테이너가 시작된 지 얼마 되지 않아 로그가 많지 않을 때
• 모든 로그를 파일로 내보내 백업해야 할 때

그 외의 경우에는 사용하지 않는 편이 좋습니다. 더 나은 방법이 있습니다.

2. 최근 N줄 로그 확인

일상적으로 가장 자주 사용하는 팁은 다음과 같습니다.

docker logs --tail 50 my-container

--tail 옵션을 사용하면 마지막 N줄의 로그만 표시할 수 있습니다. 저는 보통 50줄이나 100줄을 확인합니다. 문제를 파악하기에는 충분하면서도 너무 많은 정보에 파묻히지 않는 양입니다.

실전 상황:

지난주에 저희 API 서비스의 응답이 갑자기 느려졌습니다. 제가 가장 먼저 실행한 명령어는 다음과 같습니다.

docker logs --tail 100 api-server

최근 100줄의 로그에서 데이터베이스 연결 시간 초과 경고를 바로 발견했습니다. 문제 범위가 즉시 좁혀졌습니다. 코드 문제가 아니라 데이터베이스 쪽 문제였습니다.

이 팁의 핵심은 최근 로그를 먼저 확인해 문제의 대략적인 방향을 파악하는 것입니다. 최신 로그에서 단서를 찾지 못했다면 다른 방법으로 더 깊이 조사하면 됩니다.

KiloClaw - 기업용 매니지드 OpenClaw, AI Agent 오케스트레이션 및 스마트 라우팅

시작하기 →광고

문제를 바로 찾고 싶지만 몇 줄을 확인해야 할지 모르겠다면 50줄부터 시작하는 것을 권합니다. 부족하면 100줄, 그래도 부족하면 200줄로 늘려 보세요. 처음부터 전체 로그를 확인하는 것보다 단계적으로 범위를 늘리는 편이 훨씬 효율적입니다.

실시간 모니터링

3. 로그 스트림 실시간 확인

이 팁은 문제를 디버깅할 때 특히 유용합니다. Linux의 tail -f 명령어처럼 로그 업데이트를 실시간으로 모니터링합니다.

docker logs -f my-container

-f 옵션(follow의 약자)을 추가하면 로그가 계속 출력되고 새로 생성된 로그가 화면에 즉시 표시됩니다.

저는 주로 다음 상황에서 사용합니다.

1. 컨테이너 시작 모니터링
   새 서비스를 배포할 때 컨테이너를 시작한 직후 -f 옵션으로 로그를 추적합니다. 설정 파일에 오류가 있으면 에러를 즉시 확인할 수 있으므로 서비스가 중단된 뒤에야 조사할 필요가 없습니다.

2. 문제 재현 과정 기록
   특정 작업에서만 발생하는 버그가 있다면 먼저 docker logs -f를 실행한 다음 해당 작업을 재현합니다. 로그가 실시간으로 갱신되므로 오류 정보를 현장에서 바로 포착할 수 있습니다.

더 실용적인 조합도 있습니다.

docker logs -f --tail 100 my-container

이렇게 하면 최근 100줄의 이전 로그를 확인하는 동시에 새 로그를 계속 추적할 수 있습니다. 모니터링을 시작할 때 최근에 무슨 일이 있었는지 먼저 살펴보고 이후 상황을 실시간으로 관찰하는 방식입니다.

예전에 한 동료가 컨테이너 문제를 디버깅하면서 -f만 실행해 놓고 30분 동안 화면을 지켜본 적이 있습니다. 로그가 한 줄도 움직이지 않았는데, 알고 보니 컨테이너가 이미 중단되어 새 로그가 생성되지 않고 있었습니다. -f를 사용하기 전에 docker ps로 컨테이너가 실행 중인지 확인하는 것이 좋습니다.

정밀 필터링

4. 시간 범위로 필터링

제가 가장 좋아하는 기능 중 하나입니다. 모니터링 시스템에서 ‘어젯밤 3시에 서비스 오류가 발생했다’고 알려 줬지만 아침에야 알림을 확인해 그사이 로그가 수천 줄 더 쌓인 경험이 있나요? 해당 시점의 로그를 빠르게 찾으려면 어떻게 해야 할까요?

--since와 --until 옵션을 사용합니다.

# 특정 시점 이후의 로그 확인
docker logs --since "2025-12-18T03:00:00" my-container

# 특정 시간 범위의 로그 확인
docker logs --since "2025-12-18T03:00:00" --until "2025-12-18T04:00:00" my-container

시간 형식은 ISO 8601 표준을 사용합니다. 하지만 형식을 엄격하게 외울 필요는 없습니다. Docker는 상대 시간도 지원합니다.

# 최근 1시간 로그 확인
docker logs --since 1h my-container

# 최근 30분 로그 확인
docker logs --since 30m my-container

# 어제부터 현재까지의 로그 확인
docker logs --since 24h my-container

실전 사례:

한번은 새벽 4시에 주문 서비스가 중단됐습니다. 오전 9시에 조사하기 시작했을 때는 로그가 이미 5시간이나 쌓여 있었습니다. 저는 바로 다음 명령어를 실행했습니다.

docker logs --since "2025-12-18T03:30:00" --until "2025-12-18T04:30:00" order-service

문제 발생 전후 1시간의 로그만 확인해 메모리 부족 오류 스택을 즉시 찾았습니다. 전체 로그를 봤다면 찾는 데 한참 걸렸을 것입니다.

5. 타임스탬프 표시

로그에서 ERROR를 발견했지만 언제 발생했는지 알 수 없어 모니터링 시스템의 데이터와 대조하지 못하는 경우가 있습니다. 이때는 타임스탬프가 필요합니다.

docker logs -t my-container

-t 옵션은 다음과 같이 각 로그 줄 앞에 타임스탬프를 추가합니다.

2025-12-18T10:23:45.123456789Z [INFO] Server started
2025-12-18T10:23:47.234567890Z [ERROR] Database connection failed

이렇게 하면 각 로그가 생성된 정확한 시점을 알 수 있습니다. 저는 보통 다른 옵션과 조합해 사용합니다.

# 최근 30분의 로그를 타임스탬프와 함께 표시
docker logs -t --since 30m my-container

# 로그를 실시간으로 모니터링하면서 타임스탬프 표시
docker logs -f -t my-container

특히 성능 문제를 분석할 때 타임스탬프가 매우 유용합니다. 요청이 들어온 시점부터 처리가 끝날 때까지 얼마나 걸렸고 어느 단계가 느렸는지 정확하게 파악할 수 있습니다.

6. grep으로 키워드 필터링

로그가 전부 INFO인데 ERROR만 보고 싶다면 grep으로 필터링합니다.

docker logs my-container | grep "ERROR"

이렇게 하면 “ERROR”가 포함된 줄만 표시됩니다. 하지만 반드시 알아야 할 함정이 하나 있습니다.

grep 필터링이 작동하지 않을 때가 있습니다!

저도 처음 이 문제를 겪었을 때 당황했습니다. 컨테이너 로그에 ERROR가 분명히 있는데 grep이 찾지 못했습니다. 나중에 알고 보니 Docker 컨테이너가 로그를 stdout(표준 출력)이 아니라 stderr(표준 오류 스트림)로 출력할 수 있고, 파이프 |는 기본적으로 stdout만 처리하기 때문이었습니다.

Vultr - 고성능 NVMe 클라우드 서버, 전 세계 32개 노드, Docker 원클릭 배포

요금 보기 →광고

해결 방법은 stderr를 stdout으로 리디렉션하는 것입니다.

docker logs my-container 2>&1 | grep "ERROR"

2>&1은 stderr(파일 디스크립터 2)를 stdout(파일 디스크립터 1)으로 리디렉션한다는 뜻입니다. 이렇게 하면 grep이 모든 로그를 포착할 수 있습니다.

더 실용적인 조합:

# ERROR 앞뒤의 문맥 10줄 확인
docker logs my-container 2>&1 | grep -C 10 "ERROR"

# 대소문자를 구분하지 않고 error 검색
docker logs my-container 2>&1 | grep -i "error"

# 최근 오류 20개 찾기
docker logs -t my-container 2>&1 | grep -i "error" | tail -20

-C 10 옵션은 특히 유용합니다. 일치한 줄의 앞뒤로 각각 10줄을 표시합니다. ERROR가 있는 한 줄만으로 충분하지 않을 때가 있습니다. 오류가 발생하기 전후의 문맥을 알아야 문제의 전체 흐름을 이해할 수 있습니다.

고급 활용법

7. 로그 파일의 실제 위치 확인

컨테이너 로그가 실제로 호스트의 파일에 저장된다는 사실을 모를 수도 있습니다. 로그 파일이 어디에 있는지 확인하려면 다음 명령어를 사용합니다.

docker inspect --format='{{.LogPath}}' my-container

일반적으로 다음과 같은 결과가 출력됩니다.

/var/lib/docker/containers/abc123.../abc123...-json.log

이 기능은 어디에 유용할까요?

1. 로그 파일 직접 확인
   특히 로그가 매우 클 때 docker logs 명령어가 Docker daemon에 부하를 줄 수 있습니다. 이 경우 파일을 직접 읽는 편이 더 빠를 수 있습니다.

   sudo tail -f /var/lib/docker/containers/abc123.../abc123...-json.log

2. 로그 백업
   로그를 보관해야 한다면 이 파일을 바로 복사하면 됩니다.

   sudo cp /var/lib/docker/containers/abc123.../abc123...-json.log ./backup/

3. 더 강력한 도구로 분석
   예를 들어 vim으로 로그 파일을 열면 다양한 편집기의 검색 기능을 활용할 수 있어 grep보다 유연합니다.

다만 이 로그 파일은 JSON 형식이고 각 로그 줄이 JSON 객체로 감싸져 있어 다소 복잡해 보일 수 있습니다. 단순한 텍스트 로그만 보고 싶다면 docker logs 명령어가 더 편리합니다.

로그를 파일로 내보내기:

일반 텍스트 형식으로 로그를 백업하려면 리디렉션을 사용합니다.

docker logs my-container > container.log

이렇게 내보낸 파일은 일반 텍스트이므로 나중에 분석하거나 다른 사람에게 전달하기 편합니다.

운영 환경 모범 사례

8. 로그 로테이션 설정(디스크 가득 참 방지)

솔직히 말하면 운영 환경에서 가장 쉽게 간과되지만 동시에 가장 중요한 설정입니다.

실제 장애 사례:

한번은 심각한 사례를 본 적이 있습니다. 한 컨테이너가 몇 달 동안 실행되면서 로그 파일이 계속 커졌고 결국 호스트의 디스크를 가득 채웠습니다. 서버의 모든 컨테이너가 중단되고 데이터베이스는 데이터를 쓸 수 없었으며 웹사이트도 마비됐습니다. 두 시간 동안 조사한 끝에야 로그 파일이 모든 공간을 차지했다는 사실을 발견했습니다.

이런 장애를 어떻게 예방할 수 있을까요?

로그 로테이션(log rotation)을 설정합니다. /etc/docker/daemon.json 파일에 다음 내용을 추가합니다.

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

옵션의 의미:

• max-size: 로그 파일 하나의 최대 크기는 10MB
• max-file: 로그 파일을 최대 3개까지 보관

이렇게 설정하면 컨테이너 하나가 로그에 사용하는 공간은 최대 10MB × 3 = 30MB입니다. 로그 파일이 10MB에 도달하면 Docker가 자동으로 새 파일을 만들고, 파일이 3개를 넘으면 가장 오래된 파일을 삭제합니다.

설정 적용 방법:

Railway - 현대적인 배포 플랫폼, 번거로운 운영 없이 몇 분 만에 라이브

지금 시작 →광고

daemon.json을 수정한 뒤 Docker 서비스를 다시 시작합니다.

sudo systemctl restart docker

주의: Docker를 다시 시작하면 모든 컨테이너가 재시작됩니다. 운영 환경에서는 적절한 작업 시간대를 선택해야 합니다.

개별 컨테이너 설정:

특정 컨테이너에만 로그 로테이션을 설정하려면 컨테이너를 시작할 때 다음 옵션을 지정할 수 있습니다.

docker run -d \
  --log-opt max-size=10m \
  --log-opt max-file=3 \
  my-image

이렇게 하면 다른 컨테이너에는 영향을 주지 않습니다.

9. 운영 환경 로그 관리 전략

docker logs를 한동안 사용하다 보면 로그 양이 많을 때 명령어가 매우 느려지거나 터미널이 멈춘 듯 보이는 문제가 생깁니다. docker logs가 Docker daemon에 상당한 부하를 주기 때문입니다.

운영 환경에서의 선택:

• 소규모 프로젝트(컨테이너 1~10개):

  • docker logs + 로그 로테이션 설정이면 충분합니다.
  • 간단하고 직접적이며 추가 인프라가 필요하지 않습니다.

• 중대형 프로젝트(컨테이너 10개 이상 또는 마이크로서비스 아키텍처):

  • 중앙 집중식 로그 시스템이 반드시 필요합니다.
  • 일반적인 선택: ELK (Elasticsearch + Logstash + Kibana)
  • 다른 선택지: Loki, Fluentd, Splunk

대규모 프로젝트에서 docker logs만으로 부족한 이유는 무엇일까요?

1. 성능 문제: 여러 컨테이너의 로그를 동시에 조회하면 Docker daemon의 부하가 크게 증가합니다.
2. 집계 필요성: 마이크로서비스 아키텍처에서는 하나의 요청이 10개 서비스를 거칠 수 있고 로그도 10개 컨테이너에 흩어집니다. 이를 어떻게 연결해 분석할 수 있을까요?
3. 과거 기록 조회: docker logs는 현재 컨테이너의 로그만 볼 수 있으며 컨테이너가 재시작되면 이전 로그가 사라집니다.
4. 팀 협업: 운영, 개발, 테스트 담당자가 모두 서버에 접속해 명령어를 입력하게 하는 방식은 현실적이지 않습니다.

제안:

• Docker를 막 배우기 시작했다면 docker logs 명령어를 익히는 데 집중하는 것으로 충분합니다.
• 개인 프로젝트나 소규모 팀이라면 로그 로테이션을 잘 설정해 두고 docker logs를 사용해도 괜찮습니다.
• 운영 환경에서 컨테이너가 10개를 넘는다면 중앙 집중식 로그 솔루션을 진지하게 검토하세요.
• 마이크로서비스 아키텍처라면 중앙 집중식 로그는 있으면 좋은 기능이 아니라 필수 요소입니다.

결론

지금까지 살펴본 내용을 바탕으로 글 도입부의 새벽 3시 상황으로 돌아가 보겠습니다. 지금 같은 상황을 다시 겪는다면 저는 다음과 같이 처리할 것입니다.

1. 먼저 docker logs --tail 100 payment-service로 최근 로그를 빠르게 확인합니다.
2. 단서를 찾지 못했다면 시간 범위로 필터링합니다. docker logs --since "2025-12-18T03:00:00" --until "2025-12-18T03:30:00" payment-service
3. 타임스탬프와 grep을 조합합니다. docker logs -t payment-service 2>&1 | grep -i "error" | tail -20

세 단계면 길어도 2분 안에 문제의 위치를 찾을 수 있습니다.

이것이 docker logs를 능숙하게 사용할 때 얻는 가치입니다. 모든 옵션을 외우는 것이 아니라 어떤 상황에서 어떤 조합을 사용해야 하는지 아는 것입니다.

마지막으로 다시 강조하겠습니다. 컨테이너가 운영 환경에서 실행 중이라면 지금 바로 로그 로테이션을 설정하세요. 디스크가 가득 찬 뒤 후회하지 마세요. 설정 파일은 몇 줄에 불과하지만 큰 장애를 막아 줄 수 있습니다.

빠른 참조 카드

# 기본 확인
docker logs <컨테이너명>                    # 모든 로그 확인
docker logs --tail 50 <컨테이너명>         # 최근 50줄 확인

# 실시간 모니터링
docker logs -f <컨테이너명>                # 실시간 추적
docker logs -f --tail 100 <컨테이너명>     # 최근 100줄을 표시하고 실시간 추적

# 시간 필터링
docker logs --since 1h <컨테이너명>        # 최근 1시간
docker logs --since "2025-12-18T03:00:00" <컨테이너명>  # 지정한 시간 이후

# 정밀 검색
docker logs -t <컨테이너명>                           # 타임스탬프 표시
docker logs <컨테이너명> 2>&1 | grep -i "error"      # 오류 검색
docker logs <컨테이너명> 2>&1 | grep -C 10 "error"   # 검색 결과와 문맥 표시

# 고급 활용법
docker inspect --format='{{.LogPath}}' <컨테이너명>   # 로그 파일 위치 확인
docker logs <컨테이너명> > log.txt                   # 로그 내보내기

이 참조 카드를 저장해 두었다가 다음에 컨테이너 문제가 생기면 바로 활용해 보세요.