Spitfirev0.71.0 · Yenilikler

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

Java servisini OTel ile bağlamak

OpenTelemetry Java agent'ı (-javaagent) koda dokunmadan trace, metrik ve log toplar. Değerler ve genel kurallar: Servisleri OTel ile bağlamak: genel.

Sürüm tablosu

Java Agent Not
8, 11, 17, 21, 25 ve sonrası opentelemetry-javaagent.jar 2.33.1 Tüm bantlar aynı agent'ı kullanır
7 ve öncesi desteklenmiyor Java 8+'a yükseltin ya da yalnız sunucu metrikleri: Collector

Sürümünüzü bulun: java -version.

Doğrulandı: 2026-11-02. Kaynak: desteklenen JVM'ler (OpenJDK ve OpenJ9: 8, 11, 17, 21, 25, 27), sürüm 2.33.1.

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. Agent'ı indirin:
bash
sudo mkdir -p /opt/spitfire-otel /etc/spitfire-otel
sudo curl -sSfL -o /opt/spitfire-otel/opentelemetry-javaagent.jar \
  https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v2.33.1/opentelemetry-javaagent.jar
sudo chmod 644 /opt/spitfire-otel/opentelemetry-javaagent.jar
  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: agent yüklenir; başka her değer: agent yüklenmez, SDK kapalı.
if [ "$IS_OTEL_ENABLED" = "true" ]; then
  export JAVA_TOOL_OPTIONS="-javaagent:/opt/spitfire-otel/opentelemetry-javaagent.jar ${JAVA_TOOL_OPTIONS:-}"
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/java -jar /srv/app/app.jar
  1. Yeniden başlatın: sudo systemctl daemon-reload && sudo systemctl restart <unit>
  2. Agent'ın yüklendiğini görün: journalctl -u <unit> -n 200 | grep opentelemetry-javaagent (opentelemetry-javaagent - version: 2.33.1 satırı).
Not

Tomcat, WildFly ya da kendi betiğiyle başlayan uygulamalarda da aynı yol çalışır: JVM JAVA_TOOL_OPTIONS'ı kendisi okur.

Docker

  1. otel-run dosyasını (Linux 4. adım) Dockerfile'ın yanına koyun.
  2. Dockerfile'a ekleyin; ENTRYPOINT'in başına /opt/spitfire-otel/otel-run gelir, gerisi sizin komutunuzdur:
dockerfile
ADD --chmod=644 https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v2.33.1/opentelemetry-javaagent.jar /opt/spitfire-otel/opentelemetry-javaagent.jar
COPY --chmod=755 otel-run /opt/spitfire-otel/otel-run
ENTRYPOINT ["/opt/spitfire-otel/otel-run", "java", "-jar", "/app/app.jar"]
  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 (servis)

  1. C:\spitfire-otel klasörünü açın; agent'ı indirin (https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v2.33.1/opentelemetry-javaagent.jar) ve C:\spitfire-otel\opentelemetry-javaagent.jar olarak koyun.
  2. PowerShell'i yönetici olarak açın, <windows-service> yerine servisin adını (Get-Service listesindeki Name) yazıp çalıştırın:
powershell
$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 -eq "true") {
  $Otel += "JAVA_TOOL_OPTIONS=-javaagent:C:\spitfire-otel\opentelemetry-javaagent.jar"
} 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_|JAVA_TOOL_OPTIONS|NO_PROXY)=' })
Set-ItemProperty $Key -Name Environment -Type MultiString -Value ($Keep + $Otel)
Restart-Service -Name $Service -Force
  1. Servisin logunda opentelemetry-javaagent - version: 2.33.1 satırını görü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 8. 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 <unit> ve sudo rm -r /opt/spitfire-otel /etc/spitfire-otel; Docker'da Dockerfile'a eklenen üç satırı silin; Windows'ta servisin Environment değerinden OTel satırlarını silip C:\spitfire-otel'i kaldırın.

Sık karşılaşılan sorunlar

Belirti Neden Çözüm
Logda opentelemetry-javaagent satırı yok otel-run çalışmadı ya da IS_OTEL_ENABLED true değil systemctl cat <unit>'te iki ExecStart satırı ve EnvironmentFile var mı bakın
Picked up JAVA_TOOL_OPTIONS iki kez agent gösteriyor Uygulama zaten -javaagent ile başlıyor Eski -javaagent parametresini kaldırın
Image'da /bin/sh yok (distroless) otel-run çalışamaz ENTRYPOINT'i değiştirmeyin; ortam dosyasına JAVA_TOOL_OPTIONS=-javaagent:/opt/spitfire-otel/opentelemetry-javaagent.jar ekleyin; kapatmak için OTEL_JAVAAGENT_ENABLED=false
Trace, metrik gelmiyor Adres, token ya da ağ Doğrulama adımlarını uygulayın

İlgili sayfalar