Spitfirev0.71.0 · Yenilikler

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

.NET servisini OTel ile bağlamak

OpenTelemetry .NET Automatic Instrumentation koda dokunmadan trace, metrik ve log toplar. Değerler ve genel kurallar: Servisleri OTel ile bağlamak: genel.

Sürüm tablosu

Çalışma ortamı Sürüm Not
.NET 8, 9, 10 1.18.0 Linux, Windows, Docker
.NET 6, 7 1.9.0 .NET 6 ve 7 desteği 1.10.0'da kaldırıldı; 1.9.0'da kalın
.NET Framework 4.6.2 – 4.8.1 1.18.0 Yalnız Windows (IIS ya da Windows servisi)
.NET Framework 4.6.1 ve öncesi (4.5 dahil) desteklenmiyor 4.6.2+'ya (ör. 4.8) yükseltin ya da yalnız sunucu metrikleri: Collector

Sürümünüzü bulun: .NET için dotnet --list-runtimes; .NET Framework için uygulamanın web.config ya da .csproj dosyasındaki targetFramework.

Aşağıdaki komutlarda sürüm v1.18.0 yazılıdır; bandınız .NET 6/7 ise her yerde v1.9.0 yazın.

Doğrulandı: 2026-11-02. Kaynak: desteklenen çalışma ortamları, değişiklik günlüğü (.NET 6/7 kaldırılması 1.10.0), 1.9.0 belgesi, IIS, Windows servisi.

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 (Windows: C:\spitfire-otel\ca.pem)
  • Proxy varsa Tower ve Spitfire NO_PROXY içinde
  • Örnekleme parentbased_traceidratio, 0.1

Linux (systemd)

  1. Kurulum betiğini indirip çalıştırın (makinede curl ve unzip olmalı):
bash
curl -sSfL -O https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/download/v1.18.0/otel-dotnet-auto-install.sh
sudo OTEL_DOTNET_AUTO_HOME=/opt/otel-dotnet-auto SKIP_RELEASE_VERIFICATION=true sh ./otel-dotnet-auto-install.sh
sudo mkdir -p /opt/spitfire-otel /etc/spitfire-otel
Not

Makinede GitHub CLI (gh) varsa SKIP_RELEASE_VERIFICATION=true kısmını silin; betik indirilen paketin imzasını doğrular. 1.9.0 bu değişkeni kullanmaz.

  1. /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
  1. İzni kısın: sudo chmod 600 /etc/spitfire-otel/<service-name>.env
  2. /opt/spitfire-otel/otel-run dosyasını oluşturun, şunu yapıştırın:
bash
#!/bin/sh
# IS_OTEL_ENABLED=true: profiler ve startup hook yüklenir; başka her değer: hiçbiri yüklenmez.
if [ "$IS_OTEL_ENABLED" = "true" ]; then
  export OTEL_DOTNET_AUTO_HOME=/opt/otel-dotnet-auto
  . /opt/otel-dotnet-auto/instrument.sh
else
  export OTEL_SDK_DISABLED=true
fi
exec "$@"
  1. Çalıştırılabilir yapın: sudo chmod 755 /opt/spitfire-otel/otel-run
  2. Servisin şimdiki başlatma komutunu bulun: systemctl cat <unit> | grep ^ExecStart
  3. sudo systemctl edit <unit> açın, şunu yapıştırın (son satırda ExecStart='tan sonraki komutu 6. adımdaki komutla değiştirin):
ini
[Service]
EnvironmentFile=/etc/spitfire-otel/<service-name>.env
ExecStart=
ExecStart=/opt/spitfire-otel/otel-run /usr/bin/dotnet /srv/app/App.dll
  1. Yeniden başlatın: sudo systemctl daemon-reload && sudo systemctl restart <unit>
  2. Yüklendiğini görün: ls /var/log/opentelemetry/dotnet altında servisin süreç numarasıyla log dosyaları oluşur.
Dikkat

Servis DOTNET_EnableDiagnostics=0 ile başlıyorsa .NET 8+'da profiler yüklenmez; bu satırı kaldırın.

Docker

  1. otel-run dosyasını (Linux 4. adım) Dockerfile'ın yanına koyun.
  2. Dockerfile'a ekleyin (image'da curl ve unzip olmalı); ENTRYPOINT'in başına /opt/spitfire-otel/otel-run gelir, gerisi sizin komutunuzdur:
dockerfile
ADD --chmod=755 https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/download/v1.18.0/otel-dotnet-auto-install.sh /tmp/otel-dotnet-auto-install.sh
RUN OTEL_DOTNET_AUTO_HOME=/opt/otel-dotnet-auto SKIP_RELEASE_VERIFICATION=true sh /tmp/otel-dotnet-auto-install.sh && rm /tmp/otel-dotnet-auto-install.sh
COPY --chmod=755 otel-run /opt/spitfire-otel/otel-run
ENTRYPOINT ["/opt/spitfire-otel/otel-run", "dotnet", "/app/App.dll"]
  1. Ortam dosyasını (Linux 2. adım) Docker makinesinde /etc/spitfire-otel/<service-name>.env olarak kaydedin.
  2. Ç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.
  3. 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 2. 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 -
  1. Deployment'ta container'ın altına ekleyin:
yaml
envFrom:
  - secretRef:
      name: <service-name>-otel
  1. Yeniden başlatın: kubectl rollout restart deployment/<deployment>

Windows: kurulum (bir kez)

  1. PowerShell'i yönetici olarak açın ve çalıştırın:
powershell
New-Item -ItemType Directory -Force C:\spitfire-otel | Out-Null
Invoke-WebRequest -Uri https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/download/v1.18.0/OpenTelemetry.DotNet.Auto.psm1 -OutFile C:\spitfire-otel\OpenTelemetry.DotNet.Auto.psm1
Import-Module C:\spitfire-otel\OpenTelemetry.DotNet.Auto.psm1
Install-OpenTelemetryCore -SkipReleaseVerification
Not

Makinede GitHub CLI (gh.exe) varsa -SkipReleaseVerification'ı silin; paketin imzası doğrulanır. 1.9.0'da bu parametre yoktur, silin.

  1. Uygulama IIS'teyse "Windows: IIS", Windows servisiyse "Windows: servis" bölümüne geçin.

Windows: IIS

  1. Yönetici PowerShell'de bir kez çalıştırın (IIS yeniden başlar):
powershell
Import-Module C:\spitfire-otel\OpenTelemetry.DotNet.Auto.psm1
Register-OpenTelemetryForIIS
  1. Uygulamanın application pool'u için, <app-pool> yerine pool'un adını (IIS Yöneticisi → Application Pools) yazıp çalıştırın:
powershell
Import-Module WebAdministration
$Pool = "<app-pool>"
$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 -ne "true") {
  $Vars.COR_ENABLE_PROFILING = "0"
  $Vars.CORECLR_ENABLE_PROFILING = "0"
  $Vars.OTEL_SDK_DISABLED = "true"
  $Vars.OTEL_TRACES_EXPORTER = "none"
  $Vars.OTEL_METRICS_EXPORTER = "none"
  $Vars.OTEL_LOGS_EXPORTER = "none"
}
$Filter = "system.applicationHost/applicationPools/add[@name='$Pool']/environmentVariables"
foreach ($Name in @($Vars.Keys) + @("COR_ENABLE_PROFILING", "CORECLR_ENABLE_PROFILING", "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] }
}
Restart-WebAppPool -Name $Pool
  1. Sitede birkaç sayfa açın; C:\ProgramData\OpenTelemetry .NET AutoInstrumentation\logs altında w3wp log dosyaları oluşur.
Dikkat

Register-OpenTelemetryForIIS makinedeki bütün application pool'ları etkiler. Toplanmasını istemediğiniz pool'lar için 2. adımı $IS_OTEL_ENABLED = "false" ile çalıştırın.

Windows: servis

  1. Yönetici PowerShell'de, <windows-service> yerine servisin adını (Get-Service listesindeki Name) yazıp çalıştırın:
powershell
Import-Module C:\spitfire-otel\OpenTelemetry.DotNet.Auto.psm1
$Service = "<windows-service>"
$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>"
)
# Özel CA: $Otel += "OTEL_EXPORTER_OTLP_CERTIFICATE=C:\spitfire-otel\ca.pem"
if ($IS_OTEL_ENABLED -ne "true") { $Otel += "OTEL_SDK_DISABLED=true" }
$Key = "HKLM:\SYSTEM\CurrentControlSet\Services\$Service"
$Keep = @((Get-ItemProperty $Key).Environment | Where-Object { $_ -and $_ -notmatch '^(IS_OTEL_ENABLED|OTEL_(?!DOTNET_AUTO_)|NO_PROXY)=' })
Set-ItemProperty $Key -Name Environment -Type MultiString -Value ($Keep + $Otel)
if ($IS_OTEL_ENABLED -eq "true") {
  Register-OpenTelemetryForWindowsService -WindowsServiceName $Service -OTelServiceName "<service-name>"
} else {
  Unregister-OpenTelemetryForWindowsService -WindowsServiceName $Service
}
  1. C:\ProgramData\OpenTelemetry .NET AutoInstrumentation\logs altında servisin süreç adıyla log dosyaları oluşur.

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 8. adım, Docker 5. adım, Kubernetes 4. adım ya da Windows betiğini "false" ile yeniden çalıştırın).
  2. Kaldırmak: Linux'ta sudo systemctl revert <unit> ve sudo rm -r /opt/otel-dotnet-auto /opt/spitfire-otel /etc/spitfire-otel; Docker'da Dockerfile'a eklenen satırları silin; Windows'ta Unregister-OpenTelemetryForIIS ya da Unregister-OpenTelemetryForWindowsService -WindowsServiceName <windows-service>, ardından Uninstall-OpenTelemetryCore ve C:\spitfire-otel'i silin.

Sık karşılaşılan sorunlar

Belirti Neden Çözüm
Log klasörü boş Profiler yüklenmedi IS_OTEL_ENABLED true mu; IIS'te Register-OpenTelemetryForIIS çalıştı mı; DOTNET_EnableDiagnostics=0 var mı
.NET 6/7 servis 1.18.0 ile başlamıyor ya da veri yok 1.18.0 .NET 6/7'yi desteklemez 1.9.0 ile yeniden kurun
.NET Framework 4.5 uygulamasında veri yok 4.6.2 altı desteklenmez Uygulamayı 4.6.2+'ya taşıyın
Linux ARM64'te "CLR profiler was not correctly loaded" ARM64 profiler glibc 2.33+ ister; Debian 11 (ör. .NET 6 6.0 image'ları) 2.31'dir Ubuntu 22.04+ tabanı (ör. 6.0-jammy image) ya da x64 sunucu kullanın
gh bulunamadı hatası 1.18.0 imza doğrulaması GitHub CLI ister gh kurun ya da SKIP_RELEASE_VERIFICATION=true / -SkipReleaseVerification kullanın
Trace, metrik gelmiyor Adres, token ya da ağ Doğrulama adımlarını uygulayın

İlgili sayfalar