DEV Community

Cover image for API Gözlemlenebilirlik Nedir ve Nasıl Sağlanır
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

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

API gözlemlenebilirliği, API’nizin ürettiği telemetriyi (metrikler, günlükler ve izler) kullanarak “neden böyle davrandı?” sorusunu yanıtlayabilme yeteneğidir. Amaç yalnızca dashboard izlemek değil; beklenmeyen bir hata, gecikme veya bölgesel sorun çıktığında mevcut verilerle kök nedene inebilmektir.

Apidog'u bugün deneyin

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

Gözlemlenebilirlik, kontrol teorisinden gelir: Bir sistemin harici çıktılarından dahili durumunu çıkarabiliyorsanız, sistem gözlemlenebilirdir.

API tarafında bu şu anlama gelir:

  • Yeni log satırı eklemek için yeniden deploy yapmadan sorun teşhis edebilmek
  • Hangi endpoint’in, hangi bölgede, hangi API sürümünde yavaşladığını görebilmek
  • Metrik, log ve trace verilerini aynı istek bağlamında ilişkilendirebilmek
  • Önceden tahmin etmediğiniz hata modlarını araştırabilmek

Örneğin bir müşteri saat 02:00’de “ödeme istekleri yavaş” dediğinde şu soruları yanıtlayabilmelisiniz:

  • Sadece /v2/checkout endpoint’i mi etkilendi?
  • Sorun belirli bir bölgede mi?
  • p99 gecikmesi ne zaman arttı?
  • Hangi downstream servis süreyi artırdı?
  • Aynı trace_id ile ilişkili loglarda hata var mı?

Gözlemlenebilirlik ve İzleme

İzleme ve gözlemlenebilirlik birlikte kullanılır, ancak aynı şey değildir.

İzleme, önceden tanımladığınız sinyalleri takip eder:

  • Hata oranı %5’i geçti mi?
  • p99 gecikmesi 1 saniyenin üzerine çıktı mı?
  • CPU kullanımı kritik seviyeye geldi mi?

Gözlemlenebilirlik ise sistemin davranışı hakkında yeni sorular sormanızı sağlar:

  • Neden yalnızca belirli müşteriler etkileniyor?
  • Neden yeni API sürümünde gecikme arttı?
  • Neden retry sayısı belirli bir bölgede yükseldi?

Kısa haliyle: İzleme “bir şey bozuldu” der. Gözlemlenebilirlik “neden bozuldu?” sorusunu yanıtlamanıza yardım eder. Uyarı tarafını daha ayrıntılı incelemek isterseniz, API izleme kılavuzumuz bu konuyu detaylandırır.

Yön İzleme Gözlemlenebilirlik
Yanıtlanan soru Bilinen bir sinyal aralık dışı mı? Sistem neden bu şekilde davranıyor?
Tanımlanma zamanı Önceden Araştırma sırasında
En iyi kullanım alanı Bilinen hata modları, SLO ihlalleri Yeni ve beklenmeyen sorunlar
Çıktı Uyarılar, durum panoları Sorgulanabilir metrik, log ve trace verisi

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

API gözlemlenebilirliği genellikle üç telemetri sinyali üzerine kurulur:

  1. Metrikler
  2. Günlükler
  3. İzler

OpenTelemetry bu sinyalleri standartlaştırır. Bugün izler, metrikler, günlükler ve bagajı destekler; olaylar ve profiller ise geliştirme aşamasındadır.

1. Metrikler

Metrikler, zaman içinde toplanan sayısal ölçümlerdir. API’ler için başlangıçta şu metrikleri izleyin:

  • İstek oranı
  • Hata oranı
  • Gecikme dağılımı
  • p95 ve p99 gecikme
  • Endpoint bazlı başarı/başarısızlık oranı

Ortalama gecikme tek başına yeterli değildir. Ortalama değer düşük görünürken p99 kullanıcıları çok yavaş yanıt alıyor olabilir.

Örnek metrik seti:

