PHP ve JavaScript Uygulamalarında Sentry ile Hata İzleme ve VPS’te Observability

PHP veya JavaScript ile geliştirdiğiniz bir uygulamada, kullanıcı size sadece şunu söyler: “Bazen çalışmıyor.” Hangi sayfada, hangi tarayıcıda, ne zaman, hangi hatayla bozulduğunu çoğu zaman bilmezsiniz. Klasik sunucu loglarına bakarsınız; ama istemci tarafındaki JavaScript hataları orada yoktur. Üstelik loglarınız dolu, filtrelemesi zor, kritik hatalar sessizce arada kaynayıp gidiyor.

İşte tam bu noktada yapılandırılmış hata izleme (error tracking) ve genel olarak observability devreye giriyor. Uygulamanızdaki her hatayı bağlamıyla birlikte toplayan, gruplandıran ve size okunabilir, aksiyon alınabilir bir formatta sunan araçlar; hem geliştirme sürecini hem de üretim ortamındaki stabiliteyi bambaşka bir seviyeye taşıyor. PHP backend ve JavaScript frontend dünyasında en yaygın çözümlerden biri Sentry. Buna ek olarak açık kaynak alternatifler ve tamamlayıcı log/metric/trace çözümleri de artık olgunlaştı.

Bu yazıda DCHost ekibi olarak, PHP ve JavaScript projelerinde Sentry temelli hata izlemeyi, açık kaynak seçenekleriyle birlikte kendi VPS’iniz üzerinde nasıl konumlandırabileceğinizi adım adım ele alacağız. Amacımız sadece bir araç tanıtmak değil; aynı zamanda loglama, metrik ve iz (trace) katmanını da içeren sağlıklı bir observability mimarisini pratik bir dille kurmanıza yardımcı olmak.

PHP ve JavaScript’te Hata İzleme Neden Ayrı Bir Sistem Gerektirir?

Sunucu logları, PHP error_log’ları veya Nginx/Apache access log’ları elbette gereklidir. Ancak modern web uygulamalarında bunlar tek başına yeterli değil. Özellikle SPA (Single Page Application), yoğun JavaScript kullanan frontend’ler ve mobil web görünümlerinde hataların önemli bir kısmı kullanıcının tarayıcısında gerçekleşiyor.

Temel farkları netleştirelim:

• Sunucu logları: PHP tarafındaki uyarılar, istisnalar, HTTP 4xx/5xx kayıtları, veritabanı hataları gibi olayları içerir. Genellikle satır satır metin log formatındadır.
• Tarayıcı (JS) hataları: Kullanıcının cihazına, tarayıcısına, ekran çözünürlüğüne ve etkileşimine bağlı olarak ortaya çıkar. Bunlar çoğu zaman sunucu loglarına hiç düşmez.
• İş bağlamı: Sadece “Fatal error” satırını görmek yetmez. Hangi kullanıcıyı, hangi istek parametrelerini, hangi sürümü (release) ve hangi ortamı (production, staging) etkilediğini de bilmek gerekir.

Bu yüzden hata izleme araçları, klasik loglamanın üzerine şu katmanları ekler:

• Hatanın otomatik gruplanması (aynı stack trace tek olay olarak görülür)
• Kullanıcı, oturum, istek, HTTP header, tarayıcı, cihaz gibi bağlamsal bilgiler
• Öncesindeki adımların breadcrumbs olarak kaydedilmesi
• Önem derecesine göre e-posta, Slack vb. entegrasyonlarla uyarı
• Sürüm (release) ve commit bilgisi ile hatanın hangi deploy’dan sonra başladığını görme

PHP tarafındaki temel hata loglamasını doğru kurmak için daha önce hazırladığımız PHP hata kayıtlarını doğru yapılandırma rehberini mutlaka okumanızı öneririz. Oradaki ayarları, bu yazıda anlatacağımız Sentry ve benzeri çözümlerle birlikte düşündüğünüzde, çok daha güçlü bir observability tablosu ortaya çıkıyor.

