Docker logs는 무엇을 보여줄까? 컨테이너 오류를 확인하는 가장 쉬운 방법

 

 

※ 이 글은 운영자가 직접 Intel N100 홈서버에서 Debian과 Docker 기반 서비스를 운영하며 서버 상태를 점검하고 기록한 경험을 바탕으로 작성했습니다. 글의 문장 정리와 구성에는 AI 도구의 도움을 약간 받았지만, 최종 내용은 운영자가 직접 검토하고 확인했습니다.

Docker logs는 무엇을 보여줄까? 컨테이너 오류를 확인하는 가장 쉬운 방법

도입

지난 글에서는 docker ps 명령으로 컨테이너의 STATUS를 확인하는 방법을 알아보았습니다.

Running, Exited, Restarting 같은 상태를 읽을 수 있게 되면 현재 컨테이너가 어떤 상황인지 빠르게 파악할 수 있습니다.

하지만 STATUS만으로는 한 가지 중요한 정보를 알 수 없습니다.

왜 그런 상태가 되었는지입니다.

Running으로 표시되는데도 웹사이트가 열리지 않을 수 있고, Exited 상태라고 표시되어도 왜 종료되었는지는 알 수 없습니다.

STATUS는 현재 결과를 보여줄 뿐, 그 결과가 만들어진 이유까지 설명해 주지는 않습니다.

이럴 때 운영자가 다음으로 확인하는 것이 바로 로그(Log)입니다.

STATUS가 현재 상태를 보여준다면, 로그는 그 상태가 된 이유를 찾는 단서를 보여줍니다.

Error, Failed, Warning 메시지를 중심으로 로그를 읽고 원인을 좁혀 가는 기본 점검 흐름을 정리한 인포그래픽입니다.

※ 다이어그램은 Docker 컨테이너의 상태 확인과 로그 점검 흐름을 바탕으로 AI 도구를 활용해 제작할 예정이며, 최종 구성과 내용은 운영자가 직접 검수합니다.
출처: 디지털 장난감

본문

① STATUS 다음에는 왜 로그를 볼까?

Docker를 처음 사용할 때는 문제가 생기면 설정 파일부터 열어보거나 Docker를 다시 실행해 보려는 경우가 많습니다.

하지만 실제 운영에서는 먼저 컨테이너가 실행 중인지 확인하고, STATUS를 살펴본 뒤, 이상이 있다면 로그를 확인하는 순서가 더 자연스럽습니다.

로그에는 컨테이너 안에서 실행되는 애플리케이션이 표준 출력과 표준 오류로 남긴 메시지가 표시됩니다.

프로그램이 정상적으로 시작되었는지, 중간에 오류가 발생했는지, 어떤 기능에서 문제가 생겼는지 확인하는 데 중요한 단서가 됩니다.

문제가 생겼을 때 바로 설정을 바꾸기보다, 먼저 상태와 로그를 확인하면 불필요한 수정과 재설치를 줄일 수 있습니다.

② docker logs 명령으로 로그 확인하기

Docker에서 컨테이너 로그를 확인하는 기본 명령은 다음과 같습니다.

docker logs 컨테이너명

예를 들어 WordPress 컨테이너의 이름이 wordpress라면 다음과 같이 입력합니다.

docker logs wordpress

컨테이너 이름 대신 컨테이너 ID를 사용할 수도 있습니다.

명령을 실행하면 해당 컨테이너가 출력한 로그가 화면에 표시됩니다.

처음에는 영어 문장이 많이 보여 당황할 수 있지만, 모든 내용을 한 번에 해석할 필요는 없습니다.

③ 로그에서 무엇을 먼저 보면 될까?

로그가 길게 출력되면 처음부터 끝까지 모두 읽기보다 먼저 눈에 띄는 오류 표현을 찾아보는 것이 좋습니다.

• Error : 오류가 발생했음을 알리는 경우가 많습니다.
• Failed : 실행이나 연결, 시작 과정이 실패했음을 나타낼 수 있습니다.
• Warning : 당장 중단되지는 않았지만 확인이 필요한 경고일 수 있습니다.

다만 Warning이 있다고 해서 항상 서비스가 고장 난 것은 아닙니다.

반대로 Running 상태라고 해서 애플리케이션 내부까지 모두 정상이라는 뜻도 아닙니다.

로그는 한 단어만 보고 결론을 내리기보다, 해당 메시지 앞뒤의 내용을 함께 살펴보는 것이 좋습니다.

④ 로그가 너무 길다면 최근 내용만 본다

컨테이너를 오래 실행했다면 로그가 매우 길 수 있습니다.

이럴 때는 --tail 옵션으로 최근 기록만 확인할 수 있습니다.

docker logs --tail 30 wordpress

위 명령은 WordPress 컨테이너의 최근 30줄을 출력합니다.

⑤ 실시간으로 새 로그를 확인하는 방법

서비스를 다시 실행하거나 브라우저에서 접속을 시도하면서 새로 발생하는 로그를 보고 싶을 때는 -f 옵션을 사용할 수 있습니다.

docker logs -f wordpress

이 명령을 실행하면 이후에 새로 출력되는 로그가 계속 화면에 나타납니다.

종료하려면 보통 Ctrl + C를 누릅니다.

