Node.js Observability: OpenTelemetry + Sentry Kurulumu

Node.js tarafında "hata takibi" ile "observability" artık aynı şey değil. Bir isteğin hangi Prisma sorgusunda yavaşladığını, hangi dış API çağrısının timeout'a girdiğini görmek istiyorsan trace, log ve metrik üçlüsüne ihtiyacın var — sadece Sentry'nin klasik hata yakalama moduna değil. Bu yazı Node.js OpenTelemetry Sentry izlenebilirlik kurulumunu, @sentry/node 11.x'in OpenTelemetry çekirdeğinden Next.js instrumentation.ts ayrımına, Prisma span'lerinden örnekleme ve alert stratejisine kadar uçtan uca, gerçek kod örnekleriyle anlatıyor.

💡 Pro Tip: enableOpenTelemetrySetup bayrağını değiştirmeden önce projede zaten bir OTel pipeline'ı olup olmadığını kontrol et — ikisini aynı anda açık bırakmak her işlem için iki ayrı span üretir ve trace'ler asla birleşmez.

İçindekiler

• 2026'da Observability Minimum Seti (Trace + Log + Metrik)
• Neden Şimdi Değişti
• @sentry/node 11'in OpenTelemetry Çekirdeği
• instrumentation.ts ve instrumentation-client.ts Ayrımı
• Mevcut OTel Span'lerini Sentry'ye Yollamak
• Prisma/Postgres Sorgularını Span'lere Bağlamak
• Örnekleme (Sampling) ve Maliyet Kontrolü
• Alert Kurmak: Neyi Alarmlamalı, Neyi Asla
• Self-Host Senaryosunda Kurulum
• SSS
• Node.js'te OpenTelemetry ile Sentry nasıl birlikte kullanılır?
• Mevcut OTel trace'lerimi Sentry'ye nasıl gönderirim?
• Next.js'te instrumentation dosyası nasıl kurulur?
• Sentry mi OTel collector mı — hangisi gerekli?
• Hangi Node.js sürümü gerekiyor?
• Sonuç
• Kaynaklar

2026'da Observability Minimum Seti (Trace + Log + Metrik)

