Deploynix’i Üretimde Hata Takibi için Sentry ile Bağlama

Deploynix, sunucu düzeyinde izleme sunar — CPU, bellek, disk ve sağlık bildirimleri gibi kayıtlara ulaşmanızı sağlar. Ancak sunucu metrikleri, altyapınızın sağlıklı olduğunu gösterir; uygulamanızın doğru çalışıp çalışmadığını göstermez.

%10 CPU ile çalışan bir sunucu, hala her üçüncü istekte 500 hatası verebilir. Bir kuyruk işleyicisi “başarıyla” işlerken sessizce istisnaları yutabilir. Planlı bir görev yarıda kalabilir ve verileri tutarsız bir durumda bırakabilir.

İşte burada Sentry devreye giriyor. Sentry, uygulama seviyesinde hataları, istisnaları ve performans sorunlarını, hata ayıklama için gerekli olan bağlamla yakalar: yığın izleri, istek verileri, kullanıcı bilgileri, izler ve daha fazlası.

Deploynix ve Sentry birlikte size tam yığın gözlemlenebilirlik sunar: Deploynix ile altyapı sağlığı ve Sentry ile uygulama sağlığı. Bu kılavuz, Sentry’nin nasıl doğru bir şekilde bağlanacağını kapsar; temel SDK kurulumundan öte, sürüm takibi, kaynak haritaları, ortam etiketleme ve otomatik dağıtım bildirimlerini içerir.

Sentry Laravel SDK’sını Yüklemek

Öncelikle Sentry SDK’sını Laravel için yükleyin:

composer require sentry/sentry-laravel

Sentry yapılandırma dosyasını yayınlayın:

php artisan sentry:publish --dsn=YOUR_SENTRY_DSN

Bu, config/sentry.php dosyasını oluşturur ve .env dosyanıza SENTRY_LARAVEL_DSN girişi ekler.

Eğer manuel olarak yapılandırmayı tercih ederseniz, Deploynix kontrol panelinde aşağıdaki ortam değişkenlerini ekleyin:

SENTRY_LARAVEL_DSN=https://[email protected]/0
SENTRY_TRACES_SAMPLE_RATE=0.1

DSN (Veri Kaynağı Adı), Sentry proje ayarlarınızda Müşteri Anahtarları (DSN) altında bulunur. İz sürme örnek oranı, hangi yüzdelik isteklerin performans izlerini oluşturduğunu kontrol eder — 0.1, %10 anlamına gelir ve üretim için iyi bir başlangıçtır.

Kurulumu Doğrulamak

Sentry yapılandırmasıyla dağıtım gerçekleştirdikten sonra, test bir istisna tetikleyerek bağlantıyı doğrulayabilirsiniz. Geçici bir test yönlendirmesi ekleyin:

Route::get('/debug-sentry', function () {
    throw new \Exception();
});

Yönlendirmeyi ziyaret edin, ardından Sentry kontrol panelinizi kontrol edin. İstisnanın birkaç saniye içinde görünmesi gerekir. Doğrulama sonrasında test yönlendirmesini kaldırın.

Ortam Etiketleme

Laravel uygulamaları genelde birden fazla ortamda çalışır: yerel geliştirme, test ve üretim. Sentry’nin bu ortamları ayırt etmesi önemlidir, böylece üretim hatalarına yoğunlaşabilirsiniz.

Deploynix ortam değişkenlerinizde ayarlayın:

SENTRY_ENVIRONMENT=production

Test sunucularınız için ayarlayın:

SENTRY_ENVIRONMENT=staging

Sentry bu değeri her olayı etiketlemek için kullanır; böylece kontrol panelinde ortamlar arasında filtreleme yapabilirsiniz. Ayrıca, yalnızca üretim hataları için tetiklenen uyarı kuralları yapılandırabilirsiniz, bu sayede test sorunları kimseyi rahatsız etmez.

config/sentry.php dosyasında, ortam genellikle SENTRY_ENVIRONMENT değişkeninden alınır veya APP_ENV‘ye geri döner:

'environment' => env(, env(, )),

Bu önemlidir çünkü APP_ENV hem üretim hem de test sunucularınızda production olarak ayarlanabilir. Ayrı bir SENTRY_ENVIRONMENT değişkeni kullanmak, kesin kontrol sağlar.

Sürüm Takibi

Sürüm takibi, Sentry’nin üretim hata ayıklama için en güçlü özelliklerinden biridir. Hataları belirli sürümlerle ilişkilendirdiğinizde, şunları yapabilirsiniz:

