Node.js servisini OTel ile bağlamak

@opentelemetry/auto-instrumentations-node koda dokunmadan trace, metrik ve log toplar. Değerler ve genel kurallar: Servisleri OTel ile bağlamak: genel.

#Sürüm tablosu

Sürümünüzü bulun: servisin kullandığı Node.js ile node --version.

Aşağıdaki komutlarda 0.82.0 ve api@1.10.0 yazılıdır; bandınız 18/20/22.0–22.14 ise 0.81.2 ve api@1.9.1 yazın.

Doğrulandı: 2026-11-02. Kaynak: desteklenen çalışma ortamları, npm sayfası (engines), paket 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)

1. Uygulamanın klasöründe (package.json'ın olduğu yer) paketleri kurun:

npm install --save @opentelemetry/auto-instrumentations-node@0.82.0 @opentelemetry/api@1.10.0
sudo mkdir -p /opt/spitfire-otel /etc/spitfire-otel

2. /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

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

#!/bin/sh
# IS_OTEL_ENABLED=true: OTel --require ile yüklenir; başka her değer: yüklenmez, SDK kapalı.
if [ "$IS_OTEL_ENABLED" = "true" ]; then
  export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register ${NODE_OPTIONS:-}"
else
  export OTEL_SDK_DISABLED=true
fi
exec "$@"

5. Çalıştırılabilir yapın: sudo chmod 755 /opt/spitfire-otel/otel-run
6. Servisin şimdiki başlatma komutunu bulun: systemctl cat <unit> | grep ^ExecStart
7. 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; WorkingDirectory uygulamanın klasörü olmalı):

[Service]
EnvironmentFile=/etc/spitfire-otel/<service-name>.env
WorkingDirectory=/srv/app
ExecStart=
ExecStart=/opt/spitfire-otel/otel-run /usr/bin/node /srv/app/server.js

8. Yeniden başlatın: sudo systemctl daemon-reload && sudo systemctl restart <unit>
9. Yüklendiğini görün: journalctl -u <unit> -n 50 çıktısında Cannot find module '@opentelemetry/auto-instrumentations-node/register' hatası olmamalıdır.

#Docker

1. otel-run dosyasını (Linux 4. adım) Dockerfile'ın yanına koyun.
2. Dockerfile'a ekleyin (npm install'dan sonra, WORKDIR uygulamanın klasörü); ENTRYPOINT'in başına /opt/spitfire-otel/otel-run gelir, gerisi sizin komutunuzdur:

RUN npm install --save @opentelemetry/auto-instrumentations-node@0.82.0 @opentelemetry/api@1.10.0
COPY --chmod=755 otel-run /opt/spitfire-otel/otel-run
ENTRYPOINT ["/opt/spitfire-otel/otel-run", "node", "server.js"]

3. Ortam dosyasını (Linux 2. 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 2. 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 (servis)

1. Uygulamanın klasöründe (package.json'ın olduğu yer) paketleri kurun:

npm install --save @opentelemetry/auto-instrumentations-node@0.82.0 @opentelemetry/api@1.10.0

2. Servis uygulamanın klasöründe başlamalı (NSSM'de: nssm set <windows-service> AppDirectory C:\app; başka bir sarmalayıcıda onun çalışma klasörü ayarı).
3. Yönetici PowerShell'de <windows-service> yerine servisin adını (Get-Service listesindeki Name) yazıp çalıştırın:

$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 += "NODE_OPTIONS=--require @opentelemetry/auto-instrumentations-node/register"
} 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_|NODE_OPTIONS|NO_PROXY)=' })
Set-ItemProperty $Key -Name Environment -Type MultiString -Value ($Keep + $Otel)
Restart-Service -Name $Service -Force

4. Yüklendiğini görün: servisin logunda Cannot find module '@opentelemetry/auto-instrumentations-node/register' hatası olmamalı.

#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>, sudo rm -r /opt/spitfire-otel /etc/spitfire-otel ve npm uninstall @opentelemetry/auto-instrumentations-node @opentelemetry/api; 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

#İlgili sayfalar

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