OTLP göndericisini hazırlamak: anahtar, Collector ve sürekli APM

Bu sayfa, servislerinizin trace, metrik ve loglarını OpenTelemetry (OTLP) ile Spitfire'ın OTLP alıcısına göndermek için sizin tarafınızda yapılacakları anlatır: bir anahtar, isteğe bağlı bir ara Collector, kişisel veri süzgeci ve sürekli APM. Zabbix'ten farkı şudur: burada veriyi siz gönderirsiniz, Spitfire çekmez. Bu yüzden Spitfire'daki Test et de sizin gönderdiğiniz deneme isteğini görmeyi bekler. Alıcının Spitfire tarafındaki ayrıntıları: Gözlemlenebilirlik: OTLP alıcısı.

#Ne gerekecek

• Spitfire'ın dışarıdan erişilen adresi, ör. https://spitfire.example.com. Alıcı bu adresin /otlp/v1/traces, /otlp/v1/metrics ve /otlp/v1/logs yollarındadır. Spitfire anahtar ekranında bu adresi kendisi yazar.
• HTTPS çıkışı: servisin ya da Collector'ın bu adrese 443'ten çıkabilmesi (güvenlik duvarı, Kubernetes egress NetworkPolicy, kurumsal proxy).
• Bir OTLP alıcısı anahtarı (sfotlp_…). Her sistem ya da ortam için ayrı bir alıcı açın: biri sızarsa yalnız o kesilir.
• Koşu dışındaki veri için sürekli APM: Spitfire bir koşu sürmüyorsa gelen veriyi yalnız sürekli APM açıksa saklar. Ayrıntı: Sürekli APM'i açın.

Alıcı yalnız veri alır: Spitfire sizin sistemlerinize bu yoldan hiçbir istek göndermez.

#Sürümünüzü bulun

Doğrudan SDK'dan gönderiyorsanız dilinizin rehberindeki sürüm tablosuna bakın (Servisleri OTel ile bağlamak). Bir Collector kullanıyorsanız sürümünü öğrenin:

otelcol-contrib --version          # sunucuda
kubectl exec deploy/<collector> -- /otelcol-contrib --version   # Kubernetes'te

Doğrulandı: OpenTelemetry Collector contrib 0.164.0, Spitfire 1.4.7, 2026-11-09.

#Kuruluma göre adımlar

#Anahtarı alın

1. Gözlemlenebilirlik → Ekle → OTLP alıcısı. Ad olarak sistemin ya da ortamın adını yazın (ör. siparis-prod) ve Kaydet.
2. Anahtar (sfotlp_…) bir kez gösterilir. Spitfire yalnız özetini saklar; kaybederseniz listeden Yeni anahtar üretilir.
3. Anahtarı doğrudan sırların durduğu yere koyun: Kubernetes Secret, sunucudaki .env dosyası ya da kasa.

Anahtar ekranındaki doğrulama komutunu hemen çalıştırabilirsiniz: Göndermeden önce deneyin.

#Doğrudan SDK'dan

Tek servis ve az trafik için yeterlidir: servis Spitfire'a kendisi gönderir. Dilinizin rehberini izleyin; hepsi aynı ortam değişkenlerini kullanır:

OTEL_EXPORTER_OTLP_ENDPOINT=https://spitfire.example.com/otlp
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_HEADERS=authorization=sfotlp_…

Rehberler: Java, .NET, Python, Node.js, PHP, Go, Ruby, Rust.

Birden çok servisiniz varsa ya da Spitfire'a ulaşılamadığında uygulamanın hiç etkilenmemesini istiyorsanız bir ara Collector kullanın.

#Kubernetes'te ara Collector

Önerilen yol budur. Servisler kümedeki Collector'a gönderir, Collector Spitfire'a. Spitfire'a ulaşılamazsa uygulama beklemez; toplu gönderim, sıkıştırma, kişisel veri süzgeci ve örnekleme tek yerde yapılır.