Hatanın hangi sürümde ortaya çıktığını görmek.
Sürüm başına hata oranlarını takip etmek — bir dağıtımın durumu iyileştirip iyileştirmediğini belirlemek.
Dağıtım sonrası gerilemeleri hemen tespit etmek.
Hata artışlarını belirli kod değişiklikleriyle ilişkilendirmek.

Sürümleri Yapılandırmak

En basit yaklaşım, sürüm tanımlayıcısı olarak Git commit SHA’sını kullanmaktır. Deploynix dağıtım scriptinizde geçerli commit’i alabilir ve bunu Sentry’ye iletebilirsiniz:

Deploynix’teki ortam değişkenlerinize aşağıdakini ekleyin:

SENTRY_RELEASE=

Daha sonra, dağıtım scriptinizde (kod çekildikten sonra) sürümü dinamik olarak ayarlayın:

# Dağıtım scriptinizde
COMMIT_SHA=$(git rev-parse HEAD)
sed -i "s/SENTRY_RELEASE=.*/SENTRY_RELEASE=${COMMIT_SHA}/" .env

Alternatif olarak, sürüm numarası veya tarih içeren daha okunabilir bir sürüm formatı da kullanabilirsiniz:

RELEASE="deploynix-$(date +%Y%m%d)-$(git rev-parse --short HEAD)"
sed -i "s/SENTRY_RELEASE=.*/SENTRY_RELEASE=${RELEASE}/" .env

Sentry’de sürümü ortamdan okuyun:

'release' => env(),

Neden Sürüm Takibi Önemlidir

Sürüm takibi olmadan, Sentry size hataların düz bir zaman çizelgesini sunar. Bir hatanın Salı günü ortaya çıktığını görebilirsiniz, ancak Salı günü yapılan üç dağıtımdan hangisinin bunu tetiklediğini bilemezsiniz.

Sürüm takibi ile Sentry, hatayı ilk tetikleyen sürümü tam olarak gösterir. İlgili engeli tıklayıp, farkı görebilir ve nedeni dakikalar içinde belirleyebilirsiniz.

Ön Uç Hataları İçin Kaynak Haritaları

Eğer Laravel uygulamanızın bir JavaScript ön ucu varsa — bunu inline scriptlerle birlikte Alpine.js, JavaScript etkileşimleri olan bir Livewire uygulaması veya tam bir tek sayfalı uygulama olarak düşünün — Sentry ön uç hatalarını da yakalayabilir. Ancak, minify edilmiş JavaScript yığın izleri, kaynak haritaları olmadan faydasızdır.

Sentry Tarayıcı SDK’sını Yüklemek

Eğer Vite kullanıyorsanız (bu Laravel için varsayılan), Sentry tarayıcı SDK’sını yükleyin:

npm install @sentry/browser

JavaScript ana dosyanızda Sentry’i başlatın:

import * as Sentry from "@sentry/browser";

Sentry.init({
    dsn: "YOUR_SENTRY_DSN",
    environment: document.querySelector('meta[name="sentry-environment"]')?.content || "production",
    release: document.querySelector(meta[name="sentry-release"])?.content,
    integrations: [
        Sentry.browserTracingIntegration(),
    ],
    tracesSampleRate: 0.1,
});

Blade düzeninizde meta etiketlerini ekleyin:

Kaynak Haritalarını Yüklemek

Kaynak haritaları, Sentry’nin JavaScript yığın izlerini açılmasını sağlar; böylece orijinal dosya, satır numarası ve fonksiyon adı gösterilir yerine app-DfG8h2k.js:1:34982.

Sentry Vite eklentisini yükleyin:

npm install @sentry/vite-plugin

Bunu vite.config.js dosyanızda yapılandırın:

import { sentryVitePlugin } from "@sentry/vite-plugin";

export default defineConfig({
    build: {
        sourcemap: true,
    },
    plugins: [
        laravel({
            input: ['resources/css/app.css', 'resources/js/app.js'],
            refresh: true,
        }),
        sentryVitePlugin({
            org: "your-sentry-org",
            project: "your-sentry-project",
            authToken: process.env.SENTRY_AUTH_TOKEN,
        }),
    ],
});

SENTRY_AUTH_TOKEN, Sentry’nin Vite eklentisinin kaynak haritalarını yüklemesine izin veren bir kimlik doğrulama tokenıdır. Sentry hesabınızda Ayarlar > Kimlik Doğrulama Tokenleri altında oluşturun.

Token’i Deploynix ortamınıza ekleyin:

SENTRY_AUTH_TOKEN=your_auth_token_here

