Docker 컨테이너 로그를 읽고 문제를 찾는 순서

Docker 컨테이너가 실패했거나 동작하지 않을 때, 로그를 제대로 읽는 것이 가장 중요하다. 로컬에서는 잘 동작했던 설정도 배포 환경에서 다르게 보일 수 있기 때문이다.

컨테이너가 실행 중인지 확인하기

먼저 docker ps 명령으로 컨테이너 목록을 확인하자. 원하는 컨테이너가 실행 중인지, 아니면 exit 상태인지 확인해야 한다. exit 상태라면 왜 종료되었는지 알아야 한다.

docker ps
docker ps -a

로그 확인하기

docker logs 명령으로 컨테이너의 표준 출력과 표준 에러를 볼 수 있다. 마지막 100줄을 보려면 --tail=100 옵션을 사용하자. 실시간으로 로그를 보고 싶다면 -f 옵션을 붙이면 된다.

docker logs --tail=100 service-name
docker logs -f service-name

컨테이너 상세 정보 확인하기

docker inspect 명령으로 컨테이너의 환경 변수, 마운트된 볼륨, 포트 매핑, 상태 등을 확인할 수 있다. 이미지 태그가 정확한지, 환경 변수가 제대로 설정되었는지 여기서 다시 한 번 확인해보자.

포트 매핑 문제 찾기

컨테이너 내부에서는 3000번 포트를 사용하지만, 호스트에서는 8080번 포트로 매핑했다면, 외부에서는 8080으로 접근해야 한다. docker ps 명령의 PORTS 컬럼을 확인하면 실제 포트 매핑을 볼 수 있다. 또는 netstat 명령으로 호스트에서 정말 해당 포트가 열려있는지 확인할 수도 있다.

환경 변수 확인하기

컨테이너 내부에서 사용하는 환경 변수가 제대로 설정되었는지 확인하자. Dockerfile에서 ENV로 설정한 값과 docker run -e 옵션으로 전달한 값이 실제로 컨테이너에 적용되었는지 확인해야 한다. 필요하면 docker exec 명령으로 컨테이너 내부에 들어가서 echo $ENV_NAME 같은 명령을 실행해볼 수 있다.

애플리케이션 프로세스가 떠있는지 확인하기

컨테이너가 실행 중이더라도 내부의 애플리케이션 프로세스가 실패했을 수 있다. docker exec 명령으로 컨테이너 안에 들어가서 ps 명령을 실행해보자. 혹은 애플리케이션이 헬스체크 엔드포인트를 제공한다면 curl 명령으로 직접 확인해볼 수 있다.

이미지 빌드 로그 확인하기

컨테이너가 실패했다면, 이미지를 빌드할 때의 로그도 확인해보자. docker build 명령의 출력을 보면 어느 단계에서 실패했는지 알 수 있다. 특히 의존성 설치나 패키지 다운로드 단계에서 에러가 생기는 경우가 많다.

작은 변경부터 시작하기

로그를 읽고 원인을 찾았다면, 한 가지씩만 수정하고 다시 빌드해서 테스트하자. 여러 부분을 동시에 수정하면 어느 부분이 실제 원인인지 알기 어렵다. 특히 Dockerfile이나 환경 변수를 수정할 때는 신중하게 진행해야 한다.