1. Secret: anahtar ve adres ortam değişkeni olarak gelir; ConfigMap'e yazılmaz.

   bashKopyala

   read -rs SF_TOKEN   # anahtarı yapıştırın, Enter; komut geçmişine düşmez
   kubectl -n <namespace> create secret generic spitfire-otlp \
     --from-literal=SPITFIRE_OTLP_ENDPOINT=https://spitfire.example.com/otlp \
     --from-literal=SPITFIRE_OTLP_TOKEN="$SF_TOKEN"
   unset SF_TOKEN

2. Collector yapılandırması (ConfigMap). memory_limiter pod sınırının altında kalır; kuyruk dolarsa veri düşer, uygulama etkilenmez; yeniden deneme süresi sınırlıdır.

   yamlKopyala

   extensions:
     health_check:
       endpoint: 0.0.0.0:13133
   receivers:
     otlp:
       protocols:
         http:
           endpoint: 0.0.0.0:4318
   processors:
     memory_limiter:
       check_interval: 1s
       limit_mib: 200        # pod sınırı 256Mi: sınırın yaklaşık %80'i
       spike_limit_mib: 50
     batch:
       send_batch_size: 1024
       send_batch_max_size: 2048
       timeout: 5s
   exporters:
     otlp_http/spitfire:     # eski sürümlerde: otlphttp/spitfire
       endpoint: ${env:SPITFIRE_OTLP_ENDPOINT}
       headers:
         authorization: ${env:SPITFIRE_OTLP_TOKEN}
       compression: gzip
       sending_queue:
         num_consumers: 2
         queue_size: 50
       retry_on_failure:
         initial_interval: 5s
         max_interval: 30s
         max_elapsed_time: 120s
   service:
     extensions: [health_check]
     pipelines:
       traces:
         receivers: [otlp]
         processors: [memory_limiter, batch]
         exporters: [otlp_http/spitfire]
       metrics:
         receivers: [otlp]
         processors: [memory_limiter, batch]
         exporters: [otlp_http/spitfire]
       logs:
         receivers: [otlp]
         processors: [memory_limiter, batch]
         exporters: [otlp_http/spitfire]

3. Deployment: imaj otel/opentelemetry-collector-contrib, envFrom ile spitfire-otlp Secret'ı, bellek sınırı (ör. 256Mi) ve GOMEMLIMIT (sınırın biraz altı, ör. 200MiB), hazırlık ve canlılık denetimi :13133/.

4. NetworkPolicy: Collector'a yalnız uygulama pod'ları 4318'den girer; Collector'ın Spitfire adresine 443 çıkışı ve DNS açık kalır.

5. Servisler: OTEL_EXPORTER_OTLP_ENDPOINT=http://<collector-service>.<namespace>:4318 ve anahtarsız gönderir; anahtar yalnız Collector'dadır.

6. Kaynak öznitelikleri: service.name, service.namespace, deployment.environment ve Kubernetes namespace, deployment, pod ve node adları. Spitfire'ın servis listesi ve haritası bunları kullanır. k8sattributes işlemcisi pod bilgisini kendisi ekler.

authorization başlığı Bearer sfotlp_… ya da yalnız sfotlp_… olarak kabul edilir. Ortam değişkenindeki boşluk bir aracın elinde bozuluyorsa Bearer kelimesini atın.

Doğrulandı: OpenTelemetry Collector contrib 0.164.0 Kubernetes'te, Spitfire 1.4.7, 2026-11-09.

#Sunucuda ya da Docker'da Collector

Yapılandırma Kubernetes'tekiyle aynıdır. Anahtar ve adres ortam dosyasından gelir:

# /etc/otelcol-contrib/spitfire.env (yalnız root okur: chmod 600)
SPITFIRE_OTLP_ENDPOINT=https://spitfire.example.com/otlp
SPITFIRE_OTLP_TOKEN=sfotlp_…

