로그 및 디버깅

Nginx 로그 및 디버깅

개요

Nginx는 access.log(접근 로그)와 error.log(에러 로그) 두 가지 로그를 통해 모든 요청과 오류를 기록한다. 로그는 문제 진단과 서비스 모니터링의 핵심 도구이다.

서버를 운영하다 보면 반드시 문제가 생겨요. "사이트가 안 열려요!", "갑자기 느려졌어요!", "404 에러가 나요!" 같은 상황이 오면, 가장 먼저 확인해야 할 곳이 바로 로그 파일이에요.

로그는 서버의 블랙박스와 같아요. 무슨 요청이 들어왔고, 어떻게 처리했고, 에러가 났다면 왜 났는지 전부 기록되어 있거든요. 로그를 잘 읽을 줄 알면 대부분의 문제는 금방 해결할 수 있어요!

로그 파일 위치

graph TD
    A["/var/log/nginx/"] --> B["access.log<br/>📊 접근 로그"]
    A --> C["error.log<br/>🚨 에러 로그"]

    B --> B1["모든 HTTP 요청 기록<br/>IP, URL, 상태코드, 응답시간"]
    C --> C1["오류 및 경고 기록<br/>설정 오류, 연결 실패 등"]

    style B fill:#90EE90
    style C fill:#FFB3B3
Mermaid
복사

로그 파일	경로	기록 내용
access.log	/var/log/nginx/access.log	모든 HTTP 요청 (성공 + 실패)
error.log	/var/log/nginx/error.log	오류, 경고, 디버그 정보

Access Log (접근 로그)

기본 로그 형식

192.168.1.100 - - [17/Apr/2026:10:30:15 +0900] "GET /api/users HTTP/1.1" 200 1234 "<https://example.com/>" "Mozilla/5.0..."
Plain Text
복사

각 부분의 의미:

순서	값	의미
1	192.168.1.100	클라이언트 IP 주소
2	-	인증된 사용자 (보통 비어있음)
3	-	Remote user
4	[17/Apr/2026:10:30:15 +0900]	요청 시간
5	"GET /api/users HTTP/1.1"	요청 메서드 + 경로 + 프로토콜
6	200	HTTP 상태 코드
7	1234	응답 바이트 수
8	"<https://example.com/>"	Referer (어디서 왔는지)
9	"Mozilla/5.0..."	User-Agent (브라우저 정보)

커스텀 로그 포맷

# nginx.conf의 http 블록에서
http {
    # 기본 포맷
    log_format main '$remote_addr - $remote_user [$time_local] '
                    '"$request" $status $body_bytes_sent '
                    '"$http_referer" "$http_user_agent"';

    # 확장 포맷 (응답 시간 포함 — 성능 분석용)
    log_format detailed '$remote_addr - [$time_local] '
                        '"$request" $status $body_bytes_sent '
                        'rt=$request_time '
                        'urt=$upstream_response_time '
                        '"$http_user_agent"';

    # JSON 포맷 (로그 분석 도구 연동용)
    log_format json_log escape=json '{'
        '"time": "$time_iso8601",'
        '"remote_addr": "$remote_addr",'
        '"method": "$request_method",'
        '"uri": "$request_uri",'
        '"status": $status,'
        '"body_bytes_sent": $body_bytes_sent,'
        '"request_time": $request_time,'
        '"upstream_response_time": "$upstream_response_time",'
        '"user_agent": "$http_user_agent"'
    '}';

    access_log /var/log/nginx/access.log detailed;
}
Plain Text
복사

변수	설명	활용
$request_time	총 요청 처리 시간 (초)	느린 요청 찾기
$upstream_response_time	백엔드 응답 시간	Spring Boot 병목 확인
$bytes_sent	전송 바이트	대역폭 모니터링
$connection	연결 번호	연결 추적
$request_length	요청 크기	큰 요청 감지

Error Log (에러 로그)

에러 로그 레벨

error_log /var/log/nginx/error.log warn;
Plain Text
복사

레벨	심각도	설명	사용 시점
debug	최저	디버그 정보 (매우 상세)	개발/디버깅 시만
info	낮음	일반 정보	상세 모니터링
notice	보통	주목할 만한 이벤트	일반 운영
warn	주의	경고 (서비스 영향 없음)	프로덕션 권장
error	높음	오류 (일부 기능 실패)	프로덕션 최소
crit	매우 높음	치명적 오류	심각한 문제만
alert	긴급	즉시 조치 필요	긴급 문제만
emerg	최고	시스템 사용 불가	시스템 다운

