Sipariş Gözlemlenebilirliği: Log, Metrik, Alarm ve Mutabakat

Sipariş sisteminde yalnız hata olduğunda log dosyasına bakmak yeterli değildir. Teknik ekip; kaç siparişin gönderim beklediğini, API çağrılarının ne kadar sürdüğünü, hangi servislerde hata oranının arttığını ve hangi kayıtların uzun süre Pending kaldığını gerçek zamanlı görebilmelidir. Bu yaklaşım log, metrik, iz ve alarm bileşenlerinin birlikte kullanıldığı gözlemlenebilirlik sistemidir.

Bu rehber, RoketBayim sipariş entegrasyonunda hassas verileri açığa çıkarmadan yapılandırılmış loglama, operasyon metrikleri, alarm eşikleri ve günlük mutabakat tasarlamayı açıklar.

Gözlemlenebilirliğin üç katmanı

Log

Tek bir sipariş veya API çağrısında ne olduğunu ayrıntılı gösterir. Yerel sipariş ID, order ID, action, durum geçişi ve hata sınıfı gibi alanlar içerir.

Metrik

Sistemin genel sağlığını sayısal olarak izler. Dakika başına sipariş, başarı oranı, kuyruk gecikmesi ve durum dağılımı örnektir.

İz veya correlation

Kullanıcı isteğinden kuyruk mesajına, API çağrısından durum worker’ına kadar aynı işlemi takip etmeyi sağlar. correlation_id bütün kayıtlarda taşınmalıdır.

Yapılandırılmış log kullanın

Serbest metin loglar arama ve alarm üretmeyi zorlaştırır. Her olayı JSON gibi yapılandırılmış alanlarla yazın.

{
  "event": "provider_order_submitted",
  "local_order_id": "L-1042",
  "provider_order_id": 23501,
  "action": "add",
  "service_id": 1,
  "technical_status": "tracking",
  "duration_ms": 420,
  "correlation_id": "c-8f20",
  "timestamp": "2026-08-13T10:00:00Z"
}

Alan adlarını tüm servislerde tutarlı kullanın. Bir uygulamanın orderId, diğerinin provider_id yazması sorguları zorlaştırır.

Loglanması gereken sipariş olayları

• Yerel sipariş oluşturuldu ve doğrulandı
• Gönderim sahipliği alındı
• API add veya add_bulk isteği başladı ve bitti
• Order ID alındı
• Kesin error veya belirsiz zaman aşımı oluştu
• Provider status değişti
• Partial, Completed veya Canceled terminal sonucu alındı
• Refill veya cancel talebi gönderildi
• Retry, review veya dead-letter kuyruğuna geçildi
• Operasyon ekibi manuel işlem yaptı

Hassas verileri loglamayın

API anahtarı, parola, oturum belirteci ve ödeme bilgisi loglarda bulunmamalıdır. URL’ler de kişisel veya kampanyaya özel bilgi içerebilir; tam link yerine güvenli maskeleme veya hash düşünülebilir. Destek için hedef gerekli ise erişim yetkisi sınırlı ayrı alanda saklayın.

Temel teknik metrikler

• order_ingest_total: kabul edilen yerel sipariş sayısı
• provider_submit_total: API’ye gönderilen sipariş sayısı
• provider_submit_success_total: order ID dönen işlem sayısı
• provider_submit_error_total: error yanıtları
• provider_request_duration: API yanıt süresi dağılımı
• order_queue_age: en eski gönderim bekleyen işin yaşı
• order_unknown_total: sonucu belirsiz sipariş sayısı
• order_status_count: Pending, Processing ve terminal durum dağılımı
• order_tracking_lag: son status sorgusundan geçen süre

İş sonucu metrikleri

Teknik başarı, siparişin tamamlandığı anlamına gelmez. add isteğinin order ID döndürmesi yalnız oluşturma başarısıdır. Aşağıdaki iş metriklerini ayrıca izleyin:

• Completed oranı
• Partial oranı ve ortalama remains
• Canceled oranı
• Ortalama başlangıç süresi
• Ortalama terminal sonuca ulaşma süresi
• Servis bazında refill talep ve ret oranı
• Servis bazında destek talebi oranı

Bu metrikleri service_id ve kategori gibi düşük çeşitlilikli etiketlerle bölün. Link veya order ID gibi her kayıtta farklı değerleri metrik etiketi yapmayın; cardinality patlamasına yol açar.

Durum değişikliği metriği

Yalnız mevcut durum sayısı bazı sorunları gizler. Durum geçiş sayısını da ölçün:

order_status_transition_total{
  from="Pending",
  to="Processing",
  service_id="1"
}

Pending’den Processing’e geçiş aniden düşerse servis başlangıç sorunu olabilir. Processing’den Partial’a geçiş artarsa servis veya platform davranışı incelenmelidir.

Alarm tasarımı

Semptom alarmı

