Sentry.io Nedir? Next.js ve Nest.js Projelerinde Hata ve Performans İzleme

Bir uygulamayı canlıya aldığınızda işin zor kısmı çoğu zaman kodu yazmak değil, çalışırken neler olduğunu anlamaktır. Kullanıcı "sayfa açılmıyor" dediğinde hangi istekte, hangi tarayıcıda, hangi sürümde ve hangi veriyle sorun çıktığını bilmek isteriz. sentry.io tam olarak bu boşluğu kapatmak için geliştirilmiş bir hata ve performans izleme platformudur. Bu yazıda Sentry'nin ne olduğunu, hangi özellikleri sunduğunu, hangi projelerde hangi amaçla kullanılabileceğini ve Next.js ile Nest.js tarafında nasıl kurulduğunu anlatacağım.

Sentry.io nedir?

Sentry, uygulamanızda oluşan hataları ve performans sorunlarını toplayan, bunları düzenleyen ve geliştirici ekibine anlamlı bir biçimde ileten bir izleme (observability) platformudur. Uygulamanız tarafına küçük bir SDK eklenir. Bu SDK, bir istisna (exception) fırlatıldığında, bir promise reddedildiğinde ya da tanımladığınız bir performans ölçümü tamamlandığında olay (event) üretir ve bunu Sentry sunucularına gönderir. Sentry tarafında ise bu olaylar gruplanır, zaman çizelgesine yerleştirilir ve ilgili kişilere bildirim olarak iletilir.

Sentry'nin açık kaynak bir çekirdeği vardır ve kendi sunucunuzda da çalıştırılabilir (self-hosted). Çoğu ekip ise bulut sürümünü tercih eder. Hangi yolu seçerseniz seçin, uygulama tarafındaki entegrasyon büyük ölçüde aynıdır.

Sentry neyi çözüyor?

Sentry öncesinde hata takibi genellikle üç farklı kanaldan yapılır: kullanıcı destek talepleri, sunucu log dosyaları ve tesadüfen fark edilen konsol çıktıları. Bu yaklaşımın sorunları bellidir:

• Kullanıcı hatanın ne olduğunu tam olarak tarif edemez.
• Log dosyaları çoğu zaman bağlamdan yoksundur ve aynı hata binlerce satır arasında kaybolur.
• Frontend hataları sunucu loglarında hiç görünmez.
• Bir hatanın ilk ne zaman başladığı, hangi sürümle geldiği ve kaç kullanıcıyı etkilediği bilinmez.

Sentry bu tabloyu değiştirir. Bir hata oluştuğunda elinizde şu bilgiler olur: stack trace, hatanın oluştuğu dosya ve satır, istek bilgileri, kullanıcının o anki adımlarını gösteren breadcrumb kayıtları, tarayıcı ya da işletim sistemi bilgisi, uygulama sürümü ve hatanın kaç kez tekrarlandığı. Bu bağlam sayesinde bir hatayı tekrar üretmeden önce büyük ölçüde anlayabilirsiniz.

Temel kavramlar

Sentry ile çalışmaya başlamadan önce birkaç temel terimi bilmek işinizi kolaylaştırır:

• DSN (Data Source Name): SDK'nın olayları hangi projeye göndereceğini belirleyen adres. Gizli kabul edilmemesi gerekir, ama yine de ortam değişkeni olarak tutmak iyi bir pratiktir.
• Event (olay): Tek bir hata ya da ölçüm kaydı.
• Issue (sorun): Benzer olayların gruplanmasıyla oluşan üst kayıt. Aynı hata yüzlerce kez tetiklense bile tek bir issue altında toplanır.
• Stack trace: Hatanın çağrı zincirini gösteren kayıt.
• Breadcrumb: Hatadan önce gerçekleşen olayların izi; tıklamalar, HTTP istekleri, konsol mesajları gibi.
• Source map: Minify edilmiş JavaScript kodunun stack trace'ini orijinal kaynak koduna geri çeviren dosya. Üretim derlemelerinde hatayı anlamlı kılan en kritik parçalardan biridir.
• Environment ve release: Olayların hangi ortamdan (production, staging) ve hangi uygulama sürümünden geldiğini ayırmanızı sağlar.
• Fingerprint ve grouping: Olayların hangi kurallarla gruplanacağını belirler. Gerekirse özel kurallar yazılabilir.