http_requests_total
http_request_duration_seconds_bucket
http_request_errors_total
http_requests_in_flight
Enter fullscreen mode Exit fullscreen mode

Metrikler dashboard ve uyarılar için idealdir. Ancak tek başlarına kök nedeni göstermezler. “p99 arttı” diyebilirler, ama “hangi istekler artırdı?” sorusunu yanıtlamak için log ve trace gerekir.

2. Günlükler

Günlükler, ayrık olayların zaman damgalı kayıtlarıdır. API gözlemlenebilirliği için serbest metin yerine yapılandırılmış JSON log kullanın.

Örnek:

{
  "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"
}
Enter fullscreen mode Exit fullscreen mode

Bu log yapısında kritik alan trace_id değeridir. Aynı istekle ilişkili logları, span’leri ve metrikleri birbirine bağlamanızı sağlar.

Pratik öneriler:

  • Her isteğe bir trace_id ekleyin.
  • method, path, status, duration_ms alanlarını standartlaştırın.
  • Kullanıcıya özel hassas verileri loglamayın.
  • Bölge, API sürümü ve ortam gibi debug için gerekli alanları ekleyin.
  • Log seviyelerini tutarlı kullanın: debug, info, warn, error.

3. İzler

Dağıtılmış izleme, bir isteğin servisler arasında nasıl ilerlediğini gösterir. Her adım bir span olarak kaydedilir ve tüm span’ler aynı trace_id değerini paylaşır.

Örneğin bir ödeme isteği şu akıştan geçebilir:

API Gateway
  -> Auth Service
  -> Checkout Service
  -> Payment Provider Adapter
  -> Inventory Service
Enter fullscreen mode Exit fullscreen mode

Trace çıktısı size şunu gösterir:

  • Hangi servis ne kadar sürdü?
  • Hangi downstream çağrı yavaşladı?
  • Hata hangi adımda oluştu?
  • Retry veya timeout nerede tetiklendi?

Metrik uyarısı gecikmeyi gösterir. Trace yavaş adımı bulur. Aynı trace_id ile filtrelenen loglar da ne olduğunu açıklar.

RED Yöntemi ve Altın Sinyaller

Her metriği takip etmeye çalışmak yerine API’ler için RED yöntemiyle başlayın.

RED şunları ifade eder:

  • Rate (Oran): Saniyedeki istek sayısı
  • Errors (Hatalar): Başarısız istek oranı
  • Duration (Süre): İstek gecikmesi, özellikle p95 ve p99 
Oran     = saniyedeki istek sayısı
Hatalar  = 5xx ve beklenmeyen 4xx yanıt oranı
Süre     = p95 ve p99 gecikme
Enter fullscreen mode Exit fullscreen mode

RED, API gateway, mikroservis ve servis mesh gibi istek odaklı sistemler için iyi bir başlangıçtır.

Altyapı tarafı için ayrıca USE yöntemini ekleyebilirsiniz:

  • Utilization: Kaynak kullanımı
  • Saturation: Doygunluk
  • Errors: Kaynak hataları

API için önerilen sıra:

  1. RED metrikleriyle başlayın.
  2. Endpoint bazlı ayırın.
  3. Kritik endpoint’ler için SLO tanımlayın.
  4. Altyapı sorunlarını görmek için USE metriklerini ekleyin.

SLI ve SLO: Sinyalleri Hedefe Bağlama

Metrikler, hedef olmadan sadece grafiktir. SLI ve SLO bu sinyalleri karar mekanizmasına dönüştürür.

SLI (Service Level Indicator), hizmet kalitesinin ölçülebilir göstergesidir.

Örnek SLI’lar:

  • Başarılı istek oranı
  • p95 gecikme
  • p99 gecikme
  • Kullanılabilirlik
  • Timeout oranı

SLO (Service Level Objective), bu göstergeler için hedef değerdir.

Örnek:

28 günlük pencerede isteklerin %99,9’u 300 ms altında tamamlanmalı.
Enter fullscreen mode Exit fullscreen mode