Modern bir Node.js servisinde "gözlemlenebilir" olmak üç sinyalin birlikte toplanmasını gerektirir: trace (bir isteğin sistem içindeki yolculuğu, span'lerden oluşur), log (yapılandırılmış olay kayıtları) ve metrik (sayaç/histogram türünden zaman serisi veriler). Sentry tarihsel olarak hata yakalamayla başladı; OpenTelemetry ise baştan itibaren bu üç sinyali vendor-nötr bir standart altında topluyor. 2026'da bu iki dünyanın kesişimi artık zorunlu: tek başına hata mesajı, bir isteğin neden yavaş olduğunu göstermez — span ağacı gösterir.

Neden Şimdi Değişti

@sentry/node paketinin npm latest etiketi 2026-09-23 itibarıyla 11.0.0. GitHub üzerindeki getsentry/sentry-javascript deposunun 11.0.0 release sayfası da aynı sürümü doğruluyor. Bu major sürümde OpenTelemetry artık SDK'nın arka planında gizli bir detay değil, doğrudan yapılandırdığın bir katman: v10'da opt-in olan orchestrion tabanlı channel instrumentasyonu (import-in-the-middle yerine) varsayılan oldu — çalışma ve derleme zamanında enstrümantasyonu açıyor; Vercel/Netlify gibi hedeflerde tracing bu yüzden çalışıyor. Span streaming varsayılan oldu ve minimum desteklenen Node sürümü 20.19.0'a yükseldi (@sentry/node@11.0.0 paketinin engines alanı: >=20.19.0 <22.0.0 || >=22.12.0 <23.0.0 || >=23.2.0). Kendi sürümünü node -v ile kontrol et; çıktı bu aralıklardan birine giriyorsa uyumlusun.

Buna karşılık @opentelemetry/sdk-node paketi hâlâ 0.222.0 ile 0.x sürüm bandında — OpenTelemetry JS'in trace API/SDK spesifikasyonu kararlı sayılsa da paket sürüm numarası henüz 1.0'a geçmedi. Bu ayrım önemli: Sentry major sürüm atlarken (10'dan 11'e), OTel paketleri sürüm numaralandırmasında hâlâ 0.x'te — versiyon uyumsuzluğu sanma, bu iki proje ayrı kadanslarda ilerliyor.

@sentry/node 11'in OpenTelemetry Çekirdeği

@sentry/node 11.0.0'ın en büyük mimari değişikliği, OpenTelemetry'nin artık gizli bir uygulama detayı değil, seçilebilir bir mod olması. SDK üç senaryoyu destekliyor:

Migration dokümanı bu üçünü "Choosing an OpenTelemetry setup" başlığı altında net biçimde ayırıyor — kararını projenin mevcut altyapısına göre ver, ikisini aynı anda açık bırakma.

Basit senaryoda (Sentry'nin kendi OTel-uyumlu setup'ını kullanmak) kurulum şu şekilde başlar:

1npm install @sentry/node --save

1// sentry.server.config.ts
2import * as Sentry from "@sentry/node";
3 
4Sentry.init({
5  dsn: process.env.SENTRY_DSN,
6  enableOpenTelemetrySetup: true,
7  tracesSampleRate: 0.2,
8  dataCollection: {
9    // v10 davranışını korumak için bu kategoriyi açıkça kapatıyoruz
10    databaseQueryData: false,
11  },
12});

Dikkat edilecek nokta dataCollection.databaseQueryData. Migration dokümanına göre sendDefaultPii tamamen kaldırıldı; yerine her kategoriyi tek tek ayarlayan dataCollection geldi ve hiç ayarlanmadığında v10'dan geniş veri topluyor: databaseQueryData varsayılanı v10'da false, v11'de true. Sorgu içeriği (potansiyel PII) artık varsayılan toplandığından örnekte eski davranışı korumak için alanı false yaptım.

instrumentation.ts ve instrumentation-client.ts Ayrımı

Next.js'te Sentry kurulumunun en çok karıştırılan kısmı, hangi dosyanın hangi runtime'da çalıştığı. Resmi kurulum aracı bunu otomatik ayırır:

1npx @sentry/wizard@latest -i nextjs

Wizard üç ayrı init dosyası oluşturur ve bunları tek bir kök dosyaya bağlar:

• instrumentation-client.ts: Tarayıcıda çalışır, client-side Sentry SDK'sını başlatır.
• sentry.server.config.ts: Node.js runtime'ında çalışır, sunucu tarafı hata/trace yakalamasını kurar.
• sentry.edge.config.ts: Edge runtime'da çalışır (middleware, edge route'lar).
• instrumentation.ts: Next.js'in kendi framework hook'u — yukarıdaki üç dosyayı runtime'a göre import eden kök dosya.

Migration dokümanına göre enableOpenTelemetrySetup çoğu sunucu SDK'sinde false, @sentry/nextjs ve @sentry/sveltekit'te true varsayılanlı. Kendi OTel pipeline'ına geçeceksen Next.js'te bu bayrağı açıkça false yapman gerekir — aksi halde Sentry kendi tracer provider'ını kaydeder ve üçüncü kurulum yerine ikinciye düşersin.

Mevcut OTel Span'lerini Sentry'ye Yollamak

Zaten bir OpenTelemetry pipeline'ın varsa (kendi NodeTracerProvider'ını kuruyorsan), Sentry'yi paralel bir tracing sistemi olarak değil, mevcut pipeline'a bağlı bir hata/log kaynağı olarak eklemen gerekir. Bunun resmi yolu getOtlpTracesEndpoint(): DSN'inden Sentry'nin OTLP adresini ve auth header'larını türetip OTLPTraceExporter'a verilecek yapılandırmayı döndürür — URL string'i değil:

1npm install @opentelemetry/sdk-trace-node @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-http