Kullanıcı etkisini doğrudan gösterir. Örneğin gönderim kuyruğunun yaşı, order ID alma oranının düşmesi veya uzun Pending siparişlerin artması.

Neden alarmı

API bağlantı hatası, worker çökmesi veya veritabanı gecikmesi gibi teknik nedeni gösterir. Semptom ve neden alarmını birlikte kullanmak hızlı teşhis sağlar.

Örnek alarmlar

• Son 10 dakikada submit başarı oranı normal tabanın belirgin altına düştü
• En eski order-submit mesajı kabul edilen yaş sınırını aştı
• unknown sipariş sayısı sıfırdan büyük ve artıyor
• Aktif siparişlerin önemli bölümü uzun süredir sorgulanmadı
• Belirli serviste Partial veya Canceled oranı aniden yükseldi
• API yanıt süresi normal yüzdelik değerlerin üzerine çıktı
• DLQ büyüklüğü artıyor

Sabit eşikleri servis davranışı ve trafik hacmine göre belirleyin. Düşük trafikte yüzde oranı tek siparişle yanıltıcı olabilir; minimum örnek sayısı kullanın.

Alarm yorgunluğunu önleme

Her hata logu için bildirim göndermek teknik ekibi duyarsızlaştırır. Alarmlar eyleme dönük olmalı, sorumlu ekip ve ilk kontrol adımını içermelidir. Aynı kök nedenden çıkan yüzlerce sipariş alarmını tek olay altında gruplayın.

Uyarı, kritik ve bilgi seviyelerini ayırın. Kullanıcı etkisi olmayan kısa süreli dalgalanma bilgi panelinde kalabilir; order gönderiminin durması kritik alarmdır.

Dashboard tasarımı

Tek bir panelde aşağıdaki bölümler faydalıdır:

1. Gelen, gönderilen ve başarıyla order ID alan sipariş hacmi
2. API yanıt süresi ve error oranı
3. Kuyruk yaşları ve worker çalışma durumu
4. Pending, Processing, Completed, Partial ve Canceled dağılımı
5. En çok hata üreten servisler
6. Unknown, review ve DLQ kayıtları
7. Bakiye ve yetersiz bakiye hata trendi

Dashboard yalnız toplam sayıları değil, önceki dönem karşılaştırmasını da göstermelidir. Normal trafik değişimiyle anomali böyle ayırt edilir.

Correlation ID kullanımı

Kullanıcı sipariş isteği geldiğinde correlation_id üretin. Bu değeri HTTP logu, yerel sipariş, kuyruk mesajı, API çağrısı ve durum worker olaylarında taşıyın. Destek ekibi order ID’den correlation ID’ye, teknik ekip de bütün zaman çizelgesine ulaşabilmelidir.

Correlation ID güvenlik belirteci değildir; tahmin edilebilir olsa bile yetki sağlamamalıdır. Kullanıcıya gösterilecekse yalnız kendi sipariş kayıtlarında kullanılmalıdır.

Dağıtık iz

Mikroservis mimarisinde sipariş doğrulama, fiyatlama, kuyruk ve provider adapter farklı servislerde çalışabilir. Trace, isteğin bu bileşenlerde harcadığı zamanı gösterir. API çağrısını ayrı span olarak işaretleyin fakat hassas istek gövdesini span attribute olarak yazmayın.

Günlük mutabakat

Gözlemlenebilirlik yalnız gerçek zamanlı alarm değildir. Her gün yerel sipariş kayıtlarıyla provider order ID, terminal durum ve ücret alanlarını karşılaştıran mutabakat işi çalıştırın.

• provider_order_id olmayan tracking kayıtları
• Terminal provider status olup yerelde açık kalan siparişler
• Uzun süredir status sorgulanmayan aktif order ID’ler
• Aynı yerel siparişe bağlı birden fazla provider order ID
• Yanıt para birimi veya ücret alanı boş kayıtlar
• Batch index eşlemesi tamamlanmamış satırlar

Mutabakat farklarını otomatik düzeltmeden önce türüne göre sınıflandırın. Bazı kayıtlar gecikmiş worker tarafından güncellenebilir; bazıları manuel inceleme gerektirir.

Runbook hazırlama

Her kritik alarm için kısa runbook oluşturun. Örneğin submit başarı oranı düştüğünde:

Log saklama ve erişim

Log saklama süresini operasyon ve güvenlik gereksinimine göre belirleyin. Her personel tüm ham loglara erişmemelidir. Destek ekibi order ID ve durum zaman çizelgesini görebilirken API anahtarı ve altyapı ayrıntıları hiçbir kullanıcıya gösterilmemelidir.

Silme ve maskeleme politikaları yedek ve arşiv sistemlerini de kapsamalıdır.

Test ve doğrulama

