Sürüm: 0.71.0Bu dokümantasyon Spitfire 0.71.0 içindir.

Python servisini OTel ile bağlamak

OpenTelemetry Python otomatik enstrümantasyonu (opentelemetry-instrument) koda dokunmadan trace, metrik ve log toplar. Değerler ve genel kurallar: Servisleri OTel ile bağlamak: genel.

Sürüm tablosu

Python	`opentelemetry-distro`	`opentelemetry-exporter-otlp-proto-http`
3.10 ve sonrası	0.66b2	1.45.2
3.9	0.62b1	1.41.1
3.8	0.54b1	1.33.1
3.7 ve öncesi	desteklenmiyor	Python 3.8+'ya yükseltin ya da yalnız sunucu metrikleri: Collector

Sürümünüzü bulun: servisin kullandığı Python ile python --version.

Aşağıdaki komutlarda 3.10+ sürümleri yazılıdır; bandınız 3.9 ya da 3.8 ise tablodaki sürümleri yazın.

Doğrulandı: 2026-11-02. Kaynak: değişiklik günlüğü (3.8 desteği 1.34.0'da, 3.9 desteği 1.42.0'da kaldırıldı), PyPI opentelemetry-sdk, Python zero-code belgesi.

Gerekenler

Spitfire adresi https://<spitfire> ve OTLP alıcısı anahtarı sfotlp_…
Tower adresi http://<tower>:4318 ve Collector token'ı sfcol_…
Protokol http/protobuf
Servis adı <service-name>, sürümü <service-version>, ortamı <environment>
Özel CA varsa CA dosyası /etc/spitfire-otel/ca.pem
Proxy varsa Tower ve Spitfire NO_PROXY içinde
Örnekleme parentbased_traceidratio, 0.1

Linux (systemd)

Paketleri servisin sanal ortamına (<venv>, ör. /srv/app/.venv) kurun:

bash

sudo <venv>/bin/pip install opentelemetry-distro==0.66b2 opentelemetry-exporter-otlp-proto-http==1.45.2
sudo <venv>/bin/opentelemetry-bootstrap -a install
sudo mkdir -p /opt/spitfire-otel /etc/spitfire-otel

/etc/spitfire-otel/<service-name>.env dosyasını oluşturun, şunu yapıştırın:

bash

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

Aynı dosyanın sonuna Python log'ları için şu iki satırı ekleyin:

bash

OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
OTEL_PYTHON_LOG_AUTO_INSTRUMENTATION=true

İzni kısın: sudo chmod 600 /etc/spitfire-otel/<service-name>.env
/opt/spitfire-otel/otel-run dosyasını oluşturun, şunu yapıştırın:

bash

#!/bin/sh
# IS_OTEL_ENABLED=true: komut opentelemetry-instrument ile başlar; başka her değer: OTel'siz başlar.
if [ "$IS_OTEL_ENABLED" = "true" ]; then
  exec "$(dirname "$(command -v "$1")")/opentelemetry-instrument" "$@"
fi
export OTEL_SDK_DISABLED=true
exec "$@"