1// otel-setup.ts
2import * as Sentry from "@sentry/node";
3import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
4import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
5import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
6 
7const dsn = process.env.SENTRY_DSN!;
8const endpoint = Sentry.getOtlpTracesEndpoint(dsn);
9 
10if (!endpoint) {
11  throw new Error("Could not parse the Sentry DSN");
12}
13 
14const provider = new NodeTracerProvider({
15  spanProcessors: [new BatchSpanProcessor(new OTLPTraceExporter(endpoint))],
16});
17provider.register();
18 
19Sentry.init({
20  dsn,
21  enableOpenTelemetrySetup: false,
22  integrations: [Sentry.openTelemetryIntegration()],
23});

Bu senaryoda tracesSampleRate ayarlamıyoruz — örnekleme kararı artık OTel sampler'ının sorumluluğunda, Sentry sadece zaten üretilmiş span'lere hata/log ekliyor.

Prisma/Postgres Sorgularını Span'lere Bağlamak

Bir isteğin yavaş olduğunu görmek yeterli değil — hangi Prisma sorgusunun bu yavaşlığa sebep olduğunu görmen gerekir. Sentry-native yolda (birinci/ikinci kurulum) Prisma prismaIntegration ile kutudan çıktığı gibi enstrümante; aşağıdaki kurulum yalnızca kendi OTel pipeline'ın için geçerli. Bunun için Prisma'nın resmi OTel entegrasyonu @prisma/instrumentation paketini kullanıyorsun:

1npm install @prisma/instrumentation

1// otel-setup.ts (yukarıdaki provider kurulumuna ek)
2import { PrismaInstrumentation, registerInstrumentations } from "@prisma/instrumentation";
3 
4registerInstrumentations({
5  instrumentations: [new PrismaInstrumentation()],
6});

