Profile picture

[Docker / 모니터링] nginx 메트릭(Metric) 시각화하기

JaehyoJJAng2025년 03월 10일

개요

image 사진 출처: Grafana의 Nginx 대시보드


nginx는 많은 웹 서버 환경에서 필수적으로 사용되죠?

저또한 홈서버 상단에 nginx가 위치해있습니다.


nginx를 운영하다보면 nginx의 상태와 트래픽을 실시간으로 모니터링하고 싶은 순간이 오는데요!

특히 access.log와 error.log는 중요한 로그이지만, 텍스트로 확인하기에는 비효울적입니다.


이번 포스팅에서는 Prometheus + Telegraf + Grafana 조합을 통해 Nginx-exporter로부터 메트릭을 수집하고,

이를 Grafana 대시보드 로 시각화하는 전체 과정을 정리해볼까 합니다!

시각화를 위한 대시보드는 14900 ID를 사용할 예정입니다!


메트릭을 수집하기 위한 준비사항

nginx의 메트릭 정보를 수집하기 위해 필요한 것은 다음과 같습니다.

  • nginx
  • nginx-prometheus-exporter
  • prometheus
  • grafana

nginx에서 metric 정보를 생성하는 방법

nginx 서버에서 메트릭 데이터를 생성하려면 stub_status 모듈을 활성화 시켜줘야 합니다!

오픈소스로 공개된 nginx와 상용 버전(nginx-plus)에서 수집할 수 있는 메트릭 데이터는 차이가 있답니다! 관련 링크


stub_status를 활성화 했다고 메트릭 정보가 자동으로 수집되는 것은 아닙니다!

메트릭 정보를 실시간으로 수집하기 위해서는 nginx-prometheus-exporter를 설치해줘야 해요!


먼저 위 패키지를 설치하기 이전에 stub_status를 활성화 시켜주겠습니다.


먼저 stub_status 모듈이 nginx에 내장되어 있는지 확인해볼게요!

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

이제 /etc/nginx/nginx.conf 파일 내부에 http 스코프를 추가해줄게요.

* 80 포트에 대한 설정은 이미 /etc/nginx/sites-available/default 파일에서 listen 설정이 되있습니다. 주의해주세요.


기존 server에 /metrics 로케이션을 다음과 같이 추가해주세요!

server {
  # ...
  listen 80;
  server_name localhost;

  location /metrics {
    stub_status on; # stub_status 활성화
    allow all; # allow 접근을 허용할 주소 설정
    # deny 접근을 허용하지 않을 주소 설정
  }
}

만약 기존에 nginx를 운영 중이셨다면 기존 server 설정에 location /metrics 섹션만 추가해 작성해주시면 됩니다.


변경된 설정을 적용해주겠습니다.

sudo nginx -t
sudo systemctl restart nginx

nginx가 정상적으로 재시작 되었다면 메트릭이 수집되는지 확인해볼게요.

curl localhost/metrics

Active connections: 2 
server accepts handled requests
 9 9 363 
Reading: 0 Writing: 1 Waiting: 1

nginx-prometheus-exporter 설치하기

nginx-prometheus-exporter의 역할을 nginx에서 노출시킨 메트릭 정보를 Prometheus가 수집할 수 있도록 하는 에이전트입니다.


저희는 위에서 nginx의 stub_status를 활성화하여 메트릭 정보가 수집된 것을 볼 수 있었어요!

여기서 nginx-prometheus-exporter를 설치하면 해당 에이전트가 자동으로 nginx 메트릭을 수집하여 줍니다!


그럼 이제 해당 exporter 설치해보도록 할게요
(최신 릴리즈 정보는 nginx-prometheus-exporter Release를 참고해주세요.)

# exporter 다운로드
wget -O nginx-prometheus-exporter-1-4-2.tar.gz https://github.com/nginx/nginx-prometheus-exporter/releases/download/v1.4.2/nginx-prometheus-exporter_1.4.2_linux_386.tar.gz

# 압축 해제
tar -xvf nginx-prometheus-exporter-1-4-2.tar.gz

압축을 해제하면 nginx-prometheus-exporter 라는 실행파일이 생깁니다.

실행파일 사용 방법은 다음과 같습니다.
(실행 관련 문서는 여기에 더 자세하게 공지되어 있습니다.)

nginx-prometheus-exporter --nginx.scrape-uri=http://<nginx_ip>:8080/stub_status

저희는 이전에 /metrics 라는 로케이션으로 stub_status를 활성화하였고, 앤드포인트는 http://<nginx_서버_ip>/metrics 입니다.

nginx-prometheus-exporter --nginx.scrape-uri=http://<nginx_ip>/metrics

위 명령을 실행하면 포트 번호 9113이 부여된 프로그램이 백그라운드로 실행됩니다.


만약 기본 포트 번호를 변경하고 싶다면

-web.listen-address=<원하는_포트_번호>

-web.listen-address 옵션을 추가하시면 됩니다.


Telegraf 설치 및 설정하기

Telegraf는 다양한 소스에서 데이터를 수집하고 InfluxDB에 전송하는 에이전트입니다.

다양한 데이터 소스를 지원하고, 시스템 정보, 로그, 센서 등의 다양한 데이터를 수집할 수 있어요. image


telegraf를 설치해볼게요!

