API Gözlemlenebilirlik Nedir ve Nasıl Sağlanır

API gözlemlenebilirliği, API'nizin yaydığı telemetriyi (metrikler, günlükler ve izler) inceleyerek neden bu şekilde davrandığını anlama yeteneğidir. Sabit bir kontrol paneli setini izlemenin ötesine geçer. İyi yapılandırılmış bir API, yalnızca zaten ürettiği verileri kullanarak, hiç beklemediğiniz sorular da dahil olmak üzere, dahili durumu hakkında yeni sorular sormanıza olanak tanır.

API Gözlemlenebilirliği Gerçekte Ne Anlama Gelir?

Terim, kontrol teorisinden gelir; bir sistemin harici çıktılarından dahili durumunu çıkarabiliyorsanız, o sistem gözlemlenebilirdir. Yazılıma uygulandığında, bir API, yeni bir günlük kaydı satırı eklemek için yeni kod göndermeye gerek kalmadan herhangi bir davranışı teşhis etmek için çıktıları (telemetri) size yeterli bilgiyi verdiğinde gözlemlenebilirdir.

Bu son kısım önemlidir. Gözlemlenebilirlik ile, bir müşteri sabah 2'de belirli bir bölgedeki kullanıcılar için tek bir API sürümünde yavaş ödeme istekleri bildirdiğinde, zaten topladığınız verilerden "neden" sorusunu yanıtlayabilmelisiniz. Tahmin etmediğiniz hata modlarını araştırmak için yeterince zengin bir şekilde enstrümantasyon yaparsınız. Bu, yalnızca sormayı zaten bildiğiniz soruları yanıtlayan çalışma süresi kontrollerinden farklı bir hedeftir.

Gözlemlenebilirlik ve İzleme

İnsanlar bu kelimeleri birbirinin yerine kullanır, ancak farklı şeyleri tanımlarlar.

İzleme, bilinen sinyalleri izler ve bir eşiği aştıklarında uyarı verir. Ne izleyeceğinize (hata oranı, CPU, p99 gecikmesi) ve neyin kötü sayılacağına önceden karar verirsiniz. İzleme, "bozulmasını beklediğim şey bozuluyor mu?" sorusunu yanıtlar.

Gözlemlenebilirlik, sistemin bir özelliğidir: telemetrisi, dahili durum hakkında keyfi sorular sormanıza ne kadar izin verir. "Bu neden böyle davranıyor?" sorusunu yanıtlar, hatta "bu" hiç bir kontrol paneli oluşturmadığınız bir şey olsa bile.

Basitçe söylemek gerekirse, izleme bir şeylerin yanlış olduğunu söyler. Gözlemlenebilirlik ise nedenini bulmanıza yardımcı olur. İkisini de ihtiyacınız var. İzleme size uyarıyı verir; gözlemlenebilirlik ise uyarıdan temel nedene giden yolu gösterir. Uyarı tarafı hakkında daha derinlemesine bir inceleme isterseniz, API izleme kılavuzumuz bunu ayrıntılı olarak ele almaktadır.

İşte ayrım bir tabloda.

Üç Temel Direk: Metrikler, Günlükler, İzler

Gözlemlenebilirlik, genellikle üç temel direk olarak adlandırılan üç tür telemetriye dayanır. Satıcıdan bağımsız standart olan OpenTelemetry, bunları telemetri "sinyalleri" olarak resmileştirir. OpenTelemetry şu anda izleri, metrikleri, günlükleri ve bagajı desteklemekte olup, olaylar ve profiller geliştirme aşamasındadır. Klasik üçlü, ilk üç sinyale karşılık gelir.

Metrikler

Metrikler, zaman içinde toplanan sayısal ölçümlerdir. Bir API için en önemli olanlar istek oranı, hata oranı ve gecikme dağılımıdır. Gecikmeyi sadece ortalama olarak değil, yüzdelik dilimler (p95 ve p99) olarak bildirin. Ortalama, gerçek kullanıcıların hissettiği yavaş kuyruğu gizler.