Çalıştırılabilir yapın: sudo chmod 755 /opt/spitfire-otel/otel-run
Servisin şimdiki başlatma komutunu bulun: systemctl cat <unit> | grep ^ExecStart. Komutun ilk kelimesi sanal ortamın içindeki tam yol olmalıdır (ör. /srv/app/.venv/bin/gunicorn).
sudo systemctl edit <unit> açın, şunu yapıştırın (son satırda ExecStart='tan sonraki komutu 7. adımdaki komutla değiştirin):

ini

[Service]
EnvironmentFile=/etc/spitfire-otel/<service-name>.env
ExecStart=
ExecStart=/opt/spitfire-otel/otel-run /srv/app/.venv/bin/gunicorn app:app --bind 0.0.0.0:8000

Yeniden başlatın: sudo systemctl daemon-reload && sudo systemctl restart <unit>
Çalıştığını görün: systemctl status <unit> çıktısında süreç opentelemetry-instrument üzerinden başlamıştır.

Docker

otel-run dosyasını (Linux 5. adım) Dockerfile'ın yanına koyun.
Dockerfile'a ekleyin; ENTRYPOINT'in başına /opt/spitfire-otel/otel-run gelir, gerisi sizin komutunuzdur (ilk kelime tam yol):

dockerfile

RUN pip install opentelemetry-distro==0.66b2 opentelemetry-exporter-otlp-proto-http==1.45.2 \
 && opentelemetry-bootstrap -a install
COPY --chmod=755 otel-run /opt/spitfire-otel/otel-run
ENTRYPOINT ["/opt/spitfire-otel/otel-run", "/usr/local/bin/gunicorn", "app:app", "--bind", "0.0.0.0:8000"]

Ortam dosyasını (Linux 2. ve 3. adım) Docker makinesinde /etc/spitfire-otel/<service-name>.env olarak kaydedin.
Çalıştırın: docker run --env-file /etc/spitfire-otel/<service-name>.env … ya da compose'da servisin altına env_file: /etc/spitfire-otel/<service-name>.env.
Ortam dosyası değişince konteyneri yeniden oluşturun (restart yetmez): docker compose up -d --force-recreate <service>

Kubernetes

Image'ı Docker bölümündeki gibi hazırlayın.
Ortam dosyasını (Linux 2. ve 3. adım) <service-name>.env olarak kaydedip Secret yapın:

bash

kubectl create secret generic <service-name>-otel --from-env-file=<service-name>.env \
  --dry-run=client -o yaml | kubectl apply -f -

Deployment'ta container'ın altına ekleyin:

yaml

envFrom:
  - secretRef:
      name: <service-name>-otel

Yeniden başlatın: kubectl rollout restart deployment/<deployment>

Windows (servis)

Yönetici PowerShell'de paketleri servisin sanal ortamına (<venv>, ör. C:\app\.venv) kurun:

powershell

<venv>\Scripts\pip.exe install opentelemetry-distro==0.66b2 opentelemetry-exporter-otlp-proto-http==1.45.2
<venv>\Scripts\opentelemetry-bootstrap.exe -a install

<windows-service> yerine servisin adını (Get-Service listesindeki Name), <venv> yerine sanal ortamın klasörünü yazıp çalıştırın:

powershell

$Service = "<windows-service>"
$Venv = "<venv>"
$IS_OTEL_ENABLED = "true"
$Otel = @(
  "IS_OTEL_ENABLED=$IS_OTEL_ENABLED",
  "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_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true",
  "OTEL_PYTHON_LOG_AUTO_INSTRUMENTATION=true"
)
# Özel CA: $Otel += "OTEL_EXPORTER_OTLP_CERTIFICATE=C:\spitfire-otel\ca.pem"
if ($IS_OTEL_ENABLED -eq "true") {
  $Otel += "PYTHONPATH=$Venv\Lib\site-packages\opentelemetry\instrumentation\auto_instrumentation"
} else {
  $Otel += "OTEL_SDK_DISABLED=true"
}
$Key = "HKLM:\SYSTEM\CurrentControlSet\Services\$Service"
$Keep = @((Get-ItemProperty $Key).Environment | Where-Object { $_ -and $_ -notmatch '^(IS_OTEL_ENABLED|OTEL_|PYTHONPATH|NO_PROXY)=' })
Set-ItemProperty $Key -Name Environment -Type MultiString -Value ($Keep + $Otel)
Restart-Service -Name $Service -Force

Servise birkaç istek gönderin ve Doğrulama adımlarını uygulayın.

Not

PYTHONPATH, OTel'i opentelemetry-instrument ile aynı yolla yükler (kaynak); servis komutu değişmez. Serviste zaten PYTHONPATH varsa o satırda ; ile arkasına ekleyin.

Kapatma ve kaldırma

Kapatmak: ortam dosyasında (Windows'ta betikte) IS_OTEL_ENABLED=false yapın ve servisi yeniden başlatın (Linux 9. adım, Docker 5. adım, Kubernetes 4. adım ya da Windows betiğini yeniden çalıştırın).
Kaldırmak: sudo systemctl revert <unit>, sudo rm -r /opt/spitfire-otel /etc/spitfire-otel ve <venv>/bin/pip uninstall ile opentelemetry- paketlerini kaldırın; Docker'da Dockerfile'a eklenen satırları silin; Windows'ta servisin Environment değerinden OTel satırlarını silin.

Sık karşılaşılan sorunlar

Belirti	Neden	Çözüm
`opentelemetry-instrument: not found`	Komutun ilk kelimesi sanal ortamın dışında	`ExecStart`'ta sanal ortamdaki tam yolu yazın (ör. `/srv/app/.venv/bin/python`)
`pip` sürüm bulamıyor	Python sürümü bandın dışında	Tablodaki bandınızın sürümlerini yazın
Trace var, kütüphane span'leri yok	`opentelemetry-bootstrap` çalışmadı	1. adımın ikinci komutunu servisin sanal ortamında yeniden çalıştırın
gunicorn ya da uWSGI worker'larından metrik gelmiyor	Fork eden sunucular	Fork modeli örneği'ndeki `post_fork` ayarını uygulayın
Trace, metrik gelmiyor	Adres, token ya da ağ	Doğrulama adımlarını uygulayın

Python servisini OTel ile bağlamak

#Sürüm tablosu

#Gerekenler

#Linux (systemd)

#Docker

#Kubernetes

#Windows (servis)

#Kapatma ve kaldırma

#Sık karşılaşılan sorunlar

#İlgili sayfalar

Sürüm tablosu

Gerekenler

Linux (systemd)

Docker

Kubernetes

Windows (servis)

Kapatma ve kaldırma

Sık karşılaşılan sorunlar

İlgili sayfalar