Sentry ile Hata İzleme Mimarisi

Sentry, hem PHP hem de JavaScript dünyasında yaygın kullanılan bir hata izleme ve performans izleme platformu. İki şekilde kullanılabiliyor:

• SaaS hizmeti olarak (Sentry’nin kendi bulut platformu)
• VPS veya dedicated sunucunuza self-hosted kurulum

Biz burada özellikle kendi DCHost VPS’iniz üzerinde self-hosted kurulum senaryosuna odaklanacağız; ancak mimari, SaaS sürüm için de aynıdır.

Sentry Mimarisi Temel Kavramlar

• SDK: PHP, JavaScript, Node.js, Laravel, Symfony, React, Vue vb. teknolojiler için resmi kütüphaneler.
• DSN: Uygulamanızın Sentry sunucusuna bağlanırken kullandığı bağlantı dizesi. Hangi projeye log yazacağınızı belirler.
• Project: Örneğin “my-app-php” ve “my-app-frontend” gibi her bileşen için ayrı proje.
• Environment: production, staging, dev gibi ortam ayrımları.
• Release: Genellikle git tag veya commit hash ile eşleşen sürüm bilgisi. Hangi deploy’dan sonra hata artmış görebilirsiniz.

Akış basitçe şöyle işler:

1. PHP veya JavaScript uygulamanızda Sentry SDK’yı kurarsınız.
2. Bir istisna (exception) veya JS hatası oluştuğunda SDK bu olayı yakalar.
3. Olayı, DSN üzerinden HTTP istekleriyle Sentry sunucunuza gönderir.
4. Sentry sunucusu bu olayları işler, veritabanına kaydeder, gruplanmış şekilde arayüzde gösterir ve gerekirse uyarı tetikler.

VPS Üzerinde Sentry Kurulumu İçin Örnek Yaklaşım

Sentry’yi kendi DCHost VPS’inize kurmak için en pratik yol Docker tabanlı self-hosted paketi kullanmaktır. Varsayalım ki aşağıdaki kaynaklara sahipsiniz:

• Güncel bir Linux VPS (örneğin 2–4 vCPU, 4–8 GB RAM, hızlı NVMe disk)
• Docker ve docker-compose kurulu
• Sentry için ayrılmış bir alt alan adı, örneğin sentry.ornekalanadiniz.com
• Reverse proxy olarak Nginx veya Caddy ve geçerli bir SSL sertifikası

Resmi self-hosted deposunu çekip, basitleştirilmiş bir docker-compose ile ayağa kaldırabilirsiniz. Örneğin:

version: '3.8'
services:
  sentry:
    image: sentry:latest
    depends_on:
      - postgres
      - redis
    environment:
      SENTRY_SECRET_KEY: <guclu-bir-anahtar>
      SENTRY_POSTGRES_HOST: postgres
      SENTRY_DB_USER: sentry
      SENTRY_DB_PASSWORD: <sifre>
    ports:
      - '9000:9000'

  postgres:
    image: postgres:14
    environment:
      POSTGRES_DB: sentry
      POSTGRES_USER: sentry
      POSTGRES_PASSWORD: <sifre>

  redis:
    image: redis:6

Gerçekte Sentry’nin kendi sağladığı docker-compose dosyası ve kurulum script’leri daha kapsamlıdır; bunları kılavuza göre uygulamanız gerekir. Biz burada mimariyi sadeleştirmek için şematik bir örnek verdik.

Log ve metrik tarafını da aynı VPS’te veya ayrı bir gözlem sunucusunda toplamak isterseniz, daha önce anlattığımız VPS log yönetimini Loki ve Promtail ile merkezi hale getirme rehberindeki yaklaşım, Sentry ile güzelce tamamlayıcı bir rol oynar.

PHP Uygulamaları İçin Sentry Entegrasyonu

PHP tarafında en yaygın senaryo; Laravel, Symfony, WordPress veya özel yazılmış bir MVC uygulamasına Sentry SDK eklemek. Örnekleri Laravel odaklı verelim, ardından çıplak PHP için de kısaca değinelim.