sudo apt-get update
sudo apt-get install telegraf

/etc/telegraf/telegraf.conf 파일을 수정할게요.

맨 아래에 다음 내용을 추가해주세요.

#nginx-metrics and logs
[[inputs.nginx]]
     urls = ["http://localhost:9113/metrics"] # 앞서 nginx exporter endpoint를 넣어주세요.
     response_timeout = "5s"
[[inputs.tail]]
    name_override = "nginxlog"
    files = ["/var/log/nginx/access.log"]
     from_beginning = true
    pipe = false
    data_format = "grok"
    grok_patterns = ["%{COMBINED_LOG_FORMAT}"]

# telegraf 프로메테우스 연동
###############################################################################
#                            OUTPUT PLUGINS                                   #
###############################################################################

[[outputs.prometheus_client]]  # <<<< 이 두 라인을 입력해야해요. 8080 포트 열기
    listen = "0.0.0.0:8080"    # <<<< 이 포트로 프로메테우스가 telegraf를 호출합니다.

# Configuration for sending metrics to InfluxDB
# [[outputs.influxdb]]           <<< 이 라인을 주석처리해야함

telegraf를 재시작 해주겠습니다.

sudo systemctl restart telegraf && systemctl status telegraf

# 메트릭이 수집되는지 확인해볼게요.
curl localhost:8080/metrics

# 아래 내용이 출력되면 완료입니다.
cpu_usage_guest{cpu="cpu-total",host="dev-ubuntu"} 0
cpu_usage_guest{cpu="cpu0",host="dev-ubuntu"} 0
...

모니터링 도구 설치하기

  • 해당 챕터는 모니터링 서버에서 진행해주세요!
    • 모니터링 도구를 웹 서버에서 같이 배포할 예정이시라면 그대로 진행해주셔도 상관없습니다!
    • 저는 웹 서버와 모니터링 서버가 분리되어 있는 상황이기 때문에 따로 구축된 모니터링 서버에서 진행하도록 하겠습니다.

프로메테우스와 그라파나를 설치해줘야 합니다.


프로메테우스 설치

설치 방법이 변경될 수 있으니 공식 문서의 릴리즈 별 설치 방법을 참고하여 설치해주세요.


wget https://github.com/prometheus/prometheus/releases/download/v2.39.0/prometheus-2.39.0.linux-arm64.tar.gz
tar xvfz prometheus-2.39.0.linux-arm64.tar.gz

설치 폴더 내의 prometheus.yml 파일을 다음과 같이 수정해줍시다.

scrape_configs:
  - job_name: "nginx-exporter"
    static_configs:
      - targets: ["아이피주소:포트번호"]
      
  - job_name: "other-server"
    static_configs:
      - targets: ["아이피주소:포트번호"]
   ...

nginx-exporter의 target IP와 포트 번호를 적어주시면 됩니다.


설정한 뒤에 프로메테우스를 재시작 해주겠습니다.

# 8080포트로 실행
nohup /home/ubuntu/prometheus-2.39.0.linux-arm64/prometheus --web.enable-lifecycle --config.file=/home/ubuntu/prometheus-2.39.0.linux-arm64/prometheus.yml --web.listen-address=:8080 > prometheus.log 2>&1 &

# prometheus.yml 리로드
curl -X POST http://localhost:8080/-/reload

재시작 한 후에 브라우저에서 프로메테우스 포트로 접근하면 다음과 같은 정보 확인이 가능합니다. image


그라파나 설치

그라파나 또한 설치 방법이 변경될 수 있으니 공식 문서의 릴리즈 별 설치 방법을 참고하여 설치해주세요.

wget https://dl.grafana.com/oss/release/grafana-9.2.0.linux-arm64.tar.gz
tar -zxvf grafana-9.2.0.linux-arm64.tar.gz

vi /home/ubuntu/grafana-9.2.0/conf/defaults.ini

# 실행
cd /home/ubuntu/grafana-9.2.0/bin/ && nohup /home/ubuntu/grafana-9.2.0/bin/grafana-server > grafana.log 2>&1 &

그라파나는 기본 포트가 3000번입니다. 다른 포트로 변경을 원하시면 conf/defaults.ini 파일의 http_port 변수 값을 수정해주세요.

  • 기본 아이디 및 패스워드는 admin 입니다.

datasource 등록

프로메테우스를 데이터소스로 등록해주세요.

  • Connections -> Data Sources -> Add Datasource -> Prometheus
  • HTTP URL만 설정해주시고 Save 해주시면 됩니다.
    • 이 때 Fail이 발생하는 경우 프로메테우스 서버의 IP를 확인해주세요.

대시보드 등록

사용할 대시보드의 ID 값은 다음과 같습니다.

  • 14900

image 저는 이미 등록한 대시보드라서 다음과 같이 경고문이 나왔네요!


대시보드를 확인해보면 다음과 같이 구성됨을 볼 수 있습니다! image


마무리

이렇게 Grafana + Prometheus + Telegraf 조합을 사용하여 nginx 로그 파일을 시각화하는 방법에 대해서 알아봤습니다.


참고로!

웹 서버 로그를 분석하는 도구로는 이러한 방법 말고 GoAccess 오픈소스 프로젝트를 사용하는 방법도 있답니다! image

    Tag -
Loading script...