OpenTelemetry Nedir ve Neden Önemli?
Modern mikroservis mimarilerinde tek bir isteğin birçok servis, kuyruk ve veri deposu üzerinden akması sıradan bir durum haline geldi. Bu akıştaki gecikmeleri, hataları ve dar boğazları anlamanın en güvenilir yolu, dağıtık izleme (distributed tracing), metrik ve log verilerini bir arada toplayıp ilişkilendirmektir. OpenTelemetry (OTel), bu ihtiyacı standartlaştıran açık kaynak bir çatı sunar. Node.js projelerinde OTel kullanarak HTTP isteklerini, veritabanı çağrılarını ve iç fonksiyonlarınızı otomatik veya manuel olarak izleyebilir, verileri OTLP üzerinden Grafana Tempo ve Prometheus gibi sistemlere aktarabilirsiniz.
Mimari: SDK, Collector ve Gözlemleme Katmanı
Basit ve güvenilir bir kurulum için üç katman önerilir: (1) Uygulama içinde @opentelemetry/sdk-node ve otomatik enstrümantasyon paketleri çalışır. (2) Veriler OTLP ile OpenTelemetry Collector’a gönderilir. (3) Collector, gelen trace’leri Tempo’ya, metric’leri Prometheus’a, tercihen log’ları da Loki’ye yönlendirir. Böylece uygulama sadece bir hedefi bilir ve detayları Collector yönetir; yapılandırma değişiklikleri için uygulamayı yeniden dağıtmanız gerekmez.
Ön Koşullar ve Temel Kurulum
- Node.js 18+ önerilir, çünkü AsyncLocalStorage ile bağlam yayılımı daha stabil ve hızlıdır. Paket yöneticisi olarak npm, pnpm ya da yarn kullanabilirsiniz.
- Projenizde hizmet adını ve ortamı belirlemek için şu ortam değişkenlerini ayarlayın: OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTES=deployment.environment=prod. OTLP hedefi için Collector URL’niz genelde http://otel-collector:4318 (HTTP) veya 4317 (gRPC) olacaktır.
- OTel’i uygulamanın en erken aşamasında, sunucu başlatılmadan önce başlatın. Örneğin tracing.js dosyanızı ilk import eden dosya yapın; aksi halde bazı framework etkinlikleri enstrümante edilemez.
Otomatik ve Manuel Enstrümantasyon
Node.js tarafında @opentelemetry/auto-instrumentations-node HTTP, gRPC, Express, Fastify, MySQL, PostgreSQL, Redis gibi popüler bileşenleri otomatik izler. Bu sayede hiçbir kod yazmadan gelen istekler, giden HTTP çağrıları ve DB sorguları için span’ler oluşturulur. Kritik işlevlerinizde daha detaylı görünürlük istiyorsanız manuel enstrümantasyonla özel span’ler açıp önemli değişkenleri attribute olarak ekleyebilirsiniz. Örneğin sipariş tutarı, sepet boyutu veya kampanya kodu gibi iş metriklerini PII içermeyecek şekilde iliştirmek, kök nedeni çözmede büyük avantaj sağlar.
Örnek Yapılandırma Prensipleri
- Sampler: Üretimde yüzde 100 örnekleme pahalı olabilir. ParentBasedTraceIdRatio gibi oran bazlı sampler kullanın; giriş noktalarında yüzde 5-10, hata kodlarında ise koşullu olarak yüzde 100 örnekleme tercih edebilirsiniz.
- Propagator: Varsayılan W3C Trace Context yeterlidir. Hizmet zincirindeki tüm servislerin aynı propagatörü kullanması span bağlarının korunmasını sağlar.
- Resource Nitelikleri: service.name, service.version, deployment.environment, cloud.region gibi alanları doldurun. Sürüm numarası (örn. git SHA) hata takibinde altın değerindedir.
- OTLP Exporter: HTTP veya gRPC kullanılabilir. Kurumsal ağlarda HTTP genellikle daha sorunsuzdur. Timeouts ve yeniden deneme ayarlarını Collector’a bırakmak, uygulama üzerinde yükü azaltır.
OpenTelemetry Collector İpuçları
Collector, performans ve güvenilirlik için kritik bir bileşendir. Girişte otlp receiver, ortada batch ve attributes processor’ları, çıkışta tempo ve prometheus exporter’ları kullanılır. Batch, küçük span’lerin birikerek verimli gönderilmesini sağlar. Attributes processor ile gereksiz ya da hassas alanları (örn. e-posta, telefon) maskeleyebilir veya kaldırabilirsiniz. Tempo tarafında multi-tenant ihtiyaç varsa tenant başına service.name veya header tabanlı ayırma stratejisi kullanın.
Grafana Tempo ve Prometheus Entegrasyonu
Tempo, span verilerini ölçeklenebilir şekilde tutar ve Grafana ile mükemmel entegredir. Grafana’da “Explore” bölümünden trace ID ile arama yapabilir, isteklerin gecikme dağılımını görebilir ve sorunlu hizmeti hızlıca belirleyebilirsiniz. Metrikler için Prometheus, Node.js ve Collector’dan gelen ölçümleri toplayarak p95/p99 gecikme, hata oranı ve istek hacmini panolarda görselleştirir. Traces ile metrics arasında exemplar köprüleri kurduğunuzda, grafikteki bir pik noktasından ilgili trace’e tek tıkla bağlanabilirsiniz.
Performans, Maliyet ve Güvenlik
- Overhead: Otomatik enstrümantasyonun CPU/GC etkisi genellikle düşüktür, ancak sıcak yol (hot path) fonksiyonlarda manuel span açmayı sınırlayın. Toplayıcıda batch boyutlarını ve flush aralıklarını gözden geçirerek ağ trafiğini optimize edin.
- Maliyet: Oran bazlı örnekleme ve hata odaklı dinamik örnekleme ile depolama ve sorgu maliyetlerini kontrol altında tutun. Geliştirme ve staging ortamlarında daha yüksek oran, üretimde daha düşük oran kullanmak iyi bir dengedir.
- Gizlilik: PII ve gizli anahtarları span attribute’larına koymayın. Collector’da maskeleme kuralları ekleyin. Log ve trace korelasyonu yaparken veri minimizasyonuna dikkat edin.
Hata Ayıklama ve Yaygın Sorunlar
- Bağlam Kaybı: Özellikle eski Promise zincirlerinde veya üçüncü taraf kütüphanelerde bağlam kaybı olabilir. Node 18+ ve AsyncLocalStorage ile bu sorun büyük ölçüde azalır. Framework düzeyinde middleware sırasını kontrol edin.
- Eksik Span’ler: Uygulamada OTel başlatma dosyasının en önce import edildiğinden emin olun. Sunucu başlatma komutunuzda -r ./tracing.js gibi bir preload yaklaşımı kullanmak güvenilirdir.
- Gönderim Hataları: Collector’a ulaşamıyorsanız firewall veya servis keşfi sorunlarını kontrol edin. OTLP gRPC ile MTLS yapılandırıyorsanız sertifika yollarını ve SNI ayarlarını doğrulayın.
Sonuç
OpenTelemetry, Node.js uygulamalarınızda uçtan uca görünürlük sağlayarak sorun tespiti ve performans optimizasyonunu hızlandırır. Uygulama içinde hafif bir SDK, merkezde güçlü bir Collector ve gözlemleme katmanında Tempo/Prometheus kombinasyonu ile maliyet-etkin, taşınabilir ve geleceğe dönük bir çözüm elde edersiniz. Doğru örnekleme, sağlam kaynak nitelikleri ve sıkı gizlilik politikaları ile ekipler hem geliştirici deneyimini hem de kullanıcı memnuniyetini anlamlı biçimde artırabilir.
Hiç yorum yok:
Yorum Gönder