Şimdi, dağıtım scriptiniz npm run build çalıştığında, Sentry Vite eklentisi otomatik olarak kaynak haritalarını Sentry’ye yükler ve bunları mevcut sürümle ilişkilendirir. Ön uç hataları, orijinal kaynak kodunuzla birlikte deşifre edilmiş yığın izleri ile gösterilecektir.

Güvenlik notu: Kaynak haritaları Sentry sunucularına yüklenir, ancak kullanıcılarınıza sunulmaz. Kullanıcılarınız yine de sıkıştırılmış JavaScript alır. Kaynak haritaları yalnızca Sentry tarafından hata raporlarını deşifre etmek için kullanılır.

Dağıtım Scriptinizden Dağıtım Bildirimleri

Sentry’nin dağıtım takibi, sürümlerin ötesine geçer. Sentry’ye bir dağıtım hakkında bilgi verdiğinizde:

Sürümü belirli bir ortama dağıtıldıkları olarak işaretler.
Bir sonraki sürümde çözüldüğü işaretli sorunları çözer.
Dağıtım hakkında ekip üyelerine bildirim gönderir.
Yeni sürüm hatalarının oranını geri bildirim izlemek için başlatır.

Sentry’ye dağıtımları doğrudan Deploynix dağıtım scriptinizden bildirebilirsiniz. Dağıtım scriptinize aşağıdakini ekleyin:

SENTRY_RELEASE=$(git rev-parse HEAD)
SENTRY_ENVIRONMENT="production"
SENTRY_ORG="your-sentry-org"
SENTRY_PROJECT="your-sentry-project"
SENTRY_AUTH_TOKEN="your-auth-token"

curl -s https://sentry.io/api/0/organizations/${SENTRY_ORG}/releases/ \
  -H "Authorization: Bearer ${SENTRY_AUTH_TOKEN} \
  -H "Content-Type: application/json" \
  -d "{
    \"version\": \"${SENTRY_RELEASE}\",
    \"projects\": [\"${SENTRY_PROJECT}\"]
  }"

curl -s https://sentry.io/api/0/organizations/${SENTRY_ORG}/releases/${SENTRY_RELEASE}/deploys/ \
  -H "Authorization: Bearer ${SENTRY_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"environment\": \"${SENTRY_ENVIRONMENT}\",
    \"name\": \"Deploynix dağıtımı $(date +%Y-%m-%d_%H:%M:%S)\"
  }"

İlk curl komutu, Sentry’de sürümü oluşturur (varsa yoksa). İkinci komut ise dağıtımı kaydeder. Birlikte, Sentry’nin sürüm panosunda eksiksiz bir dağıtım geçmişi sağlar.

Daha temiz bir dağıtım scripti için, Sentry bildirimini bir shell scriptine çıkarabilir ve Deploynix kontrol panelinde saklanan ortam değişkenlerine referans verebilirsiniz:

# dağıtım scripti
bash scripts/notify-sentry.sh

Uyarıları Yapılandırmak

Sentry, hatalarınızı ve dağıtım bilgilerinizi aldığında, ekip arkadaşlarınızı bir şeyler ters gittiğinde haber vermek için uyarıları yapılandırın.

Tavsiye Edilen Uyarı Kuralları

Yeni sorun uyarısı: Sentry, önceden görmediği bir hata gördüğünde tetiklenir. Bu, yeni dağıtımlarla tanıtılan hataları hemen yakalar.

Koşullar: Yeni bir sorun oluşturulması.
Hareketler: Ekip üyelerinin Slack kanalı veya e-postasına bildirim gönderme.
Sıklık: Her sorun için en fazla 30 dakikada bir.

Yüksek frekans uyarısı: mevcut bir hata aniden çok daha sık meydana gelirse (bir gerileme veya altyapı sorunu gösterebilir), tetiklenir.

Koşullar: Bir sorundaki olay sayısı saatte 100’ü geçerse.
Hareketler: “Kritik” öncelikli bir bildirim gönderme.
Sıklık: Saate en fazla bir kez.

Ortam spesifik uyarılar: Dağıtımda, üretim hataları için sayfanızın önceliğine göre izleme sağlar; test sorunları ise düşük öncelikli bir Slack kanalına gönderilir. Bu, aşırı uyarı yorgunluğunun önüne geçer.

Performans Uyarıları

Eğer performans izleme etkinse ( SENTRY_TRACES_SAMPLE_RATE üzerinden), işaretleriniz için performans uyarıları yapılandırın:

Yavaş işlemler: Belirli bir yön için p95 yanıt süresi SLAsını aşarsa uyarın.
Geçiş değişiklikleri: İşlemler sayısı önemli ölçüde düşerse (bu kullanıcıların uygulamanıza erişemediğini gösterebilir) uyarın.