Laravel’de Sentry Kurulumu

Adımlar kabaca şöyle:

1. Composer ile SDK’yı ekleyin:

composer require sentry/sdk

2. Environment değişkenine DSN ekleyin:

# .env
SENTRY_LARAVEL_DSN=https://<public-key>@sentry.ornekalanadiniz.com/<project-id>
SENTRY_TRACES_SAMPLE_RATE=0.2
SENTRY_ENVIRONMENT=production

Buradaki DSN, doğrudan kodun içinde sabit yazılmamalı; .env kullanmak hem güvenlik hem de esneklik açısından daha sağlıklı. VPS üzerinde gizli anahtar yönetimi konusunda sorularınız varsa, VPS’te .env ve gizli anahtar yönetimi rehberimizde detaylı bir yol haritası paylaştık.

3. Laravel için Sentry servis sağlayıcısını ve facade’ını etkinleştirin (Laravel sürümüne ve SDK paketine göre değişebilir, Sentry dokümantasyonuna bakın).
4. Hata handler içine entegrasyon ekleyin:

// app/Exceptions/Handler.php
use SentryLaravelFacade as Sentry;

public function report(Throwable $exception)
{
    if (app()->bound('sentry') && $this->shouldReport($exception)) {
        Sentry::captureException($exception);
    }

    parent::report($exception);
}

Bu kod, Laravel’in zaten sahip olduğu raporlama mekanizmasını bozmadan, Sentry’ye de kopya geçmesini sağlar. Bundan sonra production ortamında oluşan istisnalar; kullanıcı, istek, route, HTTP metodu, header’lar ve stack trace ile birlikte Sentry arayüzünde görünecektir.

WordPress veya Özel PHP Uygulamalarında Sentry

Laravel kullanmıyorsanız da mantık aynı: Global exception handler veya framework’ünüzün hata yakalama noktasında Sentry çağrısı yapmak.

require __DIR__ . '/vendor/autoload.php';

Sentryinit([
    'dsn' => getenv('SENTRY_DSN'),
    'environment' => getenv('SENTRY_ENVIRONMENT') ?: 'production',
]);

set_exception_handler(function (Throwable $exception) {
    SentrycaptureException($exception);
    // Burada kendi log mekanizmanız veya hata sayfanız da çalışabilir.
});

WordPress tarafında ise genellikle eklenti tabanlı entegrasyonlar kullanılır veya wp-config.php içinde Sentry SDK başlatılır. Önemli olan; fatal hatalar ve beklenmeyen istisnelerin global olarak yakalanmasıdır.

Performans İzleme ve Breadcrumb’lar

Sentry sadece istisnaları değil; istek süresi, yavaş sorgular ve belirli kod bloklarının performansını da ölçebilir. Laravel’de Sentry performans izlemeyi etkinleştirdiğinizde, her HTTP isteği için bir transaction kaydı oluşur. Bu kayıtlar, daha sonra APM (Application Performance Monitoring) görünümünde analiz edilebilir.

Ayrıca Sentry, breadcrumbs adı verilen mini log’larla; hatadan hemen önce gerçekleşen sorguları, HTTP isteklerini, kullanıcı aksiyonlarını ve debug loglarını da olaya iliştirir. Böylece tek bir stack trace yerine, bir hikâye görürsünüz.

JavaScript (Browser ve Node.js) İçin Hata İzleme

Tarayıcı tarafındaki JavaScript hatalarını sunucu loglarından takip etmek neredeyse imkansızdır. Kullanıcının hangi cihazı kullandığını, hangi ekranda, hangi butona tıkladığında hata aldığını bilmek ise dönüşüm oranları için kritiktir.

Browser Tarafında Sentry

En basit entegrasyon, Sentry’nin CDN üzerinden sağladığı script’i sayfaya eklemekle başlar:

<script src='https://browser.sentry-cdn.com/7.x.x/bundle.tracing.min.js' integrity='<...>' crossorigin='anonymous'></script>
<script>
Sentry.init({
  dsn: 'https://<public-key>@sentry.ornekalanadiniz.com/<project-id>',
  environment: 'production',
  tracesSampleRate: 0.2,
});
</script>

Bundan sonra sayfada oluşan window.onerror ve unhandledrejection olayları otomatik yakalanır ve Sentry’ye gider. SPA framework’leri (React, Vue, Angular) için özel Sentry paketleri de vardır; bunlar router geçişleri, component lifecycle olayları gibi daha zengin bağlam sunar.

Önemli bir nokta: Frontend DSN’iniz kullanıcı tarafında gözükeceği için backend DSN’inizle aynı projeyi kullanmamanız genelde iyi bir pratiktir. Ayrı bir Sentry projesi açıp sadece frontend hataları için kullanmak, ayrıştırma ve yetkilendirme açısından daha sağlıklıdır.

Kullanıcı ve Oturum Bilgilerini Ekleme

Sentry, anonim kullanıcı kimlikleriyle hata bağlamını zenginleştirmenize izin verir. Örneğin giriş yapmış bir kullanıcının ID ve e-posta adresini (KVKK’ya uygun bir şekilde) ekleyebilirsiniz:

Sentry.setUser({
  id: '12345',
  email: '[email protected]'
});

Burada e-posta adresi gibi kişisel verileri gerçekten gönderip göndermeyeceğiniz; şirketinizin veri işleme politikalarına ve KVKK yorumunuza göre değişir. Anonimleştirilmiş ID’ler, hash’lenmiş e-posta adresleri veya sadece kullanıcı rollerini göndermek de çoğu senaryoda yeterli olabilir.

Node.js ve API Katmanı

JavaScript sadece tarayıcıda değil, Node.js tabanlı backend’lerde de yaygın. Express benzeri bir framework kullanıyorsanız, Sentry entegrasyonu tipik olarak iki middleware ile yapılır:

import * as Sentry from '@sentry/node';
import express from 'express';

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.SENTRY_ENVIRONMENT || 'production',
});

const app = express();

app.use(Sentry.Handlers.requestHandler());

// ... route tanımları ...

app.use(Sentry.Handlers.errorHandler());

Bu yapı, istek bağlamını otomatik olarak olaylara ekler ve Express error middleware zinciriyle uyumlu çalışır. Node.js tarafını da gözlemlemek istiyorsanız, daha önce hazırladığımız Node.js’i canlıya alırken PM2, systemd ve Nginx ile sıfır kesinti deploy rehberi ile birlikte düşünmek güzel bir kombinasyon olur.

Açık Kaynak Alternatifleri ve Tamamlayıcı Araçlar

Sentry, hata izleme tarafında güçlü bir standart haline geldi; ancak her senaryoda tek seçenek olmak zorunda değil. Özellikle tamamen açık kaynak ve kendi kontrolünüzde bir yığın kurmak istiyorsanız şu yolları düşünebilirsiniz:

Self-Hosted Sentry

Aslında en doğrudan açık kaynak seçeneği, Sentry’nin kendi self-hosted sürümünü kullanmak. Kaynak kodu açık, Docker ile kurulabiliyor ve kendi DCHost VPS’inizde veya dedicated sunucunuzda çalıştırılabiliyor. Avantajları:

• Veriniz tamamen sizin altyapınızda kalır.
• Ortam, domain, entegrasyonlar üzerinde tam kontrol.
• Fiyatlandırma, kendi donanım maliyetinizle sınırlı.

Dezavantajları ise bakım yükü, güncellemeler ve ölçekleme sorumluluğunun size ait olması. Yüksek trafikli projelerde veritabanı, queue ve disk kapasitesini iyi planlamanız gerekir.

Sentry Protokolüyle Uyumlu Alternatifler

Bazı açık kaynak projeler, Sentry SDK’larını değişiklik yapmadan kullanmanızı sağlayan Sentry-uyumlu protokoller sunar. Örneğin kendi basitleştirilmiş hata izleme panelinizi kurmak, ancak mevcut Sentry SDK ekosisteminden de faydalanmak istiyorsanız bu yaklaşım değerlendirilebilir.