프로덕션에서는 보통 warn 또는 error 레벨을 사용해요. debug는 로그가 너무 많이 쌓여서 디스크를 가득 채울 수 있으니 주의!

흔한 에러 로그 메시지

에러 메시지	의미	해결
connect() failed (111: Connection refused)	백엔드 서버 미실행	Spring Boot 상태 확인
open() "/var/www/..." failed (2: No such file)	파일 없음	경로 확인, 파일 존재 확인
open() "..." failed (13: Permission denied)	권한 없음	chown www-data:www-data
client intended to send too large body	요청 크기 초과	client_max_body_size 늘리기
upstream timed out	백엔드 응답 시간 초과	proxy_read_timeout 늘리기

실시간 로그 모니터링 명령어

# 접근 로그 실시간 확인
tail -f /var/log/nginx/access.log

# 에러 로그 실시간 확인
tail -f /var/log/nginx/error.log

# 두 로그 동시 확인
tail -f /var/log/nginx/access.log /var/log/nginx/error.log

# 특정 상태코드만 필터링
tail -f /var/log/nginx/access.log | grep " 500 "
tail -f /var/log/nginx/access.log | grep " 404 "

# 특정 IP의 요청만 보기
tail -f /var/log/nginx/access.log | grep "192.168.1.100"

# 느린 요청 찾기 (응답 시간 1초 이상)
awk '$NF > 1' /var/log/nginx/access.log
Bash
복사

로그 분석 명령어

# 가장 많이 접속한 IP (상위 10개)
awk '{print $1}' /var/log/nginx/access.log | sort | uniq -c | sort -rn | head -10

# 가장 많이 요청된 URL (상위 10개)
awk '{print $7}' /var/log/nginx/access.log | sort | uniq -c | sort -rn | head -10

# 상태코드별 요청 수
awk '{print $9}' /var/log/nginx/access.log | sort | uniq -c | sort -rn

# 시간대별 요청 수
awk '{print $4}' /var/log/nginx/access.log | cut -d: -f1,2 | sort | uniq -c

# 4xx, 5xx 에러 수
grep " [45][0-9][0-9] " /var/log/nginx/access.log | wc -l
Bash
복사

로그 로테이션

로그 파일은 계속 커지기 때문에, 주기적으로 **로테이션(순환)**해야 해요.

flowchart LR
    A["access.log<br/>(현재 기록 중)"] -->|"로테이션"| B["access.log.1<br/>(어제 로그)"]
    B --> C["access.log.2.gz<br/>(그제 로그, 압축)"]
    C --> D["...<br/>(14일치 보관)"]
    D --> E["🗑️ 자동 삭제"]
Mermaid
복사

# logrotate 설정 확인
cat /etc/logrotate.d/nginx
Bash
복사

/var/log/nginx/*.log {
    daily              # 매일 로테이션
    missingok          # 로그 파일 없어도 에러 아님
    rotate 14          # 14일치 보관
    compress           # 오래된 로그 gzip 압축
    delaycompress      # 하루 뒤에 압축
    notifempty         # 빈 파일은 로테이션 안 함
    create 0640 www-data adm
    sharedscripts
    postrotate
        [ -f /var/run/nginx.pid ] && kill -USR1 `cat /var/run/nginx.pid`
    endscript
}
Plain Text
복사

디버깅 워크플로우

flowchart TD
    A["🚨 문제 발생!"] --> B["1️⃣ error.log 확인<br/>tail -f error.log"]
    B --> C{"에러 메시지<br/>확인됨?"}
    C -->|Yes| D["에러 메시지 기반<br/>문제 해결"]
    C -->|No| E["2️⃣ access.log 확인<br/>상태코드 분석"]
    E --> F{"상태코드<br/>비정상?"}
    F -->|4xx| G["클라이언트 문제<br/>경로, 권한 확인"]
    F -->|5xx| H["서버 문제<br/>백엔드 상태 확인"]
    F -->|No| I["3️⃣ 네트워크 확인<br/>curl, ss 명령어"]

    D --> J["✅ 해결!"]
    G --> J
    H --> J
    I --> J
Mermaid
복사

핵심 정리

access.log: 모든 HTTP 요청 기록 — IP, URL, 상태코드, 응답시간

error.log: 오류/경고 기록 — 프로덕션에서는 warn 레벨 권장

실시간 모니터링: tail -f /var/log/nginx/access.log

커스텀 로그 포맷에 $request_time 추가하면 성능 분석 가능

logrotate로 로그 파일 자동 순환 관리 필수