Üretim için En İyi Uygulamalar

Örnekleme Oranları

Üretimde, performans izleme için %100 işlem yakalamak pahalıdır ve gereksizdir. %0.1 (yani %10) bir örnekleme oranı, önemli ölçüde performans verileri sağlar ve Sentry kotanızı aşmaz.

Hata olayları içinse, Sentry varsayılan olarak tüm hataları yakalar (örnekleme yoktur). Bu doğrudur — her hatayı bilmek istersiniz, hataların istatistiksel bir örneği değil.

Hassas Veri Temizleme

Laravel uygulamaları genellikle hassas verilerle ilgilenir: parolalar, API anahtarları, kredi kartı numaraları, kişisel bilgiler. Sentry bazı hassas alanları otomatik olarak temizler, ancak ek temizleme yapılandırmalısınız.

config/sentry.php dosyanızda:

'before_send' => function (\Sentry\Event $event): ?\Sentry\Event {
    // Hassas istek verilerini kaldır
    $request = $event->getRequest();
    if ($request) {
        $data = $request->getData();
        $sensitiveFields = ['password', 'password_confirmation', 'credit_card', 'ssn', 'token'];
        foreach ($sensitiveFields as $field) {
            if (isset($data[$field])) {
                $data[$field] = ;
            }
        }
        $request->setData($data);
    }
    return $event;
},

Ayrıca, projenizde Sentry’nin sunucu tarafı veri temizleme yapılandırmasını Güvenlik ve Gizlilik ayarlarında yapılandırın. “Genişletilmiş Veri Temizleme” seçeneğini etkinleştirin ve uygulama spesifik hassas alan adlarını ekleyin.

Bilinen Hataları Yoksayma

Bazı hatalar beklenir ve dikkat gerektirmez: web tarayıcılarından 404’ler, kullanıcı girişlerinden doğrulama hataları, brute force girişimleri nedeniyle kimlik doğrulama hataları. Bu hataların Sentry tarafından göz ardı edilmesini yapılandırın:

'ignore_exceptions' => [
    \Symfony\Component\HttpKernel\Exception\NotFoundHttpException::class,
    \Illuminate\Validation\ValidationException::class,
    \Illuminate\Auth\AuthenticationException::class,
],

Bu, Sentry kontrol panelinizi gerçek hatalara odaklar ve beklenen uygulama davranışıyla ilgili bildirimleri azaltır.

Kuyruk ve İş İzleme

Sentry, Laravel entegrasyonu aracılığıyla kuyruk işleyicilerinden istisnaları otomatik olarak yakalar. Ancak iş hatalarına ek bağlam eklemek için de şunları yapabilirsiniz:

use Sentry\Laravel\Integration;

class ProcessPayment implements ShouldQueue
{
    public function handle(): void
    {
        Integration::addBreadcrumb(new \Sentry\Breadcrumb(
            \Sentry\Breadcrumb::LEVEL_INFO,
            \Sentry\Breadcrumb::TYPE_DEFAULT,
            'queue',
            'Ödeme işleniyor',
            ['order_id' => $this->order->id, 'amount' => $this->order->total]
        ));

        // Ödemeyi işleyin...
    }
}

Breadcrumb’lar, bir hataya yol açan olayların izini oluşturur; bu sayede istisna atılmadan önce ne olduğunu anlamanıza yardımcı olur.

Her Şeyi Bir Araya Getirmek

Sentry’nin Deploynix ile düzgün bir şekilde yapılandırılmasıyla, gözlemlenebilirlik yığınınız her iki katörü de kapsar:

Deploynix altyapınızı izler: CPU yükünü, bellek kullanımını, disk alanını ve sunucu sağlığını izler. Donanım kaynakları kısıtlandığında uyarılar tetiklenir.

Sentry uygulamanızı izler: İstisnalar, yavaş işlemler, başarısız işler ve ön uc hataları. Kodunuz düzgün çalışmadığında uyarılar tetiklenir.

Sürüm takibi, dağıtımları hatalarla ilişkilendirir: Hangi dağıtımın bir hatayı tanıttığını, hangi commit’in bunu neden olduğunu ve düzeltmek için dağıttığınız düzeltmenin gerçekten çözümleyip çözmediğini bilirsiniz.

Bu, kendi gözlemlenebilirlik boru hattınızı inşa etmenin karmaşıklığı olmadan üretim seviyesinde izleme sağlar. Deploynix altyapıyı yönetir. Sentry uygulamayı yönetir. Siz ise kodları yönetirsiniz.

Kaynak: Orijinal Makale

Contents