Docker 로그를 읽고 컨테이너 문제를 진단하는 방법

운영 중 Docker 컨테이너가 정상 작동하지 않을 때는 작은 신호도 빨리 분리해서 봐야 한다. 컨테이너 자체가 실행 중인지, 실행 중이라면 로그는 어떤 상태인지를 먼저 파악한다.

현재 상태 파악

가장 먼저 볼 명령어들:

docker ps
docker ps -a  # 정지된 컨테이너도 포함

PID와 상태(Up, Exited)를 본다. Exited 상태라면 컨테이너가 종료된 것이므로, 왜 종료되었는지가 중요하다. 정상적으로 종료되었는지 아니면 에러로 인해 중단되었는지 확인한다.

로그 확인

컨테이너의 마지막 로그를 본다:

docker logs --tail=100 service-name
docker logs -f service-name  # 실시간 로그 추적

--tail=100은 마지막 100줄을 보는 것이고, -f 플래그는 새로운 로그를 계속 따라간다. 에러 로그에서 "permission denied"나 "connection refused" 같은 키워드를 찾아본다.

상세 정보 확인

컨테이너의 설정과 네트워크 상태를 본다:

docker inspect service-name

이 명령은 매우 상세한 정보를 JSON 형식으로 출력한다. 특히 확인할 부분:

• State: 실행 중(running)인지, 종료(exited)되었는지
• Mounts: 볼륨이 제대로 마운트되었는지
• NetworkSettings: 포트 매핑이 맞게 설정되었는지
• Env: 환경변수가 정확하게 전달되었는지

로컬과 운영 환경의 차이

같은 이미지를 배포해도 환경이 다르면 동작이 달라진다:

• 이미지 태그: 로컬에서 latest로 빌드했는데, 실제 배포는 다른 태그일 수 있다.
• 환경변수: 로컬 개발용과 운영 환경용 설정이 다를 수 있다.
• 볼륨: 로컬에는 데이터가 있지만, 운영 환경에서는 볼륨이 아직 비어 있을 수 있다.

단계별 진단

1. 컨테이너가 정말 실행 중인지 먼저 확인한다. Exited 상태면 로그에서 마지막 에러를 찾는다.
2. 실행 중이라면, 로그에서 "error", "failed", "exception" 같은 키워드를 찾는다.
3. 네트워크 연결을 확인한다. 포트가 올바르게 매핑되었는지, 외부에서 접근 가능한지 테스트한다.
4. 권한 문제가 있는지 확인한다. 파일 쓰기, 네트워크 소켓 생성 등에 권한이 필요할 수 있다.

마무리

한 가지씩 확인하면서 불필요한 변경을 최소화한다. 처음에는 로그만 봐도 대부분의 문제가 눈에 띄기 때문이다.