HTML / JavaScript sitesini (tarayıcı) OTel ile bağlamak
Build adımı olmayan her site için tek bir <script> etiketi yeter; loader'ı Spitfire'ınız https://<spitfire>/rum/spitfire-rum.js adresinde sunar. İstekler backend'e traceparent ile bağlanır, sonuç APM → Son kullanıcı sayfasında görünür. Ortak değerler: genel bakış.
Sürüm tablosu
| Parça | Paket | Sürüm |
|---|---|---|
Loader /rum/spitfire-rum.js |
@opentelemetry/sdk-trace, sdk-logs, core, resources |
3.0.0 |
@opentelemetry/exporter-trace-otlp-http, exporter-logs-otlp-http, instrumentation, instrumentation-fetch, instrumentation-xml-http-request |
0.300.0 | |
@opentelemetry/instrumentation-document-load |
0.69.0 | |
@opentelemetry/instrumentation-user-interaction |
0.68.0 | |
@opentelemetry/browser-instrumentation (Web Vitals, hatalar, navigation) |
0.9.0 | |
@opentelemetry/api |
1.10.0 | |
| Tarayıcı | ES2020 (Chrome 85, Firefox 79, Safari 14 ve sonrası) | – |
Loader bu paketlerden Spitfire ile birlikte derlenir. Tarayıcı onu CDN'den değil sizin Spitfire'ınızdan yükler, Spitfire güncellenince o da güncellenir. Sürümü tarayıcı konsolunda: SpitfireRUM.version. OTel tarayıcı instrumentation'ını deneysel sayıyor.
Doğrulandı: 2026-11-09. Kaynak: OTel JS browser, npm @opentelemetry/browser-instrumentation.
Gerekenler
- Spitfire adresi
https://<spitfire>; servis adı<service-name>, sürüm<service-version>, ortam<environment> - Sitenin adresi (burada
https://<app-origin>) ve her sayfanın kullandığı HTML dosyası (burada/srv/web/index.html) - API adresiniz, düzenli ifade olarak (burada
^https://api\.example\.com/)
HTML
Anahtarı oluşturun: Yönetim → Entegrasyonlar → Entegrasyon ekle → Tarayıcı ve uygulama anahtarı, İzin verilen kökenler
https://<app-origin>;sfrum_…anahtarını kopyalayın (APM).Bunu
/srv/web/index.htmldosyasının<head>bölümüne, diğer script'lerinizden önce yapıştırın (ölçülecek her sayfada olmalı):
<!-- IS_OTEL_ENABLED=true: kapatmak için bu etiketi silin -->
<script src="https://<spitfire>/rum/spitfire-rum.js"
data-endpoint="https://<spitfire>/otlp"
data-key="sfrum_…"
data-service="<service-name>"
data-version="<service-version>"
data-env="<environment>"
data-sample="1"
data-propagate="^https://api\.example\.com/"></script>- Siteniz
Content-Security-Policygönderiyorsa Spitfire'ıscript-srcveconnect-srclistelerine ekleyin:
Content-Security-Policy: script-src 'self' https://<spitfire>; connect-src 'self' https://<spitfire>- Sayfayı yayınlayın ve tarayıcıda açın.
Ayarlar
| Attribute | Anlamı |
|---|---|
data-key |
sfrum_… anahtarı (zorunlu) |
data-service |
Uygulamanın APM'deki adı (zorunlu) |
data-endpoint |
OTLP adresi; varsayılan: script'in kendi adresi + /otlp |
data-version, data-env |
Sürüm ve ortam |
data-sample |
Gönderilen session oranı, 0 ile 1 arası; varsayılan 1 |
data-propagate |
traceparent alacak API adreslerinin düzenli ifadesi (sayfanın kendi adresi her zaman alır) |
Ne gönderir
- Sayfa yüklemesi:
documentLoadspan'i ve DNS'ten load'a adım adım süreleri, kaynak sayısını ve en yavaş kaynağı taşıyanbrowser.page_timingevent'i. - Tek sayfalı uygulamada her rota değişimi için bir
screen.viewspan'i. - fetch ve XHR client span'leri (adres query string'siz);
data-propagateile eşleşenlertraceparenttaşır. click/submitspan'leri, stack'liexceptionevent'leri.- LCP, INP, CLS, FCP, TTFB event'leri; ölçüldükleri öğe
browser.web_vital.targetiçinde en çok 200 karakterlik bir CSS seçicisi olarak gelir, metni asla. - Sayfa görüntüleme başına bir
browser.long_tasksevent'i (50 ms ve üstü görevler).
Her şeyde sekme başına bir session.id olur. Tarayıcı, işletim sistemi, cihaz türü ve ülke Spitfire'da bulunur; gönderenin adresi saklanmaz (Ne saklanır).
Oturum açmış kullanıcı (isteğe bağlı)
Kodunuz belirtmedikçe kullanıcıyla ilgili hiçbir şey gönderilmez. Session'ları kullanıcıya göre görmek için oturum açıldıktan sonra kendi kullanıcı kimliğinizle (e-posta adresi değil) bunu çağırın:
<script>SpitfireRUM.setUser('<user-id>')</script>Oturum kapanınca: SpitfireRUM.setUser(null)
Backend'iniz
- Backend'in CORS ayarı
https://<app-origin>adresinden gelen trace başlıklarına izin versin:
Access-Control-Allow-Headers: traceparent, tracestate, baggageDoğrulama
- Spitfire loader'ı sunuyor:
curl -s -o /dev/null -w '%{http_code}' https://<spitfire>/rum/spitfire-rum.js | grep -q '^200$' && echo OK- Tarayıcı gönderebiliyor:
curl -s -o /dev/null -w '%{http_code}' -X OPTIONS https://<spitfire>/otlp/v1/logs -H 'Origin: https://<app-origin>' -H 'Access-Control-Request-Method: POST' | grep -q '^204$' && echo OK- Spitfire anahtarı kabul ediyor:
curl -s -o /dev/null -w '%{http_code}' -X POST https://<spitfire>/otlp/v1/traces -H 'Origin: https://<app-origin>' -H 'Authorization: Bearer sfrum_…' -H 'Content-Type: application/json' -d '{}' | grep -q '^200$' && echo OK- Sayfayı açın, sonra APM → Son kullanıcı:
<service-name>uygulaması bir dakika içinde bir sayfa yüklemesi gösterir.
Kapatma ve kaldırma
- Bir süre kapatmak için:
data-sample="0"yazın. - Kaldırmak için:
<script … spitfire-rum.js>etiketini ve eklediğiniz CSP satırlarını silin.
Sık karşılaşılan sorunlar
| Belirti | Çözüm |
|---|---|
Konsol: spitfire-rum: data-key must be … |
data-key, sfrum_… anahtarı olmalı |
| Konsol: CSP script'i ya da bağlantıyı reddetti | HTML adım 3 |
| Doğrulama adım 2 bir şey yazmıyor | https://<app-origin> adresini anahtarın İzin verilen kökenler listesine ekleyin; 30 sn bekleyin |
401 |
Anahtar sfrum_… olmalı ve açık olmalı |
429 |
Anahtarın Dakikada gönderim değerini artırın ya da data-sample değerini düşürün |
| API çağrılarınız CORS hatası veriyor | Backend'iniz adım 1 |
| İstekler backend trace'ine bağlanmıyor | data-propagate, API adresinize uymalı |
| Web Vitals gelmiyor | LCP ve INP sayfa gizlenince ya da kapanınca gönderilir; bir kez sekme değiştirin |