Ingest formatları

Errorbird üç yazma ucu sunar. Üçü de aynı X-API-KEY doğrulamasını, 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; Serilog/Seq sink'leri
`POST /api/v1/ingest/otlp`	OTLP/HTTP JSON logs	OpenTelemetry Collector

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

Ş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, olayları NDJSON olarak toplu gönderir; Errorbird de batch ucunu bu biçimde kabul eder. İstemci tarafı tamponlama ve yeniden deneme sink'in kendi davranışıdır ve olduğu gibi çalışır.

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.

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?

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:

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.
İ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.
İ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ı.
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 ve Java stack trace biçimleri ayrı ayrı tanını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.

Kota ve saklama

Kota aylıktır ve plana bağlıdır (Hobby 5.000, Pro 100.000, Business 1.000.000 olay). Kota dolduğunda ingest 429 döner ve sayaç ay başında sıfırlanır.

Saklama süresi de plana bağlıdır (3 / 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.