Sentry'nin temel özellikleri

Sentry'nin sunduğu özellikler zamanla genişlemiştir. Pratikte en sık kullanılanları şunlardır:

Error Monitoring

Yakalanmamış istisnaların ve manuel olarak raporladığınız hataların takibi. Issue listesi, önceliklendirme, atama, çözüldü olarak işaretleme ve yeniden açılma (regression) gibi süreçleri destekler.

Performance Monitoring (Tracing)

İstekleri, veritabanı sorgularını, dış API çağrılarını ve frontend sayfa yüklemelerini izler. Hangi endpoint'in yavaş olduğunu, yavaşlığın nerede oluştuğunu (ağ, veritabanı, uygulama kodu) görmenizi sağlar. Dağıtık sistemlerde servisler arası trace'leri de birleştirebilir.

Session Replay

Kullanıcının tarayıcıdaki oturumunu video benzeri bir biçimde yeniden oynatmanıza olanak tanır. Hassas alanların maskelenmesi kritik olduğu için bu özelliği açmadan önce gizlilik ayarlarını dikkatle yapılandırmak gerekir.

Profiling

CPU kullanımı ve fonksiyon düzeyinde çalışma süresi gibi verileri toplayarak performans darboğazlarının kod seviyesinde tespit edilmesine yardımcı olur.

Cron Monitoring ve Uptime

Zamanlanmış görevlerin (cron job) çalışıp çalışmadığını, beklenen süreden uzun sürüp sürmediğini takip eder. Belirli servislerin erişilebilirliğini izlemek için de kullanılabilir.

Alert ve iş akışları

Belirli koşullar gerçekleştiğinde (örneğin yeni bir issue açıldığında ya da bir hatanın belirli bir eşiği aştığında) e-posta, Slack, Microsoft Teams veya benzeri kanallara bildirim gönderebilirsiniz. Bildirim kurallarını iyi kurmak, gürültüyü azaltmanın en etkili yoludur.

Release takibi ve sağlık metrikleri

Yeni bir sürüm yayınladığınızda hata oranının arttı mı azaldı mı olduğunu karşılaştırabilirsiniz. Dağıtım sonrası gözlemi bu nedenle çok değerlidir.

Hangi projelerde hangi amaçla kullanılır?

Sentry her türlü yazılım projesinde işe yarar, ancak her projede odak noktası farklıdır.

Next.js uygulamaları

Next.js, hem istemci tarafında (React bileşenleri, tarayıcı olayları) hem sunucu tarafında (Server Components, Route Handlers, Server Actions, middleware) çalışan bir yapıdır. Bu nedenle hataların nerede oluştuğunu ayırt etmek zorlaşabilir. Sentry'nin Next.js entegrasyonu bu ayrımı otomatik olarak yapar ve olayları hem istemci hem sunucu bağlamıyla birlikte gösterir. Özellikle şu konularda işe yarar:

• Sayfa yükleme performansının ve Core Web Vitals metriklerinin izlenmesi
• Server Component ve Server Action hatalarının yakalanması
• Source map yükleme ile derlenmiş kodda anlamlı stack trace elde etme
• Hidrasyon (hydration) hatalarının ve istemci tarafı çökmelerin tespiti

Nest.js API'leri

Nest.js ile yazılmış backend servislerinde Sentry en çok HTTP katmanındaki istisnaların yakalanması, veritabanı sorgularının performansının izlenmesi ve arka plan işlerinin (queue, cron) takibi için kullanılır. Modüler mimari sayesinde hata filtreleri ve interceptor'lar üzerinden Sentry'yi merkezi bir noktadan devreye almak mümkündür.

Tek sayfa uygulamalar (React, Vue, Angular)

İstemci tarafı uygulamalarda en büyük sorun, hataların sunucu loglarında görünmemesidir. Sentry'nin tarayıcı SDK'sı, yakalanmamış hataları, reddedilen promise'leri ve konsol olaylarını kaydeder. Sürüm bilgisiyle birlikte kullanıldığında, hangi dağıtımın hangi hatayı getirdiğini net biçimde görürsünüz.

Mobil uygulamalar

React Native, Flutter, iOS ve Android için de SDK'lar mevcuttur. Çökme raporları (crash report), uygulama açılış süresi ve ağ istekleri gibi konularda faydalıdır. Mobil tarafta sembol dosyalarının (dSYM, ProGuard mapping) yüklenmesi önemlidir.