Docker'da: docker run --env-file spitfire.env -v $PWD/config.yaml:/etc/otelcol-contrib/config.yaml otel/opentelemetry-collector-contrib. systemd'de: servis dosyasına EnvironmentFile=/etc/otelcol-contrib/spitfire.env.

#Kişisel veriyi süzün

Trace ve loglara kullanıcı kimliği, e-posta, telefon, istemci IP'si, sorgu dizisi, başlık ve SQL parametresi yazılmamalıdır (KVKK, GDPR). Uygulama yazmıyorsa da Collector'da ikinci bir süzgeç önerilir:

processors:
  attributes/pii:
    actions:
      - { key: enduser.id, action: delete }
      - { key: user.email, action: delete }
      - { key: client.address, action: delete }
      - { key: http.request.header.authorization, action: delete }
      - { key: http.request.header.cookie, action: delete }
  transform/pii:
    error_mode: ignore
    trace_statements:
      - replace_pattern(span.attributes["url.full"], "\\?.*", "")
      - replace_all_patterns(span.attributes, "value", "[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+", "<email>")
    log_statements:
      - replace_pattern(log.body["string"], "[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+", "<email>")

İşlemcileri her hattın processors listesine memory_limiter'dan sonra, batch'ten önce ekleyin. Dış servislere giden isteklerde traceparent göndermemek de iç kimlikleri üçüncü taraflardan saklar.

Spitfire'ın kendisi de bir güvenlik ağıdır: URL'lerin sorgu dizisini keser, veritabanı ifadelerini işlem ve tabloya indirger. Gelen öznitelik değerlerinde e-posta, telefon ya da açık IP kalıbı görürse alıcı satırında o özniteliklerin adlarını gösterir. Değerin kendisi gösterilmez ve saklanmaz. Uyarıyı görürseniz bu süzgece o adları ekleyin.

#Sürekli APM'i açın

Spitfire bir koşu sürerken gelen veriyi koşunun penceresine yazar. 7/24 izleme için sürekli APM gerekir; kapalıyken koşu dışındaki veri 200 ve "partial success" yanıtıyla atılır. Collector'ın logunda şöyle görünür:

warn  Partial success ... no Spitfire run in progress: data outside run windows is not kept

1. APM → Servisler: kurulum yöneticisi "Trace'lerin veritabanında yer kaplayacağını onaylıyorum" kutusunu işaretler ve saklama gününü seçer (lisansın izin verdiği güne kadar).
2. Kendi sunucunuzda çalışan Spitfire'da ayrıca SPITFIRE_CLICKHOUSE_URL gerekir.
3. Disk için kaba bir tahmin: 30 saniyede yaklaşık 200 span üreten küçük bir sistem 30 günde birkaç GB tutar.

Yönetici değilseniz Spitfire alıcı penceresinde bunu bir uyarı kutusuyla söyler: kutuyu yöneticinize iletin. Alıcı satırındaki koşu dışı atılan sayacı da ne kadar verinin kaybolduğunu gösterir.

Doğrulandı: Spitfire 1.4.7, 30 günlük saklama, 2026-11-09.

#Ön kapı arkasındaysa

Kendi sunucunuzdaki Spitfire Cloudflare Access gibi bir kapının arkasındaysa Collector'ın isteği kapıya takılır (302 ya da 403). Zabbix'in tersine burada service token çalışır: istemci sizin Collector'ınızdır ve istediğiniz başlığı ekleyebilir.

1. Zero Trust → Access controls → Service credentials → Service Tokens → Create Service Token; Client ID ve Client Secret'ı Collector'ın Secret'ına koyun.

2. Spitfire alan adında Path otlp/ olan ayrı bir uygulama açın; politika Service Auth, Include → Service Token → oluşturduğunuz token. Arayüz mevcut uygulamanın politikasında kalır.

