12. nginx 모니터링방법

Nginx 성능 모니터링

• 본 문서는 Zabbix에서 Nginx의 성능 지표를 모니터링하는 절차를 설명한다.
• Zabbix 공식 템플릿은 Nginx by HTTP와 Nginx by Zabbix agent 방식을 제공하며, 두 방식 모두 Nginx의 stub_status 페이지를 기반으로 동작한다.
• 단순성과 유지보수 측면에서는 외부 스크립트 없이 동작하는 공식 템플릿 방식이 권장된다.

구성 개요

• Zabbix Server 또는 Proxy: Nginx 상태 페이지를 HTTP 또는 Agent를 통해 수집한다.
• Nginx: ngx_http_stub_status_module로 상태 정보를 노출한다.
• 통신 포트:
  • Zabbix Web UI -> Zabbix Server: 80/tcp, 443/tcp
  • Zabbix Server/Proxy -> Nginx status page: 80/tcp, 443/tcp 또는 별도 모니터링 포트
  • Agent 방식 사용 시 Zabbix Server/Proxy -> Zabbix Agent: 10050/tcp 또는 Agent -> Server/Proxy: 10051/tcp
• 일반적으로 상태 페이지 경로는 /basic_status를 사용한다.

권장 방식

• 공식적으로는 Nginx by HTTP와 Nginx by Zabbix agent 두 가지 기본 템플릿을 사용할 수 있다.
• Agent가 꼭 필요 없는 구조를 원하면 Nginx by HTTP 방식이 단순하다.
• 이미 대상 서버에 Zabbix Agent가 배포되어 있다면 Nginx by Zabbix agent를 사용하는 것도 자연스럽다.

사전 준비

• Nginx가 정상 실행 중이어야 한다.
• stub_status 모듈이 포함된 빌드여야 한다.
• Zabbix Server 또는 Proxy에서 상태 페이지에 접근 가능해야 한다.
• 상태 페이지는 외부 전체 공개가 아니라 Zabbix Server 또는 Proxy에서만 접근 가능하도록 제한하는 것이 좋다.

stub_status 모듈 확인

• Nginx 빌드에 stub_status 모듈이 포함되어 있는지 확인한다.

nginx -V 2>&1 | grep -o with-http_stub_status_module

• 출력에 with-http_stub_status_module가 보이면 사용 가능한 상태이다.

Nginx 상태 페이지 설정

• 가장 일반적인 방법은 별도 경로 또는 별도 포트로 stub_status 페이지를 노출하는 것이다.
• 아래는 기본적인 예시이다.

server {
    listen 127.0.0.1:7777;

    location = /basic_status {
        stub_status;
        allow 127.0.0.1;
        allow ::1;
        deny all;
    }
}

• 또는 기존 virtual host 안에 location만 추가하는 방식도 사용할 수 있다.
• Zabbix Server가 원격지에 있다면 allow에 해당 IP를 추가해야 한다.

설정 반영

• 설정 파일 문법을 확인한 뒤 Nginx를 reload 한다.

nginx -t
systemctl reload nginx

상태 페이지 확인

• 설정 후 상태 페이지 응답을 확인한다.

curl http://127.0.0.1:7777/basic_status

• 응답에 Active connections, Reading, Writing, Waiting 값이 보이면 정상이다.

Web UI 등록

• Zabbix Web UI에서 대상 Nginx 서버 Host를 생성하거나 기존 Host를 사용한다.
• HTTP 방식이면 Nginx by HTTP 템플릿을 연결하고, Agent 방식이면 Nginx by Zabbix agent를 연결한다.
• Host interface에는 대상 서버의 IP 또는 DNS를 입력한다. HTTP 템플릿도 {HOST.CONN} 매크로 해석을 위해 Host interface가 필요할 수 있다.
• 템플릿 연결 후 Macros에서 상태 페이지 접속 정보를 환경에 맞게 조정한다.

주요 매크로