Bu tür projelerde genellikle şu özellikleri bulursunuz:

• Exception ve event toplama
• Basit bir web arayüzü
• PostgreSQL veya benzeri bir veritabanı arka planı
• Temel uyarı ve filtreleme yetenekleri

İhtiyacınız Sentry’nin tüm gelişmiş APM yetenekleri değil de daha hafif bir hata izleme aracıysa, bu tarz çözümler DCHost VPS’inizde son derece ekonomik ve kontrol edilebilir bir mimari sunar.

Log, Metrik ve Trace Katmanını Tamamlamak

Hata izleme, observability hikayesinin sadece bir parçası. Gerçek bir üretim ortamında aşağıdaki üç katmanı birlikte düşünmek gerekiyor:

• Loglar: Uygulama ve sunucu loglarının merkezi toplanması ve sorgulanması
• Metrikler: CPU, RAM, disk, response time, istek sayısı gibi sayısal veriler
• Trace’ler: Bir isteğin farklı servisler arasında nasıl aktığını gösteren uçtan uca izler

Log tarafında, Sentry’yi tamamlamak için VPS’te Loki, Promtail ve Grafana ile merkezi loglama rehberimizde detaylandırdığımız yaklaşımı uygulayabilirsiniz. Böylece Sentry’de gördüğünüz bir hata için, ilgili zaman aralığındaki Nginx, PHP-FPM veya uygulama loglarını saniyeler içinde filtreleyebilirsiniz.

Trace ve metrik tarafında ise OpenTelemetry ile Laravel ve Node.js’te uçtan uca izler kurma rehberimiz, Sentry’yi tamamlayan bir diğer güçlü parça. Sentry ile hatayı, OpenTelemetry ile isteğin bütün yolculuğunu, Prometheus benzeri çözümlerle de sistem metriklerini birlikte okuduğunuzda; sorun tespiti birkaç dakikalık bir işe dönüşüyor.

Kaynak kullanım metriklerini izlemek içinse, VPS kaynak kullanımı izleme rehberimizde anlattığımız htop, Netdata ve Prometheus kombinasyonu; özellikle CPU veya disk darboğazı yaşadığınızda değerli bir tamamlayıcı.

DCHost VPS Üzerinde Observability Stratejisi Adım Adım

Gelin tüm parçaları bir araya getirelim. Elinizde PHP (örneğin Laravel) + JavaScript (SPA veya klasik frontend) içeren bir uygulama var ve bunu DCHost üzerinde bir veya birkaç VPS’te barındırıyorsunuz. Nasıl bir observability planı kurmalısınız?

1. Ortamları ayırın
   Geliştirme, test (staging) ve canlı ortamları hem hosting hem de hata izleme düzeyinde ayırmak, gözlemlenebilirliğin temel taşıdır. Bunun için geliştirme, test ve canlı ortamlar için hosting mimarisi rehberimizde detaylı bir örnek kurguladık.
2. Sentry projelerini tasarlayın
   En azından şu ayrımı yapmanızı öneririz:
   • Backend (PHP) için ayrı bir Sentry projesi
   • Frontend (JavaScript) için ayrı bir Sentry projesi

   Ortam bazında environment alanını (production, staging) kullanın.

3. Log toplama mimarisini belirleyin
   PHP, Nginx/Apache, veritabanı ve sistem loglarını ya aynı VPS’te ayrı bir disk bölümüyle; ya da merkezi bir log VPS’i üzerinde Loki veya ELK türü çözümlere gönderin. Böylece disk dolması sorunlarını da logrotate ve disk kullanımı rehberimizde anlattığımız gibi daha öngörülebilir kılabilirsiniz.
