This page is also available in English. Read in English → Kapat

Tarayıcı hataları ve source map

Ön yüzünüzde oluşan JavaScript hataları @errorbird/browser paketiyle toplanır. Küçültülmüş (minified) koddan gelen stack trace, derleme hattınızdan yüklediğiniz source map'lerle sunucuda orijinal koda çevrilir:

RangeError: Geçersiz tutar: -5                RangeError: Geçersiz tutar: -5
    at n (…/app.4f3c.js:1:34)          →          at formatPrice (src/checkout.ts:3:11)
    at …/app.4f3c.js:1:126                         at renderCart (src/checkout.ts:9:30)
    at e (…/app.4f3c.js:1:119)                     at renderCart (src/checkout.ts:9:16)

Gruplama da çevrilmiş metinden yapılır. Küçültücü her derlemede fonksiyonlara başka adlar verir (n, e, q…) ve sütunları kaydırır; imza bunlardan hesaplansaydı her deploy, var olan her hatayı yeni bir Issue olarak açardı.

Kurulum

npm install @errorbird/browser

Uygulamanızın girişinde, diğer kodlardan önce:

import { init } from '@errorbird/browser'

init({
  key: 'ebrd_pub_…',                       // publishable anahtar
  release: import.meta.env.VITE_RELEASE,   // ör. "[email protected]" ya da commit SHA
  environment: 'production',
})

Bu kadarı yakalanmamış hataları (window.onerror) ve yakalanmamış promise reddedilmelerini (unhandledrejection) toplar. Hata gönderimi sayfayı hiçbir koşulda bozmaz: ağ hatası yutulur, SDK'nın kendi hatası raporlanmaz, sunucu tarafı render'da (window yokken) çağrılar etkisizdir.

Anahtar. Yalnızca publishable anahtar kullanın; istek, anahtarın izinli alan adı listesindeki bir origin'den gelmelidir. Secret anahtar derlenmiş pakete girerse proje adına yazma yetkisi herkese açık olur.

Elle gönderim

import { captureException, captureMessage, setTag } from '@errorbird/browser'

try {
  await odemeAl()
} catch (error) {
  captureException(error, { tags: { adim: 'odeme' } })
  throw error
}

setTag('kiraci', 'acme')
captureMessage('Ödeme sağlayıcısı yavaş yanıt verdi', 'Warning')

React'te bir error boundary'nin componentDidCatch metodunda captureException(error) çağırmanız yeterlidir.

Seçenekler

Gürültüye karşı korumalar: aynı hata 60 saniye içinde yalnızca bir kez gönderilir. Bilgi taşımayan Script error. (CORS başlığı olmadan başka kökenden yüklenen script'in hatası; tarayıcı ayrıntıyı gizler) ve ResizeObserver loop uyarıları varsayılan olarak atlanır. Sayfa adresi sorgu dizesi olmadan gönderilir: ?token=… gibi parametreler çoğu zaman kişisel veri ya da gizli bilgi taşır.

Source map yükleme

Source map'ler derleme hattından (CI) secret anahtarla yüklenir:

PUT /api/v1/sourcemaps?release=<sürüm>&file=<küçültülmüş dosya adı>
X-API-KEY: ebrd_secret_…
Content-Type: application/json

<haritanın kendisi>

file, stack trace'te görünen dosyanın adıdır (app.4f3c.js); yol ve sorgu dizesi dikkate alınmaz, .map eki verilirse atılır. Aynı sürüm ve dosya için yeniden yükleme eskisinin yerine geçer (worker'lar çözülmüş haritayı önbellekte tuttuğu için yeni hâli en geç 30 dakika içinde devreye girer; yeni sürüm adıyla yükleme anında geçerlidir). Harita yüklenirken çözülerek doğrulanır; bozuk harita 400 invalid_source_map ile reddedilir. Dosya başına sınır 20 MB'dır.

Vite ile örnek bir CI adımı:

export RELEASE="web@$(git rev-parse --short HEAD)"
VITE_RELEASE="$RELEASE" npx vite build --sourcemap hidden

for map in dist/assets/*.js.map; do
  curl --fail -X PUT \
    "https://api.errorbird.com/api/v1/sourcemaps?release=$RELEASE&file=$(basename "$map" .map)" \
    -H "X-API-KEY: $ERRORBIRD_SECRET_KEY" \
    -H "Content-Type: application/json" \
    --data-binary "@$map"
done

# Haritaları yayına almayın: orijinal kaynak kodunuzu içerirler.
rm dist/assets/*.js.map

--sourcemap hidden, haritayı üretir ama paketin sonuna //# sourceMappingURL yorumunu eklemez; tarayıcılar haritayı aramaz, kaynak kodunuz yayına çıkmaz. Webpack'te karşılığı devtool: 'hidden-source-map', esbuild'de --sourcemap=external'dır.

Sürüm adı birebir aynı olmalıdır. SDK'ya verdiğiniz release ile yüklemedeki release aynı değilse eşleme yapılmaz. En güvenli yol, ikisini de aynı ortam değişkeninden (yukarıdaki RELEASE) üretmektir.

Nasıl çalışır?

1. SDK hatayı POST /api/v1/ingest/browser ucuna gönderir. Uç, diğer ingest uçlarıyla aynı kotayı, PII temizlemesini ve doğrulamayı kullanır; farkı yalnızca CORS'a izin vermesidir.
2. Worker olayı işlerken sürüm etiketine ve stack'teki dosya adlarına bakar, eşleşen haritayı bulursa her çerçeveyi orijinal dosya, satır ve sütuna çevirir.
3. Çerçevenin fonksiyon adı küçültülmüş addan değil, haritadaki orijinal kaynak metninden (sourcesContent) konumu kapsayan fonksiyonun adı olarak bulunur. Kaynak metni olmayan haritalarda haritanın names alanı kullanılır; bu durumda ad derlemeler arasında daha az kararlıdır.
4. İmza çevrilmiş stack'ten hesaplanır. Küçültülmüş hâl olayın metadata'sında minifiedStackTrace olarak saklanır; harita yanlış sürüme yüklendiğinde ham konuma buradan bakılır.

Hem Chrome/Edge (V8: at fn (url:satır:sütun)) hem Firefox/Safari (fn@url:satır:sütun) biçimleri desteklenir. Eşlenemeyen satırlar (at Array.map (<anonymous>), haritası olmayan üçüncü taraf script'ler) olduğu gibi kalır.

Zamanlama. Harita, hatalardan önce yüklenmelidir; sembolleştirme olay işlenirken bir kez yapılır, sonradan yüklenen harita geçmiş olayları değiştirmez. Haritası bulunamayan sürüm bir dakika boyunca "yok" olarak hatırlanır, yani deploy ile yükleme arasındaki kısa yarış en fazla bir dakikalık olayı etkiler.

Yönetim

Panelde Projeler sayfası, her projenin yüklü haritalarını sürüm başına özetler ve bir sürümün haritalarını silmenizi sağlar. API karşılıkları:

Eski sürümlerin haritalarını silmek iyi bir alışkanlıktır; o sürümden hâlâ hata geliyorsa silinen harita yüzünden artık çevrilmez.