• Nginx 공식 템플릿 계열에서는 아래 매크로를 주로 사용한다.
  • {$NGINX.STUB_STATUS.HOST}
  • {$NGINX.STUB_STATUS.PATH}
  • {$NGINX.STUB_STATUS.PORT}
  • {$NGINX.RESPONSE_TIME.MAX.WARN}
  • {$NGINX.DROP_RATE.MAX.WARN}

예시 값

• {$NGINX.STUB_STATUS.HOST} = 127.0.0.1

• {$NGINX.STUB_STATUS.PATH} = basic_status

• {$NGINX.STUB_STATUS.PORT} = 7777

• 기존 웹 서비스 포트를 그대로 사용할 경우 포트와 경로를 실제 설정값에 맞게 바꿔야 한다.

수집 항목 예시

• Nginx availability
• Active connections
• Accepted connections
• Handled connections
• Requests
• Reading
• Writing
• Waiting
• 응답시간 및 drop rate 관련 트리거, 템플릿 구성에 따라 다름

방화벽 및 접근 제어

• 상태 페이지는 외부 공개 대신 관리망 또는 로컬 전용으로 두는 것이 좋다.
• HTTP 방식이면 Zabbix Server/Proxy가 해당 포트에 접근 가능해야 한다.
• Agent 방식이면 기존 Agent 정책에 따라 10050/tcp 또는 10051/tcp를 함께 고려해야 한다.
• 가능하면 127.0.0.1 또는 관리망 IP만 허용하고, reverse proxy 외부 공개 경로와 분리하는 것이 좋다.

대용량 운영 추천값

• 대규모 웹 서버 환경에서는 상태 페이지 경로, 포트, 템플릿, Host group을 표준화하는 것이 중요하다.
• 가능한 경우 stub_status를 로컬 전용 포트로 열고, Zabbix Proxy를 근접 배치하는 방식이 운영상 유리하다.
• 추천 시작 기준은 아래와 같다.

항목	추천값
템플릿	Nginx by HTTP 또는 Nginx by Zabbix agent
상태 경로	/basic_status
상태 포트	운영 포트 분리 시 7777 등 별도 포트
접근 허용	localhost 또는 Zabbix Server/Proxy IP만 허용
운영 방식	Host group, Macro, Template 표준화
수집 방식	단순 구성은 HTTP, 기존 Agent 배포 환경은 Agent 방식

구방식 참고

• 과거에는 UserParameter나 외부 스크립트 기반으로 Nginx 메트릭을 수집하는 사례가 많았다.
• 현재는 공식 템플릿을 사용하는 편이 유지보수와 표준화 측면에서 더 유리하다.
• 기존 커스텀 스크립트 환경은 즉시 제거하기보다 템플릿 기반 방식으로 단계적으로 전환하는 것이 현실적이다.

점검 항목

• stub_status 모듈이 포함되어 있는지 확인한다.
• /basic_status 페이지가 정상 응답하는지 확인한다.
• Zabbix Host에 올바른 템플릿이 연결되었는지 확인한다.
• 매크로 값이 실제 경로, 포트, 호스트 설정과 일치하는지 확인한다.
• 접근 제어, 방화벽, Host interface 오입력은 가장 흔한 원인이므로 우선 점검한다.

운영 팁

• Nginx 성능 지표만 보지 말고 OS 자원, 업스트림 응답, 인증서 만료, 웹 시나리오까지 함께 감시하는 것이 좋다.
• 로드밸런서 뒤에 있는 Nginx라면 실제 서비스 URL과 stub_status 전용 관리 URL을 분리해 두는 편이 운영에 유리하다.
• 웹 서버 수가 많을수록 포트, 경로, 템플릿, 매크로 이름 규칙을 통일하는 것이 중요하다.
• 먼저 기본 연결 상태만 수집한 뒤, 이후 upstream/SSL/API health 체크로 확장하는 방식이 안정적이다.