İzleme: Loglar, Healthcheck, Prometheus/Grafana

Kendi barındırdığı bir n8n örneğini işleten herkesin güvenilir bir işletim için üç yapı taşına ihtiyacı vardır: hata ayıklama için anlamlı loglar, çalışma süresi izleme için bir healthcheck uç noktası ve kuyruklar, webhook'lar ve formlar hakkında daha derin bilgiler için Prometheus metrikleri. n8n bu üç yapı taşını zaten içerir, sadece ortam değişkenleri üzerinden etkinleştirilip bağlanmaları gerekir. Durum: Temmuz 2026.

Log seviyesini ve log çıktısını yapılandırma

n8n, winston loglama kütüphanesini kullanır ve log çıktısını n8n loglama dokümantasyonuna göre ortam değişkenleri üzerinden yapılandırır. Günlük kullanım için iki ayar yeterlidir.

• N8N_LOG_LEVEL: ayrıntı düzeyini kontrol eder. Düşükten yükseğe doğru silent, error, warn, info ve debug kullanılabilir, varsayılan değer info'dur. silent hiçbir şey çıktı vermez, debug en ayrıntılı tanı bilgisini sağlar ve öncelikle hedefe yönelik hata ayıklama için uygundur.
• N8N_LOG_OUTPUT: logların nereye yazılacağını belirler, console veya file, console,file olarak da birleştirilebilir. Varsayılan değer console'dur.
• N8N_LOG_FILE_LOCATION: file etkinken log dosyasının yolu. Varsayılan değer <n8n klasörü>/logs/n8n.log'dur.
• N8N_LOG_FILE_SIZE_MAX: log dosyası başına maksimum boyut, MB cinsinden, varsayılan 16 MB.
• N8N_LOG_FILE_COUNT_MAX: saklanan maksimum log dosyası sayısı, varsayılan 100. Birden fazla worker olduğunda, rotasyonun depolama alanına uymasını sağlamak için bu değer bilinçli olarak ayarlanmalıdır.

Üretim ortamında info genellikle yeterlidir, debug geçici bir önlem olarak kalır çünkü belirgin şekilde daha fazla veri yazar ve log dosyalarını daha hızlı doldurur.

Çalışma süresi izleme için healthcheck uç noktaları

İzleme için n8n dokümantasyonuna göre n8n, harici çalışma süresi kontrolleri için uygun iki health uç noktası sunar. /healthz uç noktası yalnızca örneğin erişilebilir olup olmadığını bildirir, bir HTTP 200 veritabanı durumu hakkında hiçbir şey söylemez. /healthz/readiness uç noktası daha ileri gider: yalnızca veritabanı bağlandığında ve migrate edildiğinde, yani örnek isteği işlemeye gerçekten hazır olduğunda 200 döner. Yol, N8N_ENDPOINT_HEALTH değişkeni üzerinden özelleştirilebilir, örneğin bir reverse proxy farklı bir health yolu beklediğinde.

Ana sunucuda health uç noktası her zaman etkindir. Queue modundaki worker örneklerinde ise varsayılan olarak devre dışıdır ve bir yük dengeleyici veya orkestratör worker'ları da kontrol etmesi gerekiyorsa QUEUE_HEALTH_CHECK_ACTIVE=true ile etkinleştirilmelidir.

Prometheus metriklerini dışa aktarma

Daha ayrıntılı işletim verileri için n8n, prom-client kütüphanesi üzerinden bir /metrics uç noktası sunar. Varsayılan olarak devre dışıdır ve hem main hem de worker örneklerinde N8N_METRICS=true ile etkinleştirilir. İşletim için önemli: uç nokta herkese açık erişilebilir olmamalı, yalnızca Prometheus verilerini tüketen dahili sistemler için erişilebilir olmalıdır, çünkü örneğin operasyonel ayrıntılarını ifşa eder.

Tam olarak hangi metrik ve etiketlerin çıktı verildiğini N8N_METRICS_INCLUDE_* değişkenleri kontrol eder. Queue modunda ölçeklendirme kurulumları için N8N_METRICS_INCLUDE_QUEUE_METRICS=true, n8n_scaling_mode_queue_jobs_active, _completed, _failed ve _waiting gibi metrikler sağlar, güncelleme hızı N8N_METRICS_QUEUE_METRICS_INTERVAL üzerinden ayarlanabilir. n8n 2.28.0'dan itibaren webhook ve form çalışma sürelerini de kaydetmek mümkündür: N8N_METRICS_INCLUDE_WEBHOOK_METRICS, n8n_webhook_request_duration_seconds histogramını etkinleştirir, N8N_METRICS_INCLUDE_FORM_METRICS ise form gönderimleri için karşılığı olan n8n_form_submission_duration_seconds'ı etkinleştirir. N8N_METRICS_INCLUDE_WORKFLOW_INFO ile ayrıca workflow ID'lerini okunabilir isimlerle ilişkilendiren bir n8n_workflow_info gauge'u etkinleştirilebilir, bu da şifreli ID'ler olmadan Grafana panelleri için kullanışlıdır.

Metrikleri Grafana ile görselleştirme

Metrikler etkinleştirildiğinde, Prometheus, n8n örneğinin /metrics yolunu düzenli olarak sorgulayan bir scrape job üzerinden toplamayı üstlenir, varsayılan olarak n8n 5678 portunda çalışır. Ardından Grafana, Prometheus sunucu adresiyle bir veri kaynağı olarak bağlanır. Başlamak için sıfırdan dashboard oluşturmaya gerek yoktur: n8n, n8n-observability GitHub projesinde desteklenen metrikler için hazır Grafana dashboard'ları yayınlar, bunlara webhook ve form çalışma süreleri de dahildir.

Bağlam için önemli: /metrics uç noktası yalnızca self-hosted örneklerde kullanılabilir, n8n Cloud'da mevcut değildir. Self-hosting ile üretken çalışmak ve sürece tam hakimiyet sahibi olmak isteyenler NordFlux'un n8n danışmanlığından destek bulabilir.

n8n'de izleme hakkında sıkça sorulan sorular

/metrics uç noktası n8n Cloud'da kullanılabilir mi?

Hayır, n8n dokümantasyonuna göre Prometheus metrik uç noktası yalnızca self-hosted örnekler için tasarlanmıştır. Cloud örneklerinde kullanılamaz.

Üretim ortamı için hangi log seviyesi uygundur?

Varsayılan değer info, genellikle sürekli işletim için yeterli bağlam sağlar. debug belirgin şekilde daha fazla çıktı üretir ve öncelikle belirli bir sorunu hedefe yönelik ve zamanla sınırlı şekilde incelemek için uygundur.

Queue modu kurulumunda worker'ları nasıl izlerim?

Health uç noktası, queue modundaki worker örneklerinde varsayılan olarak devre dışıdır ve QUEUE_HEALTH_CHECK_ACTIVE=true ile etkinleştirilmelidir. Ayrıca N8N_METRICS_INCLUDE_QUEUE_METRICS=true, kuyruktaki aktif, tamamlanmış, başarısız olmuş ve bekleyen işlere ilişkin metrikler sağlar.

n8n'i izlemek için mutlaka Grafana'ya ihtiyacım var mı?

Hayır. Basit bir çalışma süresi izleme için /healthz veya /healthz/readiness uç noktası yeterlidir, birçok izleme aracı bunu doğrudan bir HTTP kontrolü üzerinden sorgulayabilir. Grafana, /metrics uç noktasından gelen ayrıntılı geçmişlerin, kuyruk veya gecikme verilerinin grafiksel olarak değerlendirilmesi gerektiğinde önem kazanır.