Arka plan işleri ve veri hatları

Kuyruk tüketicileri, zamanlanmış görevler ve ETL süreçleri sessizce başarısız olabilir. Sentry'nin cron izleme özelliği ve manuel hata raporlama, bu tür işlerin görünür olmasını sağlar.

Ekip ve operasyon tarafı

BT ekipleri için Sentry sadece geliştiricilerin değil, operasyonun da aracıdır. Alert kuralları ve atama mekanizması sayesinde hangi hatanın hangi ekibe ait olduğu netleşir. Bu da nöbet (on-call) süreçlerini daha sağlıklı yönetmenize yardımcı olur.

Next.js projesinde kurulum

Next.js için Sentry'nin resmi paketi @sentry/nextjs tir. Sihirbaz (wizard) komutu, gerekli dosyaların büyük kısmını sizin yerinize oluşturur:

npx @sentry/wizard@latest -i nextjs

Kurulum sonrasında projenizde genellikle şu yapılandırmalar bulunur. İstemci tarafındaki temel ayar:

import * as Sentry from '@sentry/nextjs';

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  environment: process.env.NODE_ENV,
  tracesSampleRate: 0.1,
});

Sunucu ve Edge ortamları için instrumentation.ts dosyası kullanılır. Next.js'in güncel sürümlerinde sunucu tarafındaki isteklerde oluşan hataları otomatik yakalamak için onRequestError kancası da bu dosyadan dışa aktarılabilir:

import * as Sentry from '@sentry/nextjs';

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('./sentry.server.config');
  }
  if (process.env.NEXT_RUNTIME === 'edge') {
    await import('./sentry.edge.config');
  }
}

export const onRequestError = Sentry.captureRequestError;

Burada tracesSampleRate değerine dikkat etmek gerekir. Her isteği izlemek hem maliyet hem de gürültü açısından verimsizdir. Üretim ortamında düşük bir oran (örneğin 0.1) ile başlayıp ihtiyaca göre ayarlamak genellikle makul bir yaklaşımdır.

Source map'lerin yüklenmesi için build sürecinde kimlik doğrulama token'ı gerekir. Bu token'ı kesinlikle depoya commit etmeyin; CI/CD ortamının gizli değişkenlerinde saklayın.

Nest.js projesinde kurulum

Nest.js tarafında güncel yaklaşım @sentry/nestjs paketidir. Sentry'nin başlatılması, uygulama modülleri yüklenmeden önce yapılmalıdır. Bu yüzden genellikle ayrı bir instrument.ts dosyası oluşturulur ve bu dosya main.ts içinde en üstte import edilir:

// instrument.ts
import * as Sentry from '@sentry/nestjs';

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.NODE_ENV,
  tracesSampleRate: 0.1,
});

// main.ts
import './instrument';
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(3000);
}
bootstrap();

Sıra önemlidir. Sentry başlatılmadan önce yüklenen modüllerdeki hatalar ve otomatik enstrümantasyon düzgün çalışmayabilir. Ardından Nest'in global hata filtresini Sentry ile birleştirmek için SentryGlobalFilter sağlayıcısını uygulamaya ekleyebilirsiniz. Böylece yakalanmamış HTTP istisnaları Sentry'ye iletilir.

Manuel olarak bağlam eklemek istediğiniz kritik akışlarda ise doğrudan captureException kullanmak mantıklıdır:

import * as Sentry from '@sentry/nestjs';

try {
  await this.paymentService.charge(order);
} catch (err) {
  Sentry.captureException(err, {
    tags: { module: 'payment' },
    extra: { orderId: order.id },
  });
  throw err;
}

Burada tags ve extra alanları, issue'ları filtrelemeniz ve olayın bağlamını anlamanız için değerlidir. Ancak yalnızca ihtiyaç duyduğunuz bilgiyi ekleyin.

Gizlilik ve veri yönetimi

Sentry'ye giden her olay, uygulamanızın bir parçasını taşır. Bu nedenle veri yönetimi konusunda dikkatli olmak gerekir:

• Parolalar, oturum token'ları, kart bilgileri ve kişisel veriler olayların içine sızmamalıdır. Sentry'nin varsayılan veri temizleme (scrubbing) kuralları bir başlangıçtır, ama yeterli olmayabilir.
• sendDefaultPii gibi seçenekleri, uygulamanızın veri işleme politikasına göre bilinçli olarak açıp kapatın.
• beforeSend kancası ile olay göndermeden önce temizleme veya filtreleme yapabilirsiniz.
• Session Replay kullanıyorsanız metin ve medya maskeleme ayarlarını mutlaka gözden geçirin.
• Ekibinizde kimlerin hangi projeye erişebileceğini rol tabanlı olarak yönetin.

KVKK ve GDPR gibi düzenlemelere tabi uygulamalarda Sentry'nin veri saklama bölgesi ve veri işleme sözleşmesi gibi konular da değerlendirilmelidir. Bu kararlar hukuk ve güvenlik ekipleriyle birlikte alınmalıdır.

Maliyet ve örnekleme

Sentry'nin ücretlendirmesi, işlenen olay ve izleme (trace, replay, profil) hacmine göre değişir. Güncel plan ve kotalar için resmi fiyatlandırma sayfasını kontrol etmenizi öneririm; ayrıntılar zaman içinde değişebilir. Maliyeti kontrol altında tutmak için birkaç pratik yol vardır:

• Üretimde performans izlemesi için tracesSampleRate değerini düşük tutun ve kritik endpoint'lerde daha yüksek oran tanımlayın.
• Bilinen ve zararsız hataları (örneğin tarayıcı eklentilerinden kaynaklanan gürültü) ignoreErrors ile filtreleyin.
• Bir hatanın tekrar eden olaylarını izlemek için issue'yu gruplandırma kurallarıyla düzenli tutun.
• Staging ortamı için ayrı bir proje ve daha düşük örnekleme oranı kullanın.

Sık yapılan hatalar

Sentry'yi devreye aldıktan sonra karşılaşılan tipik sorunlar şunlardır:

• Source map'lerin yüklenmemesi: Stack trace'ler minify edilmiş satır ve sütun numaralarıyla kalır. Build aşamasında source map yükleme adımını CI/CD sürecine eklemek gerekir.
• Release bilgisinin eksik olması: Hangi sürümde hata başladı sorusuna cevap veremezsiniz. Release değerini her dağıtımda otomatik olarak üretmek önemlidir.
• Gürültü: Her hatayı alert olarak bildirmek, sonunda bildirimlerin tamamen görmezden gelinmesine yol açar. Alert kurallarını önem derecesine göre ayırın.
• Yanlış ortam ayrımı: Development hatalarının production issue listesine karışması. environment değerini mutlaka doğru tanımlayın.
• Hassas verinin sızması: Yukarıda anlatılan veri temizleme ayarlarının atlanması.
• Başlatma sırası: Nest.js'te instrument.ts dosyasının en üstte import edilmemesi ya da Next.js'te yapılandırma dosyalarının ortama göre yüklenmemesi.

Sentry'nin alternatifleri

Sentry tek seçenek değildir. Bugfender, Rollbar, Bugsnag gibi hata izleme araçları; Datadog, New Relic, Grafana ekosistemi gibi tam kapsamlı gözlemlenebilirlik platformları; bir de OpenTelemetry standardı üzerine kurulu kendi altyapınız alternatiflerdir. Hangi aracı seçeceğiniz, ekibin büyüklüğüne, bütçeye, veri gizliliği gereksinimlerine ve mevcut altyapıya bağlıdır. Küçük ve orta ölçekli ekiplerde Sentry'nin hızlı kurulumu ve geliştirici odaklı arayüzü genellikle öne çıkar. Büyük kurumsal sistemlerde ise log, metrik ve trace'in tek çatı altında toplandığı platformlar daha uygun olabilir.

Sonuç

Sentry.io, uygulamanızın üretimdeki davranışını görünür kılmak için olgun ve kullanımı kolay bir araçtır. Next.js ile istemci ve sunucu tarafındaki sorunları birlikte izleyebilir, Nest.js ile API katmanındaki hataları ve performans darboğazlarını net biçimde görebilirsiniz. Önemli olan aracı kurmaktan çok, doğru örnekleme, anlamlı alert kuralları ve gizlilik ayarlarıyla düzenli bir süreç kurmaktır.

Kendi projenizde Sentry kurulumu, izleme stratejisi ya da mevcut bir sistemin gözlemlenebilirliğini iyileştirme konusunda destek almak isterseniz benimle iletişime geçebilirsiniz.