Başka bir örnek:

/v2/checkout endpoint’i için 5xx hata oranı 30 günlük pencerede %0,1’in altında kalmalı.
Enter fullscreen mode Exit fullscreen mode

SLO’lar ekip kararlarını netleştirir:

  • Yeni özellik geliştirmeye devam edebilir miyiz?
  • Güvenilirlik çalışmasına öncelik vermeli miyiz?
  • Son deploy hata bütçesini tüketti mi?

Araçlar: OpenTelemetry ve Arka Uçlar

Gözlemlenebilirlik araçlarını iki katmanda düşünün:

  1. Telemetriyi nasıl üretiyorsunuz?
  2. Telemetriyi nereye gönderiyorsunuz?

Telemetri üretimi için OpenTelemetry güçlü bir varsayılandır. OpenTelemetry, OpenTracing ve OpenCensus projelerinin birleşmesiyle oluşan CNCF projesidir. Satıcıdan bağımsızdır ve şu parçaları sağlar:

  • API’ler
  • Dil SDK’ları
  • Otomatik enstrümantasyon
  • Semantik konvansiyonlar
  • OTLP protokolü
  • OpenTelemetry Collector

Analiz ve depolama için farklı arka uçlar kullanabilirsiniz:

  • Prometheus + Grafana
  • Datadog
  • Honeycomb
  • Diğer log, metric ve trace platformları

Datadog kullanıyorsanız, Datadog API kılavuzumuz verileri programatik olarak nasıl itip çekeceğinizi gösterir.

OpenTelemetry’nin avantajı, bir kez enstrümantasyon yapıp arka ucu daha sonra değiştirebilmenizdir. Böylece satıcı bağımlılığını azaltırsınız.

Test ve Sentetik Kontroller Nereye Uyar?

Gözlemlenebilirlik yalnızca üretim ortamından gelen sinyallerle sınırlı değildir. CI testleri, sözleşme testleri ve sentetik kontroller de gözlemlenebilirlik verisidir.

Sola Kaydırma: Sözleşme Testleri ve CI

Kod üretime çıkmadan önce API sözleşmesine uyduğunu doğrulamalısınız.

CI içinde çalışan sözleşme testleri şunları yakalar:

  • Eksik alanlar
  • Yanlış status code
  • Bozulan response şeması
  • Geriye uyumsuz endpoint değişiklikleri
  • Ortam bazlı konfigürasyon sorunları

Her test çalıştırması da bir sinyaldir:

  • Hangi commit’te başarısız oldu?
  • Hangi ortamda başarısız oldu?
  • Hangi test senaryosu kırıldı?
  • Son başarılı çalıştırmadan sonra ne değişti?

Apidog CLI, test senaryolarını pipeline içinde çalıştırabilir. Node.js üzerine kuruludur ve Node v16 veya daha yenisini gerektirir.

npm install -g apidog-cli

# kurulumu doğrula
node -v && apidog -v
Enter fullscreen mode Exit fullscreen mode

Bir ortama karşı test senaryosu çalıştırmak için:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -r html,cli
Enter fullscreen mode Exit fullscreen mode

Burada:

  • -t: test senaryosu kimliği
  • -e: ortam kimliği
  • -r: rapor formatları (cli, html, json, junit)
  • --access-token: Apidog erişim token’ı

Veri odaklı test için CSV veya JSON dosyası kullanabilirsiniz:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t 637132 \
  -e 358171 \
  -r html,cli \
  -d ./data.csv
Enter fullscreen mode Exit fullscreen mode

Rapor özetini Apidog bulutuna yüklemek için:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t 637132 \
  -e 358171 \
  -r html,cli \
  --upload-report
Enter fullscreen mode Exit fullscreen mode

Kopyalayıp uyarlayabileceğiniz örnek pipeline için CI/CD kılavuzumuz için Apidog CLI yazısına veya tüm bayraklar için tam CLI referansına bakın.