Bu instrumentasyon aktif olduğunda span ağacı şu hiyerarşiyi üretir: prisma:client:operation (senin çağırdığın prisma.user.findMany() gibi bir metod) bunun altındaki ağaçta (arada prisma:engine:query gibi span'lerle) prisma:engine:db_query (gerçek SQL sorgusu) span'i açılır. Prisma dokümantasyonu bu instrumentasyonun 4.2.0–6.1.0 sürüm aralığında preview feature olarak previewFeatures = ["tracing"] şemasında etkinleştirilmesi gerektiğini, sonraki sürümlerde ise doğrudan kullanılabildiğini belirtiyor — projenin Prisma sürümünü package.json'dan kontrol edip buna göre şema ayarını yapman gerekir.

Örnekleme (Sampling) ve Maliyet Kontrolü

Sentry'de üç ayrı örnekleme kavramı var ve bunları karıştırmak ya çok fazla veri gönderip maliyeti şişirir ya da hiç trace görmemene neden olur:

Kendi OTel pipeline'ını kullandığın senaryoda (yukarıdaki enableOpenTelemetrySetup: false kurulumu) tracesSampleRate ayarlamıyorsun — örnekleme kararı OTLP exporter'a giden veriden önce, OTel Sampler katmanında veriliyor. Yani iki ayrı örnekleme mekanizmasını karıştırıp hem Sentry'de hem OTel tarafında sınırlama koymaya çalışmak, verinin nerede kesildiğini takip edilemez hale getirir. Kuralı basit tut: entegrasyon yöntemi Sentry-native ise Sentry'nin tracesSampleRate'i, kendi OTel pipeline'ın varsa OTel sampler'ı tek otorite olsun.

Sentry-native yolda sabit bir oran yerine koşullu karar vermek istersen tracesSampler fonksiyonunu kullanabilirsin. Yaygın bir pratik, health-check gibi gürültü üreten endpoint'leri örneklemeden tamamen dışlamak:

1import * as Sentry from "@sentry/node";
2 
3Sentry.init({
4  dsn: process.env.SENTRY_DSN,
5  enableOpenTelemetrySetup: true,
6  tracesSampler: ({ attributes, inheritOrSampleWith }) =>
7    inheritOrSampleWith(attributes?.["url.path"] === "/health" ? 0 : 0.2),
8});

Buradaki tuzak v11'e özgü: tracesSampler span başlamadan koştuğu için Express rotayı henüz eşleştirmemiştir — http.server span'inin adı o anda GET /health değil, sadece GET'tir. Migration dokümanının uyardığı gibi ad bazlı kurallar sessizce eşleşmeyi bırakır: ne hata ne uyarı, yalnızca beklenmedik kota kullanımı. Ada değil url.path özniteliğine bak.

Alert Kurmak: Neyi Alarmlamalı, Neyi Asla

Trace ve span topladıktan sonraki adım, bu veriyi gerçek bir uyarıya dönüştürmek. Sentry'nin alert kurulum modeli üç parçadan oluşur: trigger (koşulun ne zaman kontrol edileceği), filter (koşulun hangi verilere uygulanacağı) ve action (koşul karşılandığında ne yapılacağı — e-posta, Slack, webhook). Resmi örnek senaryolar arasında downtime tespiti, ani trafik sıçraması ve hata eşiği aşımı yer alıyor.

Pratik kural şu: her span'i değil, kullanıcıyı etkileyen eşikleri alarmla. Tek bir yavaş Prisma sorgusu için anlık alert kurmak gürültü üretir; bunun yerine p95 gecikme eşiği aşıldığında veya belirli bir hata oranı sürekli hale geldiğinde tetiklenen bir trigger kur. Alarmlanmaması gereken şey, tek seferlik ve kendi kendine düzelen anomaliler — örneğin bir deploy sırasında kısa süreli cold-start gecikmesi. Bunun için alert kuralına bir süre penceresi (örneğin 5 dakika) ve minimum tekrar sayısı ekleyerek gürültüyü filtrelemen gerekir.

Self-Host Senaryosunda Kurulum

Kendi sunucunda Sentry çalıştırıyorsan (SaaS Sentry değil), @sentry/node 11.0.0'ı kullanmadan önce kontrol etmen gereken tek şart self-hosted Sentry sürümü: migration dokümanı, bu SDK sürümünün self-hosted Sentry 26.4.2 veya üzeri gerektirdiğini belirtiyor. Daha eski bir self-host sürümüyle 11.x SDK'yı eşleştirmek, span/veri şeması uyumsuzluğuna yol açabilir.

Kurulum adımları self-host'ta SaaS'tan farklı değil — tek fark dsn değerinin kendi sunucunun ingest endpoint'ini göstermesi ve getOtlpTracesEndpoint() çağrısının da yine bu özel DSN'i kullanması:

1const dsn = "https://<public_key>@sentry.kendi-sunucun.com/<project_id>";
2 
3Sentry.init({
4  dsn,
5  enableOpenTelemetrySetup: true,
6  tracesSampleRate: 0.1,
7});

Self-host'ta yükseltme öncesi Sentry sunucu sürümünü doğrulamak, SDK'yı güncelledikten sonra veri akışının kesilmesini engelleyen en ucuz kontrol adımıdır:

1docker compose exec web sentry --version

Bu komutun çıktısı 26.4.2'nin altındaysa, önce self-hosted Sentry kurulumunu güncellemen gerekir — aksi halde @sentry/node 11.x'in gönderdiği veri şeması sunucu tarafında tam olarak işlenemeyebilir.

SSS

Node.js'te OpenTelemetry ile Sentry nasıl birlikte kullanılır?

Sentry v11'de üç yöntem var: yalnız Sentry kullanmak (varsayılan, OTel hiç devreye girmez), enableOpenTelemetrySetup: true ile Sentry'nin kendi hafif OTel-uyumlu tracer provider'ını kurdurmak, veya kendi OTel pipeline'ını (NodeTracerProvider/NodeSDK) kurup Sentry.openTelemetryIntegration() ile hataları/logları aktif span'a bağlamak. Hangisini seçeceğin, projede zaten bir OTel collector olup olmamasına bağlı.

Mevcut OTel trace'lerimi Sentry'ye nasıl gönderirim?

Kendi NodeTracerProvider'ına bir BatchSpanProcessor ekle; içindeki OTLPTraceExporter'a Sentry.getOtlpTracesEndpoint(dsn)'in döndürdüğü URL + auth header yapılandırmasını ver, provider.register() çağır, ardından Sentry.init({ dsn, enableOpenTelemetrySetup: false, integrations: [Sentry.openTelemetryIntegration()] }) yap. tracesSampleRate ayarlama — örnekleme kararı OTel sampler'ında kalır.

Next.js'te instrumentation dosyası nasıl kurulur?

npx @sentry/wizard@latest -i nextjs çalıştırılır; wizard instrumentation-client.ts (tarayıcı), sentry.server.config.ts (Node.js) ve sentry.edge.config.ts (edge runtime) dosyalarını oluşturur, bunları Next.js'e bağlayan kök dosya ise instrumentation.ts'tir. Next.js SDK'sinde enableOpenTelemetrySetup varsayılan olarak true'dur.

Sentry mi OTel collector mı — hangisi gerekli?

Birbirinin rakibi değil, tamamlayıcısı. Sentry hata/log/cron takibi ve hazır bir dashboard sağlar, OpenTelemetry ise vendor-nötr trace/metrik/log üretim standardıdır. Yalnızca Sentry kullanan projelerin OTel'e ihtiyacı yoktur (varsayılan mod). Zaten bir OTel collector'a (Grafana, Datadog, Jaeger gibi) veri gönderen projeler Sentry'yi paralel bir pipeline olarak değil, openTelemetryIntegration() ile mevcut trace'e bağlı bir hata/log kaynağı olarak eklemeli — ikisini aynı anda tracing modunda açık bırakmak, aynı işlem için iki ayrı span üretir ve bu iki pipeline hiçbir zaman birleşmez.

Hangi Node.js sürümü gerekiyor?

@sentry/node 11.0.0 için minimum desteklenen sürüm 20.19.0. Paketin engines alanı >=20.19.0 <22.0.0 || >=22.12.0 <23.0.0 || >=23.2.0 aralığını belirtiyor — bu aralığın dışındaki Node sürümleriyle kurulum uyarı verebilir veya beklenmeyen şekilde davranabilir.

Sonuç

Node.js'te observability kurulumu artık tek bir SDK'yı init etmekten ibaret değil; hangi entegrasyon yolunu seçtiğine bağlı üç farklı mimari kararı beraberinde getiriyor. Next.js kullanıyorsan Next.js 16.3'te runtime='edge' Bitti: Node'a Dönüş yazısı, instrumentation.ts'in hangi runtime'larda çalıştığını daha derinden anlamana yardımcı olur; cache ve navigation tarafında yeni davranışlar için Next.js 16.3 Instant Navigations ve Cache Components Rehberi faydalı olacaktır.

Backend tarafında framework seçimi de bu kararları etkiler; serverless bir yapıda çalışıyorsan Hono.js: Serverless Web Framework Production Rehberi 2026 mimarine uygun instrumentasyon noktalarını görmek için iyi bir başlangıç. API tasarımında hata/loglama sözleşmesini netleştirmek istersen REST API Tasarım Prensipleri: Kaynak, Hata, Pagination yazısına bakabilirsin. Mobil tarafta benzer bir izlenebilirlik disiplini kurmak istiyorsan iOS Performance Monitoring & Observability Rehberi ve iOS Crash Reporting ve Analytics: Production Kalite Rehberi yazıları, aynı prensiplerin mobil karşılığını gösteriyor.

Kurulumu bitirdikten sonra tek bir isteği uçtan uca izleyip trace görünümünde beklediğin span sayısını gördüğünden emin ol — bu, kurulumun gerçekten çalıştığının en güvenilir kanıtı.

Kaynaklar

• npm: @sentry/node — güncel sürüm ve engines bilgisi (dist-tags latest)
• npm: @opentelemetry/sdk-node — güncel sürüm bilgisi (dist-tags latest)
• GitHub: sentry-javascript 11.0.0 Release — resmi release notu
• Sentry MIGRATION.md — 10'dan 11'e geçiş rehberi, OpenTelemetry setup seçimi
• Sentry Docs: Node.js OpenTelemetry — genel entegrasyon rehberi
• Sentry Docs: Custom OpenTelemetry Setup — getOtlpTracesEndpoint kullanımı
• Sentry Docs: Next.js — instrumentation.ts ve dosya ayrımı
• OpenTelemetry JS Docs — resmi dil rehberi