Metrikler depolaması ucuz ve sorgulaması hızlıdır, bu da onları panolar ve uyarılar için ideal kılar. Zayıflıkları düşük kardinalitedir: p99 gecikmesinin arttığını söylerler, ancak buna hangi isteklerin neden olduğunu söylemezler.

Günlükler

Günlükler, ayrık olayların zaman damgalı kayıtlarıdır. Tutarlı alanlara sahip JSON olarak yayımlanan yapılandırılmış günlükler, filtrelenebildikleri ve toplanalabildikleri için serbest metin satırlarından çok daha kullanışlıdır.

{
  "timestamp": "2026-06-22T02:14:09Z",
  "level": "error",
  "method": "POST",
  "path": "/v2/checkout",
  "status": 503,
  "duration_ms": 4812,
  "trace_id": "8f3a1c9d2e7b4a16",
  "user_region": "ap-southeast-1",
  "api_version": "2026-05"
}

trace_id alanına dikkat edin. Bu kimlik, bir günlük satırını daha geniş istek akışına bağlayan şeydir ve bu bizi üçüncü direğe getirir.

İzler

Dağıtılmış bir izleme, bir isteğin hizmetler arasında nasıl hareket ettiğini takip eder. Her atlama bir 'span' haline gelir ve span'ler, tam yolu yeniden oluşturabilmeniz ve zamanın nerede harcandığını görebilmeniz için bir izleme kimliğini (trace ID) paylaşır. Bir istek bir ağ geçidi, bir yetkilendirme hizmeti ve üç mikro hizmetten geçtiğinde, izleme hangi atlamanın 4 saniye eklediğini gösterir.

İzler, mikro hizmetlerde hata ayıklamayı yönetilebilir kılar. Onlar olmadan, zincirdeki hangi hizmetin yavaş olduğunu tahmin edersiniz.

Üç temel direk birlikte çalışır. Bir metrik uyarısı ani yükselişi işaretler. Bir izleme, yavaş hizmeti gösterir. O hizmetten gelen, izleme kimliğine göre filtrelenmiş günlükler, tam olarak ne olduğunu size söyler.

RED Yöntemi ve Altın Sinyaller

Her şeyi takip etmek zorunda değilsiniz. RED yöntemi, herhangi bir isteğe dayalı hizmet için odaklanmış bir başlangıç noktası sunar. Tom Wilkie, 2015 yılında Weaveworks'teyken, Google'ın dört altın sinyalinden türetilerek bunu tanıttı.

RED şunları ifade eder:

• Rate (Oran): API'nizin saniyede işlediği istek sayısı.
• Errors (Hatalar): 5xx yanıtları ve beklenmeyen 4xx yanıtları gibi başarısız isteklerin sayısı veya oranı.
• Duration (Süre): p95 ve p99 olarak bildirilen istek gecikmelerinin dağılımı.

Oran     = saniyedeki istek sayısı
Hatalar  = %5xx (ve beklenmeyen %4xx) yanıtları
Süre     = gecikme dağılımı, p95 ve p99 olarak raporla (sadece ortalama değil)

RED, isteğe odaklıdır ve bu da API'ler, ağ geçitleri ve servis ağları için oldukça uygundur. Karşılığı olan USE (Utilization, Saturation, Errors - Kullanım, Doygunluk, Hatalar), CPU ve disk gibi altyapı kaynaklarını hedefler. Bir API için RED ile başlayın ve altındaki ana bilgisayarlar için USE'yi ekleyin.

SLI'ler ve SLO'lar: Sinyalleri Hedeflere Dönüştürme

Gözlemlenebilirlik verileri, onlara hedefler atandığında eyleme geçirilebilir hale gelir. Google SRE kitabı burada iki terimi tanımlar.