3. Exporter'a başlıkları ekleyin:

   yamlKopyala

   exporters:
     otlp_http/spitfire:
       endpoint: ${env:SPITFIRE_OTLP_ENDPOINT}
       headers:
         authorization: ${env:SPITFIRE_OTLP_TOKEN}
         CF-Access-Client-Id: ${env:CF_ACCESS_CLIENT_ID}
         CF-Access-Client-Secret: ${env:CF_ACCESS_CLIENT_SECRET}

Service token kullanamıyorsanız ikinci yol, aynı uygulamada gönderen IP'lere Bypass politikasıdır. Öteki kapılarda (nginx auth_request, SSO proxy'leri) aynı mantıkla yalnız /otlp/ yolunu açın; alıcıyı Spitfire anahtarı korur.

#Göndermeden önce deneyin

Servisin ya da Collector'ın çalıştığı makineden çalıştırın. Anahtar komut geçmişine düşmesin diye önce read -rs ile okunur:

read -rs SF_TOKEN   # anahtarı yapıştırın, Enter
curl -s -o /dev/null -w '%{http_code}\n' -X POST https://spitfire.example.com/otlp/v1/traces \
  -H "Authorization: Bearer $SF_TOKEN" -H 'Content-Type: application/json' --data '{}'
unset SF_TOKEN

Kubernetes'te aynı komutu Collector'ın namespace'inde geçici bir pod'dan çalıştırın; böylece NetworkPolicy de denenmiş olur.

Doğrulandı: curl 8, Spitfire 1.4.7, 200, 2026-11-08.

#Spitfire'da

• Test et: alıcı penceresinde Test et'e basıp yukarıdaki komutu çalıştırın. Spitfire bu anahtarla gelen ilk isteği (boş {} dahil) bekler ve zamanını ve kaynak IP'sini gösterir. Süre dolarsa "hiç istek gelmedi" der. Yanlış anahtarla gelen istekler hiçbir alıcıya bağlanamadığı için yalnız son 5 dakikadaki 401 sayısı gösterilir; IP gösterilmez. Sayı tüm kurulumundur, bu yüzden yalnız kurulum yöneticisi görür.

• Alıcı satırı: sinyal başına (trace, metrik, log) son veri zamanı ve son bir saatteki sayı, nedenine göre reddedilen istekler ve koşu dışı atılan sayacı. 24 saattir veri gelmeyen alıcı sarı, hiç veri gelmemiş alıcı kırmızı görünür.

  Not

  Sayaçlar (son bir saat, reddedilen, koşu dışı atılan, 401) yalnız bellekte tutulur: Spitfire yeniden başlayınca sıfırdan başlar. Sarı/kırmızı kayıtlı son veri zamanından gelir, yeniden başlatmada kaybolmaz.

• Veri geldi mi: servisi yeniden başlattıktan bir iki dakika sonra Tower'lar ve metrikler → Kaynaklar'da servis adı, APM'de ilk trace görünür. Collector'da:

  bashKopyala

  kubectl logs deploy/<collector> --since=1m | grep -c "Partial success"

  0 beklenir. Sayı sıfırdan büyükse Sık hatalar tablosunun son satırına bakın.

Doğrulandı: OpenTelemetry Collector contrib 0.164.0, Spitfire 1.4.7, sürekli APM onayından sonra 0, 2026-11-09.

#Sık hatalar

#Geri almak

1. Gönderimi kapatın: SDK'da izlemeyi kapatan ortam değişkeni ya da Collector'dan otlp_http/spitfire exporter'ı, sonra yeniden dağıtım.
2. Spitfire'da alıcıyı kapatın ya da silin; ya da Yeni anahtar ile eskisini hemen geçersiz kılın.
3. Secret'ı ve ön kapıda açtığınız uygulamayı silin.

Gelmiş veri saklama süresi boyunca kalır; koşulara bağlı veri o koşularda kalır.

#İlgili sayfalar

• Gözlemlenebilirlik: OTLP alıcısı
• Servisleri OTel ile bağlamak
• APM ekranları