Üretimde Sentetik İzleme

Sentetik izleme, canlı API’nize dışarıdan düzenli aralıklarla istek gönderir. Kullanıcı trafiği beklemeden sorunları yakalamanızı sağlar.

Basit bir örnek:

Her 5 dakikada bir:
GET /health
Beklenen status: 200
Beklenen süre: < 300 ms
Enter fullscreen mode Exit fullscreen mode

Daha gerçekçi bir senaryo:

1. POST /login
2. GET /cart
3. POST /checkout
4. GET /orders/{id}
Enter fullscreen mode Exit fullscreen mode

Bu kontrollerden şu sinyalleri elde edebilirsiniz:

  • Uptime
  • Bölgesel gecikme
  • Endpoint bazlı hata oranı
  • Çok adımlı akış başarısı
  • Üretimde regresyon

Temel bir API sağlık kontrolü en basit formdur. Daha kapsamlı sentetik izleme, bunu giriş ve ödeme gibi çok adımlı akışlara genişletir.

Araç seçimi için sentetik test araçları derlemesine ve üretim izleme platformları için API izleme araçları listesine bakabilirsiniz.

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

Apidog, Planlanmış Görevler ile test senaryolarını belirli aralıklarla çalıştırarak sentetik sinyaller üretebilir. Bu özellik, Testler modülünde Planlanmış Görevler altında bulunur.

Kullanım modeli:

  1. Bir veya daha fazla test senaryosu seçin.
  2. Çalışma zamanını tanımlayın.
  3. Bildirim kuralını belirleyin.
  4. Sonuçları düzenli olarak takip edin.

Planlanmış Görevler ile şu kontrolleri otomatikleştirebilirsiniz:

  • Her 6 saatte bir checkout akışı
  • Her gece regresyon testi
  • Haftalık sözleşme testi
  • Kritik endpoint’ler için üretim smoke test’i

Bilmeniz gereken noktalar:

  • Planlanmış Görevler şu anda Beta aşamasındadır.
  • Yapılandırılmış kendi kendine barındırılan bir Runner gerektirir.
  • “Çalıştıranlar” seçenekleri bugün kendi kendine barındırılan Runner’ı listeler; Apidog Cloud’un yakında geleceği belirtilmektedir.
  • Çalıştırma sayıları abonelik planınıza bağlıdır.

Bir görev oluştururken şunları seçersiniz:

  • Test Senaryoları: Çalıştırılacak senaryo veya senaryolar
  • Çalışma Modu: Örneğin her Pazar 23:00 veya her 6 saatte bir
  • Bildirim: Her çalıştırmadan sonra veya yalnızca hata durumunda

Uygulamalı yapılandırma için Apidog Planlanmış Görevler kılavuzumuza bakın.

Bu yaklaşımın değeri, aynı API senaryolarını hem geliştirme hem üretim döngüsünde kullanabilmenizdir. API’yi tasarlar, test eder ve aynı senaryoları düzenli çalıştırarak geçme/kalma ve gecikme sinyalleri üretirsiniz.

Gözlemlenebilir Bir API İçin Uygulama Planı

Sıfırdan başlıyorsanız aşağıdaki sırayla ilerleyin.

1. Yapılandırılmış Log Ekleyin

Her istekte standart log alanları üretin:

{
  "timestamp": "2026-06-22T02:14:09Z",
  "level": "info",
  "trace_id": "8f3a1c9d2e7b4a16",
  "method": "GET",
  "path": "/v1/users",
  "status": 200,
  "duration_ms": 123,
  "environment": "production"
}
Enter fullscreen mode Exit fullscreen mode

Minimum alanlar:

  • timestamp
  • level
  • trace_id
  • method
  • path
  • status
  • duration_ms
  • environment

2. Trace ID’yi Her Yere Taşıyın

Trace ID şu yerlerde görünmelidir:

  • API gateway logları
  • Uygulama logları
  • Downstream servis çağrıları
  • Hata mesajları
  • Trace span’leri

