Docker 컨테이너가 실행되지 않을 때 로그 읽는 법

Docker 컨테이너가 실행되지 않으면 패닉하기 쉽지만, 대부분의 경우 로그에 명확한 원인이 적혀 있다. 시간을 낭비하지 않으려면 로그를 정확하게 읽는 법부터 배워야 한다.

컨테이너 로그 보는 기본

docker logs service-name

기본적으로 전체 로그를 출력한다. 로그가 길면 처음부터 천천히 본다.

마지막 100줄만 보려면:

docker logs --tail=100 service-name

실시간으로 로그를 보려면:

docker logs -f service-name

로그에서 에러 찾기

에러 메시지를 필터링하면 훨씬 빠르다:

docker logs service-name | grep -i error
docker logs service-name | grep -i exception
docker logs service-name | grep -i fatal

또는 전체 로그에서 중요한 부분만 찾기:

docker logs service-name | grep -A 5 -B 5 "error"

일반적인 Docker 에러

"address already in use"

포트가 이미 사용 중이라는 뜻이다:

sudo ss -lntp | grep :3000

"No such file or directory"

Dockerfile의 COPY 또는 RUN 명령에서 잘못된 경로를 사용했다.

"Cannot connect to Docker daemon"

Docker 서비스가 실행되지 않았다:

sudo systemctl start docker

컨테이너 상태 확인

docker ps -a | grep service-name

상태(STATUS) 컬럼을 본다:

• Up: 실행 중
• Exited: 종료됨 (뒤에 종료 코드가 있음)
  • exit 0: 정상 종료
  • exit 1: 에러로 인한 종료

환경 변수와 시작 명령 확인

docker inspect service-name

여기서 볼 것:

• Cmd: 컨테이너 시작 명령
• Env: 환경 변수
• Mounts: 볼륨 마운트

빌드 로그 확인

이미지 빌드 단계에서 문제가 있으면:

docker build --no-cache -t image-name . 2>&1 | tail -50

각 RUN 단계에서 실패할 수 있다.

대화형 컨테이너로 직접 확인

같은 이미지로 대화형 컨테이너를 실행해서 내부 상태를 본다:

docker run -it --rm image-name /bin/sh

# 컨테이너 내부에서
ls -la /app  # 파일 확인
env | grep DATABASE  # 환경 변수 확인
node app.js  # 애플리케이션 시작해보기

로그 포맷 이해하기

Node.js 애플리케이션의 전형적인 로그:

> node app.js
Server is running on port 3000
Connected to database
...
error: Connect ECONNREFUSED 127.0.0.1:5432
FatalError: Database connection failed
Process exited with code 1

여기서 중요한 건 마지막 에러인 "Database connection failed"다.

디버깅 단계

1. docker logs 로 전체 로그 확인
2. grep error 로 에러만 필터링
3. docker inspect 로 설정 확인
4. docker run -it 로 대화형 테스트
5. Dockerfile 검토

이 순서를 따르면 Docker 문제의 95%를 해결할 수 있다.