Prometheus + Nginx Entegrasyonu: Nginx Metriklerini İzleme Rehberi

Prometheus + Nginx Entegrasyonu Nedir?

Nginx kendi başına Prometheus formatında metrik üretmez. Bu yüzden en yaygın yapı:

Nginx → nginx-prometheus-exporter → Prometheus

Bu mimaride Nginx, stub_status endpoint’i üzerinden temel bağlantı ve istek bilgilerini sunar. Exporter bu verileri alır ve Prometheus’un okuyabileceği metriklere dönüştürür.

1. Nginx Stub Status Aktifleştirme

İlk adımda Nginx üzerinde metriklerin okunacağı endpoint’i açmamız gerekir. Genellikle /etc/nginx/nginx.conf veya ilgili site config dosyasına aşağıdaki blok eklenir:

server {
    listen 127.0.0.1:8081;
    server_name localhost;

    location /nginx_status {
        stub_status;
        allow 127.0.0.1;
        deny all;
    }
}

Bu yapı sayesinde nginx_status endpoint’i sadece localhost üzerinden erişilebilir olur. Bu, production ortamı için daha güvenli bir tercihtir.

Nginx yapılandırmasını test edip yeniden yükleyin:

nginx -t
systemctl reload nginx

Ardından endpoint’i test edin:

curl http://127.0.0.1:8081/nginx_status

2. nginx-prometheus-exporter Kurulumu

Nginx metriklerini Prometheus’a uygun hale getirmek için exporter kullanılır. Docker ile kurulum en hızlı yöntemdir:

docker run -d --name nginx-exporter --restart unless-stopped \
  --network host \
  nginx/nginx-prometheus-exporter:latest \
  -nginx.scrape-uri http://127.0.0.1:8081/nginx_status

Burada --network host kullanılması, özellikle Linux sunucularda host.docker.internal sorunlarını önlemek için daha pratik bir çözümdür.

Kurulumdan sonra exporter metrik endpoint’ini test edebilirsiniz:

curl http://127.0.0.1:9113/metrics | head

3. Prometheus Konfigürasyonu

Exporter ayağa kalktıktan sonra Prometheus’un bu endpoint’i scrape etmesi gerekir. prometheus.yml dosyasına aşağıdaki job eklenebilir:

scrape_configs:
  - job_name: "nginx"
    static_configs:
      - targets: ["127.0.0.1:9113"]
        labels:
          app: "blogbackend"
          environment: "production"

Eğer Prometheus container olarak çalışıyorsa ve host network kullanmıyorsa, hedef adresinize göre bu satırı düzenlemeniz gerekebilir.

Prometheus config doğrulaması için:

promtool check config /etc/prometheus/prometheus.yml

4. Prometheus’ta Nginx Metriklerini Test Etme

Prometheus arayüzüne giriş yaptıktan sonra aşağıdaki sorgularla Nginx metriklerini test edebilirsiniz:

nginx_connections_active

nginx_connections_reading

nginx_connections_writing

nginx_http_requests_total

Eğer bu sorgular veri döndürüyorsa Prometheus entegrasyonu doğru şekilde çalışıyor demektir.

Grafana ile Dashboard Görselleştirme

Grafana tarafında Prometheus datasource seçildikten sonra Nginx dashboard import edebilirsiniz. Hazır dashboard ID örnekleri:

• 12708
• 9614

Alternatif olarak kendi panellerinizi oluşturup aktif bağlantı, toplam request ve anlık trafik gibi metrikleri görselleştirebilirsiniz.

Önemli Nginx Metrikleri

Sık Karşılaşılan Sorunlar ve Çözümleri

1. Prometheus Restarting Hatası

En sık sebep YAML indent hatasıdır. Özellikle scrape_configs altında boşluk hizaları bozulursa Prometheus config parse edemez.

did not find expected key

Çözüm:

• promtool check config ile config doğrulaması yapın
• Tab yerine space kullanın
• Job bloklarının hizasını kontrol edin

2. nginx exporter DOWN Görünüyor

Bunun nedeni çoğu zaman yanlış scrape URI veya yanlış port kullanımıdır. Örneğin Nginx status endpoint’i 8081 dinlerken exporter’ın 8080 kullanması bu soruna yol açar.

Çözüm:

-nginx.scrape-uri http://127.0.0.1:8081/nginx_status

3. host.docker.internal Sorunu

Linux sunucularda host.docker.internal her zaman çalışmayabilir. Bu durumda host network kullanmak veya doğrudan host IP yazmak daha stabil bir çözümdür.

4. 403 Forbidden / Connection Refused

Genellikle allow/deny ayarları veya yanlış bind adresi kaynaklıdır.

Kontrol edilmesi gerekenler:

• listen 127.0.0.1:8081;
• allow 127.0.0.1;
• deny all;
• curl http://127.0.0.1:8081/nginx_status testi

Production Best Practices

• nginx_status endpoint’ini public açmayın
• Exporter’ı sadece internal networkte çalıştırın
• Prometheus retention süresini optimize edin
• Grafana dashboard’larında alert kuralları ekleyin
• Parolaları config dosyasında düz metin tutmayın

Sonuç

Bu rehberde Prometheus + Nginx entegrasyonunu production mantığıyla adım adım ele aldık. Nginx status endpoint’i açtık, exporter kurduk, Prometheus scrape ayarını yaptık ve Grafana dashboard tarafına kadar süreci tamamladık.

Bu yapı sayesinde:

• Nginx aktif bağlantılarını izleyebilirsiniz
• Toplam request sayısını takip edebilirsiniz
• Grafana dashboard’larında metrikleri görselleştirebilirsiniz
• Production hatalarını daha hızlı teşhis edebilirsiniz

JVM ve uygulama metriklerini de görmek istiyorsanız JavaMelody rehberine de göz atabilirsiniz.