Ingest formatları

Errorbird beş yazma ucu sunar. Hepsi aynı anahtar doğrulamasını (X-API-KEY başlığı; Seq sink'i için X-Seq-ApiKey de kabul edilir), aynı kotayı ve aynı PII temizlemesini kullanır; farkları yalnızca gövde biçimidir.

Uç Gövde Kullanım
POST /api/v1/ingest Tek CLEF olayı (JSON) Elle deneme, düşük hacim
POST /api/v1/ingest/batch NDJSON (satır başına bir olay), gzip destekli Üretim; kendi toplu gönderiminiz
POST /api/v1/ingest/api/events/raw Seq'in ham CLEF biçimi (satır başına bir olay) Serilog.Sinks.Seq; sink bu adresi kendisi kurar
POST /api/v1/ingest/otlp OTLP/HTTP JSON logs OpenTelemetry Collector
POST /api/v1/ingest/browser Tarayıcı hatası (JSON) @errorbird/browser; bkz. Tarayıcı hataları

Hepsi başarıda HTTP 202 döner. Yanıtın anlamı "kuyruğa alındı"dır. Yazma işlemini isteğin içinde beklemek, uygulamanızın yanıt süresini Errorbird'ün veritabanı hızına bağlardı; kabul kriteri de bu yüzden "50 ms içinde 202"dir.

CLEF alanları

CLEF (Compact Log Event Format), Seq'in kullandığı biçimdir. Errorbird şu alanları tanır:

Alan Anlamı
@t Zaman damgası (ISO 8601). Yoksa sunucunun aldığı an kullanılır.
@l Seviye: Verbose, Debug, Information, Warning, Error, Fatal
@mt Mesaj şablonu (Kullanici {UserId} bulunamadi)
@m Şablonu doldurulmuş mesaj
@x İstisna metni / stack trace
@r Şablonun render edilmiş değerleri
@i Olay tipi kimliği
@tr Trace kimliği (W3C biçiminde 32 onaltılık karakter). traceId adıyla da gönderilebilir. Bkz. İstek bazında loglar
@sp Span kimliği. spanId adıyla da gönderilebilir.
breadcrumbs Hatadan önceki adımlar: { timestamp, category, message, level, data } nesnelerinden dizi. Tarayıcı SDK'sı kendisi doldurur; sunucu SDK'nız da gönderebilir. Bkz. Tarayıcı hataları

Şablonlu alanlar (UserId gibi) Metadata içinde jsonb olarak saklanır ve aranabilir. Errorbird ayrıca release, environment, serverName ve stackTrace alanlarını üst düzey alan olarak okur — "bu hata hangi sürümle geldi?" sorusunun cevabı budur.

Serilog'dan geçiş

Mevcut Serilog.Sinks.Seq yapılandırmanızda kod değiştirmeden yalnızca adres ve anahtar değişir:

Log.Logger = new LoggerConfiguration()
    .WriteTo.Seq(
        serverUrl: "https://api.errorbird.com/api/v1/ingest",
        apiKey: "ebrd_secret_…")
    .CreateLogger();

Sink, verilen adrese api/events/raw ekleyip olayları satır başına bir CLEF olarak toplu gönderir ve anahtarı X-Seq-ApiKey başlığında taşır; Errorbird ikisini de tanır. İstemci tarafı tamponlama ve yeniden deneme sink'in kendi davranışıdır ve olduğu gibi çalışır.

İstek bazında loglar (trace kimliği)

Bir HTTP isteği ya da arka plan işi boyunca yazılan loglar aynı trace kimliğini taşır. Errorbird bu kimliği ayrı bir alanda saklar; panelde bir logu açıp Bu isteğin tüm logları bağlantısına tıkladığınızda o isteğin bütün logları, eskiden yeniye ve ilk logdan bu yana geçen süreyle (+120 ms) listelenir. Hata detayındaki ham olaylarda da aynı bağlantı vardır: hatadan hemen önce o istekte ne olduğu tek ekranda görülür.

Kimlikler büyük/küçük harf duyarsız eşleşir. Boş, boşluk içeren, 64 karakteri aşan ya da tamamı sıfır olan kimlik yok sayılır; olay yine kaydedilir, yalnızca ilişkilendirilmez. Aynı görünüm API'den de alınır: GET /api/v1/projects/{id}/events?traceId=… (bkz. Okuma API'si).

Toplu gönderim

gzip -c olaylar.ndjson | curl -X POST https://api.errorbird.com/api/v1/ingest/batch \
  -H "X-API-KEY: ebrd_secret_…" \
  -H "content-type: application/x-ndjson" \
  -H "content-encoding: gzip" \
  --data-binary @-

Tek istekte en fazla 5.000 olay gönderilebilir; daha büyük gövde 400 döner. Bu sınır bellek koruması içindir: tek bir isteğin sunucuda sınırsız tampon açması, ingest hattını tek bir istemcinin insafına bırakırdı.

OTLP