Bir hizmet seviyesi göstergesi (SLI), hizmetinizin bir yönünün nicel bir ölçüsüdür. Yaygın SLI'ler, istek gecikmesi, hata oranı (başarısız olan tüm isteklerin oranı) ve saniyede istek olarak verimliliktir. Bunlar RED ile açıkça örtüşür.

Bir hizmet seviyesi hedefi (SLO), bir SLI için bir hedef değer veya aralıktır. Örneğin: "28 günlük bir pencere üzerinde isteklerin %99,9'u 300 ms'nin altında tamamlanır." SLO, API'nin ne zaman yeterince sağlıklı olduğunu ve ne zaman özellikler yerine güvenilirliğe mühendislik zamanı harcanması gerektiğini size ve ekibinize söyler.

SLI'lar ve SLO'lar metriklerinize anlam katar. Onlar olmadan, bir gecikme grafiği sadece dalgalı bir çizgidir; onlarla birlikte, karşılaştırabileceğiniz bir sözleşmedir.

Araçlar: OpenTelemetry ve Arka Uçlar

Gözlemlenebilirlik araçlarını iki katmana ayırabilirsiniz: telemetriyi nasıl ürettiğiniz ve nereye gönderdiğiniz.

Üretim için OpenTelemetry, öğrenmeye değer bir standarttır. OpenTracing ve OpenCensus'ın birleşmesiyle oluşan bir Cloud Native Computing Foundation (CNCF) projesidir. Satıcı ve araçtan bağımsızdır, bu nedenle geniş bir arka uç yelpazesiyle çalışır. Temel prensibi, ürettiğiniz verilerin size ait olması ve satıcı kilitlenmesinin olmamasıdır. API'ler, dil SDK'ları, semantik konvansiyonlar, OTLP kablolu protokolü, otomatik enstrümantasyon ve OpenTelemetry Collector'ı sağlar.

Depolama ve analiz için seçenekleriniz var. Prometheus, Grafana ile eşleştirildiğinde, metrikler ve panolar için yaygın bir açık kaynak yığınıdır. Datadog ve Honeycomb gibi ticari platformlar, izleri, metrikleri ve günlükleri alır ve yüksek kardinaliteli sorgulama imkanı sunar. Datadog kullanıyorsanız, Datadog API kılavuzumuz verileri programatik olarak nasıl itip çekeceğinizi gösterir.

OpenTelemetry'nin amacı, bir kez enstrümantasyon yapmanız ve ardından yeniden enstrümantasyon yapmadan arka uçları değiştirebilmenizdir. Bu taşınabilirlik, onu erken benimsemenin ana nedenidir.

Test ve Sentetik Kontroller Nereye Uyar?

Gözlemlenebilirlik sadece üretimle ilgili bir mesele değildir. En faydalı sinyallerden bazıları, hem dağıtımdan önce hem de sonra bilerek çalıştırdığınız testlerden gelir.

Sola kaydırma: sözleşme testleri ve CI çalıştırmaları

Kod dağıtılmadan önce, sözleşme testleri API'nizin spesifikasyonuna hala uyduğunu doğrular. Bunları CI'da çalıştırmak, kullanıcıya ulaşmadan önce bozuk değişiklikleri yakalar. Her CI test çalıştırması bir sinyaldir: bir commit'e, bir ortama ve bir zaman damgasına bağlı bir geçiş veya başarısızlık. Bu geçmiş, sürüm kaliteniz hakkında gözlemlenebilirlik verisidir.

Apidog CLI, test senaryolarınızı bir pipeline'da çalıştırır. Node.js üzerine kurulmuştur ve Node v16 veya daha yenisini gerektirir.

npm install -g apidog-cli
# kurulumu doğrula
node -v && apidog -v

Bir ortama karşı bir test senaryosu çalıştırın. Ortam bayrağı zorunludur ve token'ınızı açıkça geçmelisiniz.

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -r html,cli