• Başarılı siparişte tüm beklenen olayların oluşması
• Kesin error ve zaman aşımının farklı etiketlenmesi
• API anahtarının hiçbir logda bulunmaması
• Correlation ID’nin kuyruk ve worker boyunca taşınması
• Alarmın test metriğiyle tetiklenmesi ve kapanması
• Terminal durumun aktif sayaçtan çıkarılması
• Mutabakat işinin kasıtlı tutarsız kaydı bulması

Canlıya geçiş sırası

Önce yapılandırılmış log ve correlation ID ekleyin. Ardından düşük cardinality metriklerini, dashboard’u ve yalnız en kritik alarmları açın. Gerçek trafik tabanını gördükten sonra eşikleri iyileştirin. Son aşamada günlük mutabakat ve servis bazlı kalite raporlarını ekleyin.

SLO ve hata bütçesi

Teknik ekip için ölçülebilir hizmet hedefleri belirleyin. Örneğin doğrulanmış yerel siparişlerin belirli bir yüzdesinin kabul edilen süre içinde API’ye gönderilmesi veya aktif siparişlerin belirli süre içinde yeniden sorgulanması hedeflenebilir. Bu hedefler sağlayıcının teslimat garantisi değil, kendi entegrasyonunuzun performansıdır.

Hata bütçesi, kabul edilen başarısızlık payını gösterir. Bütçe hızlı tükeniyorsa yeni özellik yayını yavaşlatılıp güvenilirlik çalışmasına öncelik verilir.

Servis seviyesi ile sağlayıcı sonucunu ayırın

API çağrısının başarılı olması Completed sipariş anlamına gelmez. Dashboard’da “oluşturma teknik başarısı”, “terminal tamamlanma oranı” ve “Partial/Canceled sonucu” ayrı grafiklerde yer almalıdır. Aksi hâlde teknik entegrasyon sorunu ile servis davranışı birbirine karışır.

Olay yönetimi

Kritik alarmda bir olay sorumlusu belirleyin. Etkilenen zaman aralığı, servisler, sipariş sayısı ve kullanıcı etkisi ortak olay kaydında tutulur. Müdahale sırasında belirsiz add isteklerini otomatik retry etmemek gibi güvenlik kuralları korunmalıdır.

Olay bittikten sonra zaman çizelgesi, kök neden, kullanıcı etkisi ve kalıcı düzeltme yazılır. Amaç kişiyi suçlamak değil aynı sınıf hatanın tekrarını azaltmaktır.

Destek ekibi görünümü

Destek personeli order ID aradığında teknik durum, provider status, son sorgu zamanı, son hata sınıfı ve olay geçmişini görebilmelidir. Ham stack trace veya API anahtarı gösterilmemelidir. “Yeniden gönder” gibi riskli işlem yerine inceleme talebi oluşturulmalıdır.

Veri doğruluğu alarmları

• Provider order ID bulunup service veya link kaydı boşsa
• Completed durumda remains sıfırdan büyükse
• currency veya charge beklenmeyen biçimde yoksa
• Son status zamanı sipariş oluşturma zamanından eskiyse
• Bir order ID birden fazla müşteriye bağlanmışsa

Bu alarmlar her zaman sağlayıcı hatası değildir; yerel veri yazma veya eşleme problemi olabilir.

Sentetik kontrol

Gerçek sipariş oluşturmadan services ve balance gibi düşük riskli sorgularla bağlantı, JSON ayrıştırma ve kimlik doğrulama yolunu düzenli kontrol edebilirsiniz. Sentetik kontrol gerçek kullanıcı trafiğinden bağımsız erken uyarı sağlar. Gerçek add çağrısını sentetik test olarak kullanmak bakiye ve sipariş etkisi yaratacağı için uygun değildir.

Kapasite planlama

Yoğun saatlerde ingest hızı, worker tüketim hızı ve status polling yükünü karşılaştırın. Kuyruk yaşı düzenli artıyorsa yalnız daha fazla worker eklemek yerine API yanıt süresi, veritabanı kilidi ve batch stratejisini inceleyin.

Yayın sonrası doğrulama

Yeni entegrasyon sürümü küçük trafik yüzdesiyle açıldığında eski ve yeni sürümün submit başarı oranı, unknown kayıtları, API yanıt süresi ve mükerrer koruma sinyalleri karşılaştırılmalıdır. Hata bütçesi hızlı tükenirse otomatik geri alma veya trafik durdurma planı bulunmalıdır.

Dağıtım etiketi her log ve metriğe düşük cardinality alan olarak eklenebilir. Böylece sorun yalnız yeni sürümde mi görülüyor anlaşılır. Geri alma sonrasında kuyrukta kalan mesajların şema uyumluluğu kontrol edilmelidir.

İş ve teknik ekip ortak dili

Dashboard terimleri destek ekranıyla uyumlu olmalıdır. “submit failed”, “provider Pending” ve “unknown result” birbirinden ayrılırsa ekipler aynı olayı farklı yorumlamaz. Her metriğin tanımı ve sahibi veri sözlüğünde tutulmalıdır.