Böylece tek bir istek için tüm akışı takip edebilirsiniz.

3. OpenTelemetry ile Enstrümantasyon Yapın

OpenTelemetry kullanarak metrik, log ve trace bağlamını standartlaştırın. Önce kritik servislerden başlayın:

  • API gateway
  • Auth servisi
  • Checkout/payment servisi
  • Kullanıcıya doğrudan yanıt veren backend servisleri

4. RED Dashboard Oluşturun

İlk dashboard şu panelleri içermeli:

  • Toplam istek oranı
  • Endpoint bazlı istek oranı
  • 5xx hata oranı
  • Beklenmeyen 4xx oranı
  • p95 gecikme
  • p99 gecikme
  • En yavaş endpoint’ler
  • En çok hata veren endpoint’ler

5. SLI ve SLO Tanımlayın

Her endpoint için SLO yazmaya çalışmayın. Önce kullanıcı açısından kritik akışlardan başlayın:

  • Login
  • Checkout
  • Payment
  • Search
  • Order creation

Örnek:

Checkout API için:
28 günlük pencerede isteklerin %99,9’u 500 ms altında tamamlanmalı.
5xx hata oranı %0,1’in altında kalmalı.
Enter fullscreen mode Exit fullscreen mode

6. CI’da Sözleşme Testleri Çalıştırın

Her pull request veya merge sonrası API sözleşmesini doğrulayın:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t 637132 \
  -e 358171 \
  -r junit,cli
Enter fullscreen mode Exit fullscreen mode

CI sisteminiz JUnit raporunu okuyabiliyorsa, test sonuçlarını build sonucu olarak gösterebilirsiniz.

7. Üretimde Sentetik Kontroller Çalıştırın

Kritik akışlar için planlanmış kontroller ekleyin:

/login       -> 200
/cart        -> 200
/checkout    -> 201
/orders/{id} -> 200
Enter fullscreen mode Exit fullscreen mode

Her kontrol için şunları kaydedin:

  • Başarı/başarısızlık
  • Toplam süre
  • Hangi adımda hata oluştuğu
  • Çalıştırma zamanı
  • Ortam
  • Bölge

Sıkça Sorulan Sorular

API gözlemlenebilirliği nedir?

API gözlemlenebilirliği, bir API’nin metrikler, günlükler ve izler gibi telemetri verilerinden dahili durumunu anlayabilme yeteneğidir. Amaç, yeni enstrümantasyon eklemeden beklenmeyen sorunları araştırabilmektir.

API gözlemlenebilirliği ve izleme arasındaki fark nedir?

İzleme, önceden tanımlanmış sinyalleri takip eder ve eşik aşıldığında uyarı verir. Gözlemlenebilirlik ise sistem davranışı hakkında yeni sorular sormanızı sağlar. İzleme sorunu bildirir; gözlemlenebilirlik nedeni bulmanıza yardım eder.

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

Üç temel direk metrikler, günlükler ve izlerdir. Metrikler sayısal ölçümlerdir, günlükler olay kayıtlarıdır, izler ise bir isteğin servisler arasındaki yolunu gösterir.

Bir API nasıl gözlemlenebilir hale getirilir?

Önce yapılandırılmış log ve trace_id ekleyin. Ardından OpenTelemetry ile metrik, log ve trace bağlamını standartlaştırın. RED metriklerini izleyin, SLI/SLO tanımlayın, CI’da sözleşme testleri çalıştırın ve üretimde sentetik kontroller ekleyin.

Gözlemlenebilirlik için OpenTelemetry gerekli mi?

Hayır. Gözlemlenebilirlik bir araç değil, sistem özelliğidir. Ancak OpenTelemetry satıcıdan bağımsız bir standart olduğu için güçlü bir varsayılandır. Bir kez enstrümantasyon yapıp Prometheus, Datadog veya Honeycomb gibi farklı arka uçlara veri gönderebilirsiniz.

Top comments (0)