⑥ STATUS와 로그를 함께 확인하는 기본 흐름

docker ps

↓

STATUS 확인

↓

docker logs 실행

↓

오류 단서와 원인 확인

STATUS는 현재 컨테이너가 실행 중인지, 종료되었는지, 재시작을 반복하는지를 보여줍니다.

로그는 그 상태가 만들어진 과정에서 어떤 메시지가 나왔는지를 보여줍니다.

상태 확인과 로그 확인을 하나의 세트처럼 익혀 두면 Docker 장애를 만났을 때 어디서부터 살펴봐야 할지 방향을 잡기 쉬워집니다.

운영노트

처음에는 컨테이너가 Running으로 표시되면 모든 것이 정상이라고 생각했습니다.

하지만 홈서버에서 WordPress 컨테이너가 Running 상태인데도 웹페이지가 열리지 않았던 적이 있었습니다.

Docker 자체의 문제라고 단정하기 전에 로그를 확인해 보니 데이터베이스 연결 과정에서 오류가 발생하고 있었습니다.

컨테이너는 실행 중이었지만, 그 안의 애플리케이션은 필요한 데이터베이스와 정상적으로 연결되지 못한 상태였습니다.

그 이후부터는 STATUS를 확인한 뒤 로그까지 함께 살펴보는 습관이 생겼습니다.

에디터의 해석노트

로그는 개발자만 읽는 어려운 화면처럼 느껴질 수 있습니다.

하지만 처음부터 모든 문장을 해석할 필요는 없습니다.

중요한 것은 문제가 생겼을 때 로그를 확인하는 습관을 만드는 것입니다.

Docker 운영에서 명령어를 많이 외우는 것보다, 상태를 확인하고 로그로 원인을 좁혀 가는 순서를 익히는 것이 먼저입니다.

참고 링크 (References)

1. Docker CLI Reference : docker container logs
2. Docker Docs : View container logs
3. Docker Docs : Configure logging drivers

트러블슈팅

문제 1. 로그가 너무 길어서 필요한 내용을 찾기 어렵다

docker logs --tail 30 wordpress처럼 --tail 옵션으로 최근 기록부터 확인합니다.

문제 2. docker logs를 실행했는데 아무 내용도 나오지 않는다

애플리케이션이 표준 출력이나 표준 오류로 메시지를 남기지 않았을 수 있습니다. 사용 중인 로깅 드라이버와 컨테이너 이름도 확인합니다.

문제 3. 로그가 영어라서 이해하기 어렵다

Error, Failed, Warning 같은 핵심 단어와 그 주변 한두 줄부터 확인합니다.

문제 4. Running 상태인데 Error 메시지가 보인다

Running은 컨테이너의 주 프로세스가 실행 중이라는 뜻이지 내부 기능이 모두 정상이라는 보장은 아닙니다.

문제 5. Restarting 상태라 로그가 계속 바뀐다

재시작 직전에 출력된 메시지가 중요할 수 있으므로 최근 로그와 실시간 로그를 함께 확인합니다.

문제 상황	먼저 확인할 방향
로그가 너무 김	--tail로 최근 기록 확인
아무 내용도 나오지 않음	컨테이너 이름과 로그 출력 방식 확인
영어 로그가 어려움	Error·Failed·Warning과 주변 문장 확인
Running인데 오류가 보임	실제 서비스 기능과 오류 반복 여부 확인
Restarting으로 로그가 바뀜	재시작 직전 메시지와 최근 로그 확인

핵심 체크포인트 10

1. docker logs는 컨테이너가 출력한 로그를 확인하는 기본 명령이다.
2. STATUS는 현재 상태를 보여주지만 그 원인을 모두 설명하지는 않는다.
3. Running 상태여도 애플리케이션 내부 오류가 발생할 수 있다.
4. Exited나 Restarting 상태에서는 로그가 원인을 찾는 중요한 단서가 된다.
5. 처음에는 Error, Failed, Warning 같은 표현부터 확인해도 충분하다.
6. 오류 단어 하나만으로 결론을 내리지 말고 앞뒤 메시지를 함께 본다.
7. --tail 30은 최근 30줄의 로그를 확인할 때 사용할 수 있다.
8. -f는 새로 출력되는 로그를 계속 확인할 때 사용할 수 있다.
9. 로그가 없다고 해서 반드시 정상이라는 뜻은 아니다.
10. docker ps와 docker logs를 함께 사용하는 습관이 중요하다.

마무리

이번 글에서는 Docker 컨테이너의 로그를 확인하는 가장 기본적인 방법을 살펴보았습니다.

docker ps와 STATUS가 현재 컨테이너의 상태를 보여준다면, docker logs는 그 상태가 만들어진 이유를 찾는 단서를 보여줍니다.

처음에는 로그 전체를 이해하려고 하지 않아도 됩니다.

Error, Failed, Warning 같은 표현과 최근 메시지부터 확인하면서 평소와 다른 부분을 찾아보면 됩니다.

STATUS로 현재를 확인하고 로그로 이유를 찾는 순서는 Docker 문제 해결의 가장 기본적인 출발점입니다.

다음 글에서는 Running 상태인데도 서비스에 접속되지 않는 상황을 예로 들어, STATUS와 로그를 함께 활용해 원인을 좁혀 가는 과정을 살펴보겠습니다.