Sürüm: 0.71.0Bu dokümantasyon Spitfire 0.71.0 içindir.
Servisleri OTel ile bağlamak: genel
Bu bölümdeki rehberler bir servisi OpenTelemetry (OTel) ile Spitfire'a bağlar. Her rehber madde madde uygulanır: indir, koy, yapıştır, yeniden başlat, doğrula.
Ne işe yarar
- Servisinizin trace'leri koşu sırasında koşunun Backend sekmesine gelir;
traceparentaçık testlerde en yavaş ve hatalı istekler sizin trace'lerinizde bulunur. - Servisin metrikleri Tower üzerinden sürekli saklanır (Tower'lar ve metrikler → Kaynaklar, tür Servis).
- Kod değişikliği gerekmez: Java, .NET, Python, Node.js ve PHP için OTel'in otomatik enstrümantasyonu kullanılır.
Ne zaman kullanılır
- Yük testinde yavaşlığın servisin içinde nerede olduğunu görmek istediğinizde.
- Sunucu ve veritabanı metrikleri (Collector) yetmediğinde.
Rehberler ve sürümler
Önce servisin çalışma ortamının sürümünü bulun, sonra kendi satırınızın rehberini açın.
| Dil | Sürüm bandı | OTel paketi ve sürümü | Rehber |
|---|---|---|---|
| Java | 8, 11, 17, 21, 25 ve sonrası | opentelemetry-javaagent.jar 2.33.1 |
Java |
| Java | 7 ve öncesi | desteklenmiyor | – |
| .NET | .NET 8, 9, 10 | OpenTelemetry .NET Automatic Instrumentation 1.18.0 | .NET |
| .NET | .NET 6, 7 | OpenTelemetry .NET Automatic Instrumentation 1.9.0 | .NET |
| .NET | .NET Framework 4.6.2 – 4.8.1 | OpenTelemetry .NET Automatic Instrumentation 1.18.0 | .NET |
| .NET | .NET Framework 4.6.1 ve öncesi (4.5 dahil) | desteklenmiyor | – |
| Python | 3.10 ve sonrası | opentelemetry-distro 0.66b2 + opentelemetry-exporter-otlp-proto-http 1.45.2 |
Python |
| Python | 3.9 | opentelemetry-distro 0.62b1 + opentelemetry-exporter-otlp-proto-http 1.41.1 |
Python |
| Python | 3.8 | opentelemetry-distro 0.54b1 + opentelemetry-exporter-otlp-proto-http 1.33.1 |
Python |
| Node.js | 22.15 ve sonrası (22, 24, 26) | @opentelemetry/auto-instrumentations-node 0.82.0 |
Node.js |
| Node.js | 18.19+, 20.6+, 22.0 – 22.14 | @opentelemetry/auto-instrumentations-node 0.81.2, @opentelemetry/api 1.9.1 |
Node.js |
| PHP | 8.1 ve sonrası | opentelemetry PECL 1.4.2 + open-telemetry/sdk 1.15.0 |
PHP |
| PHP | 8.0 ve öncesi | desteklenmiyor | – |
Desteklenmeyen sürümde: çalışma ortamını tablodaki en düşük sürüme yükseltin ya da yalnız sunucu metriklerini alın (Collector).
Doğrulandı: 2026-11-02. Kaynaklar her rehberin sürüm tablosunun altındadır.
Gerekenler
Her rehber aynı değerleri ister. Tower'lar ve metrikler → Servis bağla (OTel) bunları sizin değerlerinizle doldurur.
| Değer | Nereden | Rehberde |
|---|---|---|
| Spitfire adresi | Spitfire'ı tarayıcıda açtığınız adres (ör. https://spitfire.corp ya da http://spitfire.corp:8470) |
https://<spitfire> |
| OTLP alıcısı anahtarı | Gözlemlenebilirlik → Ekle → OTLP alıcısı (nasıl) | sfotlp_… |
| Tower adresi ve portu | Tower makinesi, port 4318 (Tower'da TLS açıksa https://) |
http://<tower>:4318 |
| Collector token'ı | Tower oluşturulurken bir kez gösterilir | sfcol_… |
| Protokol | sabit: http/protobuf (gRPC kabul edilmez) |
OTEL_EXPORTER_OTLP_PROTOCOL |
| Servis adı | servisin kısa adı (ör. checkout-api) |
<service-name> |
| Servis sürümü | dağıtılan sürüm (ör. 1.4.2) |
<service-version> |
| Ortam | ör. prod, staging |
<environment> |
| CA sertifikası | Tower ya da Spitfire özel bir CA'nın sertifikasını kullanıyorsa CA dosyası (PEM) | /etc/spitfire-otel/ca.pem |
| Proxy | kurumsal proxy varsa Tower ve Spitfire proxy dışında kalmalı | NO_PROXY=<tower>,<spitfire> |
| Örnekleme | varsayılan parentbased_traceidratio, oran 0.1 |
OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARG |
Nereye ne gider:
- Trace ve log: doğrudan Spitfire'a,
https://<spitfire>/otlp/v1/tracesve/otlp/v1/logs, anahtarsfotlp_…. Servisin sunucusu Spitfire'ın adresine ulaşabilmelidir. - Metrik: Tower'a,
http://<tower>:4318/v1/metrics, tokensfcol_…. Tower yoksa metrikleri de Spitfire'a gönderin:https://<spitfire>/otlp/v1/metricsvesfotlp_…. - Spitfire'ın testlerindeki
traceparentheader'ı örneklenmiş (sampled) gelir;parentbased_…örnekleme bu istekleri oran ne olursa olsun kaydeder.
Token'lar header değerinde authorization=sfotlp_… biçiminde, Bearer kelimesi
olmadan yazılır: ortam değişkenindeki boşluk bazı SDK'larda bozulur. Spitfire ve Tower token'ı
Bearer ile de, Bearer olmadan da kabul eder.
Aç/kapat: IS_OTEL_ENABLED
Her ortam değişkeni bloğunun ilk satırı:
IS_OTEL_ENABLED=trueIS_OTEL_ENABLED=false olursa OTel verisi (trace, metrik, log) artık toplanmaz ve
gönderilmez. true olursa toplanır. Değişikliğin geçerli olması için servisin yeniden
başlatılması şarttır.
Bu değişkeni OTel'in kendisi tanımaz. Rehberdeki başlatma betiği onu çevirir: false ise
OTEL_SDK_DISABLED=true olur ve agent hiç yüklenmez (Java'da -javaagent eklenmez, .NET'te
profiler değişkenleri ayarlanmaz, Node.js'te --require eklenmez, Python opentelemetry-instrument
olmadan başlar, PHP'de OTEL_PHP_AUTOLOAD_ENABLED=false).
Ortak ortam değişkenleri
Bütün rehberler bu bloğu kullanır. Linux'ta /etc/spitfire-otel/<service-name>.env dosyasına
konur; aynı dosya Docker'da --env-file ile, Kubernetes'te Secret olarak kullanılır.
IS_OTEL_ENABLED=true
OTEL_SERVICE_NAME=<service-name>
OTEL_RESOURCE_ATTRIBUTES=service.version=<service-version>,deployment.environment=<environment>
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://<spitfire>/otlp/v1/traces
OTEL_EXPORTER_OTLP_TRACES_HEADERS=authorization=sfotlp_…
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=https://<spitfire>/otlp/v1/logs
OTEL_EXPORTER_OTLP_LOGS_HEADERS=authorization=sfotlp_…
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://<tower>:4318/v1/metrics
OTEL_EXPORTER_OTLP_METRICS_HEADERS=authorization=sfcol_…
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1
NO_PROXY=<tower>,<spitfire>
#OTEL_EXPORTER_OTLP_CERTIFICATE=/etc/spitfire-otel/ca.pem- Özel CA kullanıyorsanız son satırın başındaki
#işaretini kaldırın ve CA dosyasını o yola koyun. - Dosyada tırnak ve satır sonu yorumu kullanmayın (systemd ve Docker ikisini de değere katar).
- Dosyanın izni:
sudo chmod 600 /etc/spitfire-otel/<service-name>.env(token içerir).
Doğrulama
- Servis makinesinden Spitfire anahtarını deneyin;
200adres ve anahtar doğru,401anahtar yanlış demektir:
curl -s -o /dev/null -w '%{http_code}\n' -X POST https://<spitfire>/otlp/v1/traces \
-H 'Authorization: Bearer sfotlp_…' -H 'Content-Type: application/json' --data '{}'- Servis makinesinden Tower'ı deneyin; yanıtta
"connected":truegörünmelidir:
curl -s http://<tower>:4318/health- Servisi yeniden başlatıp bir dakika bekleyin: Tower'lar ve metrikler → Kaynaklar listesinde servis adı tür Servis ile görünür.
- Bir test koşusu başlatın: koşunun Backend sekmesinde servisin trace'leri görünür. Gözlemlenebilirlik sayfasında OTLP alıcısının yanında "son veri" güncellenir.
Sık karşılaşılan sorunlar
| Belirti | Neden | Çözüm |
|---|---|---|
curl 401 döndü |
Anahtar ya da token yanlış, iptal edilmiş ya da başka bir Tower'ın | Anahtarı Gözlemlenebilirlik'te Yeni anahtar ile yenileyin; Tower token'ını Tower'ı oluştururken verilen sfcol_… ile karşılaştırın |
| Servis listede yok | Metrikleri saklama kapalı ya da metrik Tower'a gitmiyor | Metrikleri topla ve sakla açık mı; OTEL_EXPORTER_OTLP_METRICS_ENDPOINT /v1/metrics ile mi bitiyor |
| PHP servisi listede yok | PHP kendiliğinden metrik üretmez | Beklenen durum; PHP rehberine bakın |
| Koşuda trace yok | Trace yalnız koşu penceresinde saklanır; ya da örnekleme düşük | Trace'i koşu sırasında üretin; testte traceparent açın |
Tower'dan 404 |
Trace ya da log Tower'a gönderildi | Trace ve log Spitfire'ın /otlp/v1/... adresine gider |
| TLS hatası | Özel CA tanınmıyor | OTEL_EXPORTER_OTLP_CERTIFICATE satırını açın ve CA dosyasını koyun |
| Bağlantı zaman aşımı | Kurumsal proxy araya giriyor ya da güvenlik duvarı kapalı | NO_PROXY satırını kontrol edin; servis → Tower 4318/TCP ve servis → Spitfire kuralını açtırın |