Burada -t test senaryosu kimliği, -e ortam kimliği ve -r rapor formatlarını (cli, html, json, junit) ayarlar. Varsayılan raporlayıcı cli'dır. Senaryoyu bir CSV veya JSON dosyasından yönlendirmek için -d ./data.csv (-d veya --iteration-data bayrağı bir dosya yolu alır) ekleyin. Ayrıca bir rapor özetini Apidog bulutuna da yükleyebilirsiniz.

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -r html,cli --upload-report

Kopyalayıp uyarlayabileceğiniz tam bir pipeline için, CI/CD kılavuzumuz için Apidog CLI'ye veya her bayrak için tam CLI referansına bakın.

Üretimde sentetik izleme

Sentetik izleme, canlı API'nize dışarıdan, bir kullanıcının yapacağı gibi, düzenli aralıklarla betiklenmiş istekler gönderir. Gerçek trafikten önce sorunları yakalar ve size sürekli bir gecikme ve kullanılabilirlik veri akışı sağlar. Temel bir API sağlık kontrolü en basit şeklidir. Tam sentetik izleme, onu giriş ve ardından ödeme gibi çok adımlı akışlara genişletir.

Bu kontroller kendi başlarına gözlemlenebilirlik sinyalleridir. Sabah 02:00'de 4 saniye süren başarısız bir sentetik çalıştırma, izlerinizi ve günlüklerinizi beslemek istediğiniz olay türüdür. Özel araçlar hakkında bir inceleme için sentetik test araçları derlememize ve üretim izleme platformları için API izleme araçları listemize bakın.

Apidog Planlanmış Görevlerle Gerçek Sinyaller Üretme

Apidog, Planlanmış Görevler aracılığıyla yinelenen sentetik sinyaller üretebilir. Bu özellik, yapılandırılmış test senaryolarını belirli zamanlarda otomatik olarak çalıştırır, sonuçları yakalar ve planlanmış regresyon testlerini destekler. Bunu Testler modülünde, Planlanmış Görevler altında bulabilirsiniz.

Buna güvenmeden önce bilmeniz gereken birkaç şey var. Planlanmış Görevler şu anda Beta aşamasındadır, bu nedenle onu uzun süreli stabil bir özellikten ziyade gelişmekte olan bir özellik olarak değerlendirin. Ayrıca yapılandırılmış kendi kendine barındırılan bir Çalıştırıcı gerektirir; "Çalıştıranlar" seçenekleri bugün kendi kendine barındırılan bir Çalıştırıcıyı listelemekte olup, Apidog Cloud'un yakında geleceği belirtilmektedir. Dolayısıyla henüz tam olarak bulut tabanlı bir planlanmış kontrol bulunmamaktadır.

Bir tane kurduğunuzda şunları seçersiniz:

• Test Senaryoları: yürütülecek bir veya daha fazla senaryo.
• Çalışma Modu: her Pazar saat 23:00 veya her 6 saatte bir gibi bir zaman döngüsü.
• Bildirim: her çalıştırmadan sonra veya sadece başarısızlık durumunda uyarılar.

Çalıştırma sayıları abonelik planınıza bağlıdır. Uygulamalı bir yapılandırma için Apidog Planlanmış Görevler kılavuzumuza bakın.

Buradaki değer, döngüyü kapatmaktır. API'nizi tek bir yerde tasarlar ve test edersiniz, ardından aynı senaryoları düzenli aralıklarla çalıştırırsınız, böylece eyleme geçebileceğiniz geçme/kalma ve gecikme sinyalleri üretmeye devam ederler. Apidog'u ücretsiz deneyin, kredi kartı gerekmez ve mevcut test senaryolarınızı yinelenen sinyallere dönüştürün.

Gözlemlenebilir Bir API'ye Pratik Bir Yol

Sıfırdan başlıyorsanız, şu sırayla çalışın:

1. Tutarlı bir şema ve her istekte bir izleme kimliği (trace ID) ile yapılandırılmış günlükler yayınlayın.
2. İzlerin, metriklerin ve günlüklerin bağlamı paylaşması ve arka uçlar arasında taşınabilir kalması için OpenTelemetry ile enstrümantasyon yapın.
3. RED metriklerini (oran, hatalar, p95 ve p99 ile süre) izleyin ve bunları bir kontrol paneline koyun.
4. Metriklerinizin sadece trendler değil, hedeflere sahip olması için SLI'lar ve SLO'lar tanımlayın.
5. Sürümden önce bozuk değişiklikleri yakalamak için CI'da sözleşme testleri ekleyin.
6. Üretime karşı, örneğin Apidog Planlanmış Görevlerle, düzenli olarak sentetik kontroller çalıştırın.

Hepsini bir anda yapmak zorunda değilsiniz. İlk adım bile, izleme kimlikli yapılandırılmış günlükler, sizi düz metin günlüklerinin çok ötesine taşır.

Sıkça Sorulan Sorular

API gözlemlenebilirliği nedir?

API gözlemlenebilirliği, bir API'nin yaydığı telemetriden, yani metrikler, günlükler ve izlerden dahili durumunu anlama yeteneğidir. Gözlemlenebilir bir API, yeni bir enstrümantasyon eklemeye gerek kalmadan, tahmin etmediğiniz sorunlar da dahil olmak üzere, neden belirli bir şekilde davrandığını araştırmanıza olanak tanır.

API gözlemlenebilirliği ve izleme: fark nedir?

İzleme, önceden tanımlanmış sinyalleri izler ve bir eşiği aştıklarında uyarı verir, "bozulmasını beklediğim bir şey bozuluyor mu?" sorusunu yanıtlar. Gözlemlenebilirlik, sistemin davranışı hakkında yeni, keyfi sorular sormanıza olanak tanıyan bir sistem özelliğidir, "bu neden oluyor?" sorusunu yanıtlar. İzleme bir şeylerin yanlış olduğunu söyler; gözlemlenebilirlik nedeni bulmanıza yardımcı olur. İkisini de ihtiyacınız var.

Gözlemlenebilirliğin üç temel direği nelerdir?

Üç temel direk metrikler, günlükler ve izlerdir. Metrikler, istek oranı ve gecikme yüzdelikleri gibi toplanmış sayılardır. Günlükler, ayrık olayların zaman damgalı kayıtlarıdır, ideal olarak JSON olarak yapılandırılmıştır. İzler, bir isteği hizmetler arasında takip ederek zamanın nerede harcandığını görmenizi sağlar. OpenTelemetry bunları telemetri sinyalleri olarak resmileştirir.

Bir API'yi nasıl gözlemlenebilir hale getirirsiniz?

Her istekte bir izleme kimliği (trace ID) ile yapılandırılmış günlükler yayınlayarak başlayın. Metriklerin, günlüklerin ve izlerin bağlamı paylaşması için kodunuzu OpenTelemetry ile enstrümantasyon yapın. RED metriklerini izleyin, hedefler olarak SLI'lar ve SLO'lar tanımlayın, CI'da sözleşme testleri ekleyin ve üretime karşı planlanmış sentetik kontroller çalıştırın. Her adım sorgulanabilir sinyal ekler.

Gözlemlenebilirlik için OpenTelemetry gerekli mi?

Hayır. Gözlemlenebilirlik, herhangi bir telemetri aracıyla elde edebileceğiniz bir özelliktir ve OpenTelemetry var olmadan çok önce birçok ekip özel aracıları kullanıyordu. Bununla birlikte, OpenTelemetry satıcıdan bağımsız CNCF standardıdır, bu nedenle onu benimsemek, bir kez enstrümantasyon yapmanıza ve Prometheus, Datadog veya Honeycomb gibi arka uçları yeniden enstrümantasyon yapmadan değiştirmenize olanak tanır. Güçlü bir varsayılandır, bir gereklilik değildir.