PHP servisini OTel ile bağlamak

OpenTelemetry PHP eklentisi (opentelemetry) ve SDK, kütüphanelerin otomatik enstrümantasyon paketleriyle koda dokunmadan trace ve log toplar. PHP kendiliğinden metrik üretmez: servis, uygulama kendi metriklerini kaydettiğinde (Metrics API) Tower'lar ve metrikler → Kaynaklar'da görünür; sunucunun metrikleri için Collector. Değerler ve genel kurallar: Servisleri OTel ile bağlamak: genel.

#Sürüm tablosu

Sürümünüzü bulun: php --version (PHP-FPM için php-fpm<php-version> --version).

PHP 8.0: bu sürüm için son paketler güvenlik uyarısı olan google/protobuf sürümlerini ister, Composer bunları kurmaz. PHP 8.1+'ya yükseltin.

Doğrulandı: 2026-11-02. Kaynak: PHP zero-code belgesi (PHP 8.0+), PECL opentelemetry (sürüm başına en düşük PHP), Packagist open-telemetry/sdk, Packagist open-telemetry/exporter-otlp.

#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
• Uygulamada Composer (vendor/autoload.php)

#Linux (PHP-FPM, systemd)

1. Eklentiyi derleyip kurun (Debian/Ubuntu; RHEL'de Remi deposundan php-pecl-opentelemetry paketi de olur):

sudo apt-get install -y gcc make autoconf php-dev php-pear
sudo pecl install opentelemetry-1.4.2

2. Eklentiyi açın: /etc/php/<php-version>/mods-available/opentelemetry.ini dosyasını oluşturun, şunu yapıştırın, sonra sudo phpenmod opentelemetry çalıştırın:

[opentelemetry]
extension=opentelemetry.so

3. Açık olduğunu görün: php --ri opentelemetry (opentelemetry support => enabled).
4. Uygulamanın klasöründe SDK'yı, exporter'ı ve çatınızın enstrümantasyon paketini kurun (opentelemetry-auto-laravel yerine kendi çatınızınkini yazın: -auto-symfony, -auto-slim; tam liste Packagist):

composer config allow-plugins.php-http/discovery true
composer require open-telemetry/sdk:1.15.0 open-telemetry/exporter-otlp:1.4.0 php-http/guzzle7-adapter \
  open-telemetry/opentelemetry-auto-laravel open-telemetry/opentelemetry-auto-psr3
sudo mkdir -p /opt/spitfire-otel /etc/spitfire-otel

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

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

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

#!/bin/sh
# IS_OTEL_ENABLED=true: OTel otomatik yüklenir; başka her değer: yüklenmez, SDK kapalı.
if [ "$IS_OTEL_ENABLED" = "true" ]; then
  export OTEL_PHP_AUTOLOAD_ENABLED=true
else
  export OTEL_PHP_AUTOLOAD_ENABLED=false
  export OTEL_SDK_DISABLED=true
fi
exec "$@"

8. Çalıştırılabilir yapın: sudo chmod 755 /opt/spitfire-otel/otel-run
9. PHP-FPM'in ortam değişkenlerini worker'lara geçirmesi için pool dosyasında (/etc/php/<php-version>/fpm/pool.d/www.conf) şu satırı açın ya da ekleyin:

clear_env = no

10. FPM servisinin şimdiki başlatma komutunu bulun: systemctl cat php<php-version>-fpm | grep ^ExecStart
11. sudo systemctl edit php<php-version>-fpm açın, şunu yapıştırın (son satırda ExecStart='tan sonraki komutu 10. adımdaki komutla değiştirin):

[Service]
EnvironmentFile=/etc/spitfire-otel/<service-name>.env
ExecStart=
ExecStart=/opt/spitfire-otel/otel-run /usr/sbin/php-fpm8.3 --nodaemonize --fpm-config /etc/php/8.3/fpm/php-fpm.conf

12. Yeniden başlatın: sudo systemctl daemon-reload && sudo systemctl restart php<php-version>-fpm

#Docker

1. otel-run dosyasını (Linux 7. adım) Dockerfile'ın yanına koyun.
2. Resmi php image'ında Dockerfile'a ekleyin (Composer adımı Linux 4. adımdaki gibi); ENTRYPOINT'in başına /opt/spitfire-otel/otel-run gelir, gerisi sizin komutunuzdur:

RUN pecl install opentelemetry-1.4.2 && docker-php-ext-enable opentelemetry
RUN echo "clear_env = no" >> /usr/local/etc/php-fpm.d/www.conf
COPY --chmod=755 otel-run /opt/spitfire-otel/otel-run
ENTRYPOINT ["/opt/spitfire-otel/otel-run", "php-fpm"]

3. Ortam dosyasını (Linux 5. adım) Docker makinesinde /etc/spitfire-otel/<service-name>.env olarak kaydedin.
4. Ç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.
5. Ortam dosyası değişince konteyneri yeniden oluşturun (restart yetmez): docker compose up -d --force-recreate <service>

#Kubernetes

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

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

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

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

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

#Windows (IIS)

1. PHP'nizin sürümünü ve derlemesini bulun: php -i | findstr /C:"PHP Version" /C:"Thread Safety" /C:"Architecture" (IIS NTS derlemesini çalıştırır, Thread Safety => disabled).
2. PECL Windows sayfasından PHP sürümünüze, nts ve x64'e uyan zip'i indirin (ör. https://downloads.php.net/~windows/pecl/releases/opentelemetry/1.4.2/php_opentelemetry-1.4.2-8.3-nts-vs16-x64.zip) ve içindeki php_opentelemetry.dll'i PHP'nin ext klasörüne (ör. C:\php\ext) koyun.
3. php.ini'nin sonuna bu satırı ekleyin (hangi dosya olduğunu php --ini gösterir):

extension=opentelemetry

4. Açık olduğunu görün: php --ri opentelemetry (opentelemetry support => enabled).
5. Uygulamanın klasöründe Linux 4. adımdaki iki composer komutunu çalıştırın (sudo mkdir satırı Windows'ta gerekmez).
6. Yönetici PowerShell'de C:\php\php-cgi.exe yerine sitenin kullandığı php-cgi.exe'yi (IIS Yöneticisi → FastCGI Settings → Full Path) yazıp çalıştırın (IIS yeniden başlar):

Import-Module WebAdministration
$PhpCgi = "C:\php\php-cgi.exe"
$IS_OTEL_ENABLED = "true"
$Vars = [ordered]@{
  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>"
}
# Özel CA: $Vars.OTEL_EXPORTER_OTLP_CERTIFICATE = "C:\spitfire-otel\ca.pem"
if ($IS_OTEL_ENABLED -eq "true") {
  $Vars.OTEL_PHP_AUTOLOAD_ENABLED = "true"
} else {
  $Vars.OTEL_PHP_AUTOLOAD_ENABLED = "false"
  $Vars.OTEL_SDK_DISABLED = "true"
}
$Filter = "system.webServer/fastCgi/application[@fullPath='$PhpCgi']/environmentVariables"
foreach ($Name in @($Vars.Keys) + @("OTEL_SDK_DISABLED")) {
  Remove-WebConfigurationProperty -PSPath 'MACHINE/WEBROOT/APPHOST' -Filter $Filter -Name "." -AtElement @{ name = $Name } -ErrorAction SilentlyContinue
}
foreach ($Name in $Vars.Keys) {
  Add-WebConfigurationProperty -PSPath 'MACHINE/WEBROOT/APPHOST' -Filter $Filter -Name "." -Value @{ name = $Name; value = $Vars[$Name] }
}
iisreset /restart

7. Sitede birkaç sayfa açın ve Doğrulama adımlarını uygulayın.

#Kapatma ve kaldırma

1. Kapatmak: ortam dosyasında (Windows'ta betikte) IS_OTEL_ENABLED=false yapın ve servisi yeniden başlatın (Linux 12. adım, Docker 5. adım, Kubernetes 4. adım ya da Windows betiğini yeniden çalıştırın).
2. Kaldırmak: sudo systemctl revert php<php-version>-fpm, sudo phpdismod opentelemetry, sudo rm -r /opt/spitfire-otel /etc/spitfire-otel ve composer remove ile open-telemetry/ paketlerini kaldırın; Docker'da Dockerfile'a eklenen satırları silin; Windows'ta php.ini'den extension=opentelemetry satırını ve IIS Yöneticisi → FastCGI Settings → Environment Variables'taki OTel değişkenlerini silin.

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

#İlgili sayfalar

• Servisleri OTel ile bağlamak: genel
• Tower ve sürekli metrikler
• Gözlemlenebilirlik