curl -X POST https://api.errorbird.com/api/v1/ingest/otlp \
  -H "X-API-KEY: ebrd_secret_…" \
  -H "content-type: application/json" \
  -d @otlp-logs.json

resourceLogs[].scopeLogs[].logRecords[] yapısı okunur; severityText seviyeye, body.stringValue mesaja, attributes ise Metadata'ya çevrilir. Kaydın traceId ve spanId alanları (onaltılık) trace kimliği olarak saklanır; service.version sürüme, deployment.environment ortama, host.name (yoksa service.name) sunucu adına eşlenir.

Hata kodları

Kod Anlamı Ne yapmalı
401 Anahtar geçersiz veya iptal edilmiş Anahtarı kontrol edin
400 Gövde çözümlenemedi veya batch sınırı aşıldı Gövdeyi düzeltin
429 Aylık kota doldu ya da anlık hız sınırı aşıldı Retry-After başlığını bekleyin
503 Devre kesici açık (kuyruk yazılamıyor) İstemci tamponunda tutup yeniden deneyin

Hız sınırı yazma için saniyede 2.000 olaydır (token bucket, anahtar başına) ve okuma havuzundan ayrıdır: okuma trafiği yazmayı, yazma trafiği okumayı yavaşlatmaz.

429 ve 503 durumlarında olayı atmayın. Her iki durum da geçicidir; istemci tarafında tamponlayıp üstel geri çekilme (exponential backoff) ile yeniden gönderin.

Fingerprint nasıl hesaplanır?

Yalnızca Error ve Fatal seviyesindeki olaylar Issue açar. Debug, Information ve Warning olayları Loglar sayfasında aranabilir, alarm kurallarına girer ama Hatalar listesine düşmez; aynı imzayı taşısalar bile bir Issue'nun sayacına eklenmez.

Aynı kök hatanın tek bir Issue altında toplanması, mesajın ve stack trace'in normalize edilmiş hâlinden üretilen SHA-256 özetine dayanır:

  1. Mesajdaki değişkenler yer tutucuya çevrilir. GUID, e-posta, URL, dosya yolu, zaman damgası, IP, onaltılık değer, tırnak içi metin ve sayılar sırayla değiştirilir. Kullanici 4821 icin sepet 9f3c… bulunamadi ile Kullanici 77 icin sepet a1b2… bulunamadi aynı imzayı üretir.
  2. İstisna tipi ayrıştırılır. System.NullReferenceException: mesaj biçimindeki ön ek ayrılır ve imzaya ayrı bir bileşen olarak girer.
  3. İlk 5 stack frame alınır. Daha derin çerçeveler çağıran koda göre değişir ve aynı hatayı farklı gruplara dağıtırdı.
  4. Satır numaraları düşürülür, yollar makineden bağımsızlaştırılır. Aksi hâlde tek satırlık bir düzenleme veya farklı bir derleme makinesi yeni bir Issue üretirdi.

.NET, Node.js, Java ve tarayıcı (Chrome/Edge ile Firefox/Safari) stack trace biçimleri ayrı ayrı tanınır. Tarayıcı çerçevelerinde alan adı ve sorgu dizesi de düşürülür: aynı paket CDN'den ya da ?v=3 ile sunulduğunda aynı imza çıkar. Küçültülmüş JavaScript'te imza, source map ile orijinal koda çevrilmiş stack'ten hesaplanır. Aynı kök hata farklı satır numarası ve farklı değişken değerleriyle 500 kez gönderildiğinde LogEvents'e 500 ham satır yazılır ama Issues'ta tek satır oluşur ve totalCount 500 olur.

Oturum sinyalleri

Sürüm sağlığındaki crash-free oranı oturum sinyallerinden hesaplanır. Tarayıcı SDK'sı bunları kendisi gönderir; mobil ya da masaüstü uygulamanız için doğrudan çağırabilirsiniz:

curl -X POST https://api.errorbird.com/api/v1/ingest/sessions \
  -H "X-API-KEY: ebrd_secret_…" -H "Content-Type: application/json" \
  -d '{ "release": "[email protected]", "environment": "production",
        "sessions": [ { "id": "6f1c2a9e-…", "status": "init" },
                      { "id": "0b7d4e11-…", "status": "crashed" } ] }'
# 202 { "counted": 2 }

Kota ve saklama

Kota aylıktır, plana bağlıdır ve organizasyonun bütün projeleri için ortaktır (Hobby 10.000, Pro 250.000, Business 2.000.000, Agency 10.000.000 olay). Kota dolduğunda ingest 429 döner ve sayaç ay başında sıfırlanır. Panelde ve okuma API'sinde görünen "bu ay" kullanımı da organizasyonun toplamıdır.

Saklama süresi de plana bağlıdır (7 / 15 / 30 / 90+ gün). Süresi dolan veri TimescaleDB'de drop_chunks ile chunk seviyesinde düşürülür; satır satır silme yapılmaz.