4. Metrik ve sağlık kontrollerini ekleyin
   Prometheus, Netdata veya benzeri araçlarla CPU, RAM, disk, bağlantı sayısı, HTTP response time gibi metrikleri toplayın. Sentry’de gördüğünüz bir hata patlamasının gerçekten altyapı sorunundan mı, yoksa sadece kod hatasından mı kaynaklandığını bu metriklerle hızlıca ayırt edebilirsiniz.
5. Alarm kuralları ve runbook’lar yazın
   Ciddi hatalar için Sentry’den e-posta veya webhook ile alarm tetikleyin. Metrik tarafında Prometheus uyarıları, log tarafında da belirli pattern’lere göre alarmlar oluşturun. Her kritik alarm için basit bir runbook (1–2 sayfalık nasıl müdahale edilir dökümanı) yazmak, operasyonel yükü ciddi şekilde hafifletir.

Güvenlik, Gizlilik ve KVKK Perspektifi

Hata izleme araçları, çoğu zaman kullanıcıya ait verileri de yanlarına takıp getirir. Bu yüzden KVKK ve GDPR gibi regülasyonlar açısından dikkatli olmak gerekir. Özellikle Türkiye’de faaliyet gösteren projelerde şunlara özen göstermenizi net olarak tavsiye ediyoruz:

• IP adresi, e-posta, ad-soyad gibi kişisel verileri gerçekten gerekmedikçe Sentry’ye göndermeyin.
• Göndermeniz gerekiyorsa, maskeleme veya pseudonymization yöntemlerini kullanın.
• Log ve hata olaylarının saklama sürelerini, yasal gereklilikler ve iş ihtiyacı arasında dengeli belirleyin.

Bu konuyu daha sistematik ele almak isterseniz, KVKK ve GDPR için log anonimleştirme rehberimizde IP maskeleme ve pseudonymization örneklerini detaylıca anlattık. Aynı prensipleri Sentry event’leri için de kullanabilirsiniz.

Buna ek olarak:

• Sentry arayüz erişimini iki faktörlü doğrulama ile koruyun.
• Yalnızca gerçekten ihtiyaç duyan ekip üyelerine proje erişimi verin.
• DSN ve API token’larını .env dosyalarında veya gizli değişken yönetiminde tutun; kod deposuna asla gömmeyin.

Sonuç: Hata İzleme, Log ve Metrik Üçlüsü ile Rahat Nefes Almak

PHP ve JavaScript dünyasında hataları sadece error_log ve tarayıcı konsolu ile takip etmeye çalışmak, güncel uygulama karmaşıklığı için artık yeterli değil. Sentry veya benzeri bir hata izleme aracı; istisnaları otomatik gruplayan, kullanıcı ve istek bağlamını ekleyen, hangi sürümde sorun çıktığını net gösteren yapısıyla size gerçek anlamda zaman kazandırıyor. Buna merkezi loglama, metrik toplama ve trace katmanını da eklediğinizde; “Bu hata nereden çıktı?” sorusu yerini “Tam olarak şurada, şu sırayla, şu metriklerle çıktı” netliğine bırakıyor.

DCHost olarak biz, bu tip observability mimarilerini özellikle VPS ve dedicated sunucu altyapılarımız üzerinde sıkça kurguluyoruz. İster self-hosted Sentry, ister daha hafif açık kaynak alternatifler, isterse sadece merkezi log + metrik + OpenTelemetry kombinasyonu olsun; doğru kurgulandığında operasyonel iş yükünüzü ciddi şekilde azaltıyor. Uygulamanız için benzer bir yapı düşünüyorsanız, ihtiyacınıza en uygun DCHost VPS veya dedicated sunucu boyutlandırması konusunda size teknik ekibimizle birlikte destek olmaktan memnuniyet duyarız.

Bir sonraki adım olarak, mevcut PHP ve JavaScript projelerinizde en azından üretim ortamına temel bir Sentry entegrasyonu ekleyip; bir yandan da log ve metrik tarafını güçlendirmenizi öneririm. İlk gerçek hatayı detaylı bağlamla birlikte gördüğünüz anda, bu yatırımın ne kadar işe yaradığını zaten kendiniz de hissedeceksiniz.