This page is also available in English. Read in English →
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.
- Serilog: Serilog 3.1 ve üstü, etkin bir
Activityvarsa (ASP.NET Core isteği, OpenTelemetry ile izlenen iş) trace ve span kimliğini her olaya ekler; güncelSerilog.Sinks.Seqbunları@trve@spolarak gönderir. Ek ayar gerekmez. - OpenTelemetry: log kaydının
traceIdvespanIdalanları okunur (aşağıya bakın). - Kendi korelasyon kimliğiniz: tracing kullanmıyorsanız istek kimliğinizi
traceIdalanında gönderebilirsiniz: en fazla 64 karakter, boşluksuz.
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:
- 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… bulunamadiileKullanici 77 icin sepet a1b2… bulunamadiaynı imzayı üretir. - İstisna tipi ayrıştırılır.
System.NullReferenceException: mesajbiç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, 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 }
- Oturum başladığında
init, yakalanmamış bir hata (çökme) olduğundacrashedgönderin. Aynı oturumun aynı durumu ikinci kez sayılmaz (countedbunu gösterir); ağ yeniden denemesi oranı bozmaz. id: 8–64 karakter, harf, rakam,-,_(UUID önerilir).releasezorunludur;environmentverilmezse projenin varsayılanı. Bir istekte en fazla 100 sinyal.- Sinyaller olay kotasından düşmez; ingest hız sınırına tabidir. Publishable anahtarla da gönderilebilir (yalnızca izinli alan adlarından).
- Sayılar en geç bir dakika içinde sürüm ekranına yansır.
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.