Laravel Telescope ve Pulse: Kurulum ve Üretim Rehberi

Laravel uygulamalarında hata ayıklama ve performans izleme ihtiyacı iki farklı katmanda ortaya çıkar: geliştirme sırasında "ne oldu?" sorusu, üretimde ise "sistem şu an nasıl davranıyor?" sorusu. Telescope ve Pulse bu iki ihtiyaca ayrı ayrı odaklanır. Bu rehberde her iki aracın kurulumunu, temel kullanımını ve üretim ortamındaki güvenlik sınırlarını ele alıyoruz.

Önkoşullar ve Sürüm Kapsamı

• Laravel 10 veya üzeri bir uygulama (her iki paket de modern Laravel sürümleriyle uyumludur).
• Çalışan bir veritabanı bağlantısı. Telescope ve Pulse varsayılan olarak veritabanı sürücüsüyle çalışır; Redis gibi alternatif sürücüler de desteklenir.
• Queue altyapısı. Özellikle Pulse, topladığı verileri işlemek için kuyruk kullanır; senkron kuyruk üretimde önerilmez.
• composer ve artisan komutlarına hâkimiyet.

Sürüm numarası bilinçli olarak verilmiyor. Paketlerin güncel sürümünü ve uyumluluk matrisini kurmadan önce Composer çıktısından veya resmi dokümantasyondan doğrulayın.

Telescope ve Pulse Arasındaki Ayrım

İkisi rakip değil, tamamlayıcıdır:

• Telescope, istek, sorgu, job, mail, exception gibi tek tek olayların ayrıntılı kaydını tutar. Hata ayıklama odaklıdır; veri hacmi yüksektir.
• Pulse, uygulamanın anlık sağlık göstergelerini toplar: istek süreleri, yavaş sorgular, kuyruk gecikmesi, önbellek isabet oranı gibi. Üretim izleme odaklıdır ve veriyi özetler.

Pratik kural: geliştirme ve ön üretim ortamında Telescope, üretimde ise Pulse ağırlıklı kullanılır. Telescope üretimde açılacaksa mutlaka kısıtlanmalıdır (aşağıda ele alınıyor).

Telescope Kurulumu

Paketi Composer ile ekleyin:

composer require laravel/telescope

Ardından kurulum komutunu çalıştırın:

php artisan telescope:install
php artisan migrate

telescope:install, yapılandırma dosyasını config/telescope.php altına yazar ve gerekli migration'ları oluşturur. migrate komutu Telescope'un kayıt tablolarını veritabanında açar.

Telescope paneli varsayılan olarak /telescope yolunda yayınlanır. Geliştirme ortamında APP_ENV=local iken panele doğrudan erişilebilir; üretimde bu davranışa güvenmeyin.

Erişimi Kısıtlama

Telescope, uygulamanızın iç işleyişini (istek gövdeleri, sorgular, oturum bilgileri dâhil) gösterir. Üretimde açık bırakmak ciddi bir veri sızıntısı riskidir. Erişimi TelescopeServiceProvider içinde yetkilendirmeye bağlayın:

use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;

public function register(): void
{
    Telescope::night();

    $this->hideSensitiveRequestDetails();

    Telescope::filter(function (IncomingEntry $entry) {
        if ($this->app->environment('local')) {
            return true;
        }

        return $entry->isReportableException()
            || $entry->isFailedRequest()
            || $entry->isFailedJob()
            || $entry->isScheduledTask()
            || $entry->hasMonitoredTag();
    });
}

Telescope::night() çağrısı, panelin yalnızca gece saatlerinde kayıt tutmasını sağlar; üretimde veri hacmini düşürmek için kullanışlıdır. hideSensitiveRequestDetails() ise istek başlıkları ve gövdelerindeki hassas alanları maskeler.

gate metodu ile panele kimlerin erişebileceğini tanımlayın:

protected function gate(): void
{
    Gate::define('viewTelescope', function ($user) {
        return in_array($user->email, [
            'admin@example.com',
        ]);
    });
}

Buradaki e-posta listesini kendi yönetici hesaplarınızla değiştirin. Kural olarak, listeyi koda gömmek yerine bir rol/yetki kontrolüne bağlamak daha sürdürülebilirdir.

Üretimde Veri Birikimini Yönetme

Telescope kayıtları zamanla büyür. config/telescope.php içindeki prune ayarı, eski kayıtların temizlenme süresini belirler:

'prune' => [
    'hours' => 24 * 7,
],

Bu ayarın işlemesi için zamanlanmış görevlerin çalışıyor olması gerekir. php artisan schedule:work (geliştirme) veya sunucudaki cron tanımı bunu tetikler.

Pulse Kurulumu

Pulse'u Composer ile ekleyin:

composer require laravel/pulse

Yapılandırma ve migration dosyalarını yayınlayın:

php artisan vendor:publish --provider="Laravel\Pulse\PulseServiceProvider"
php artisan migrate

Pulse paneli varsayılan olarak /pulse yolundadır ve aynı şekilde yetkilendirme gerektirir. config/pulse.php içinde erişim kontrolü tanımlanır:

'ingest' => [
    'driver' => 'storage',
],

'storage' => [
    'driver' => 'database',
    'connection' => env('DB_CONNECTION', 'mysql'),
],

Pulse'un veri toplama işini kuyruğa devretmesi için kuyruk bağlantınızın gerçek bir sürücüye (Redis, database, SQS vb.) işaret ettiğinden emin olun. sync sürücüsü, her isteğin sonunda ek yük bindirir.

Pulse Panosunu Yetkilendirme

Pulse panelinin erişimini de bir gate ile sınırlayın:

use Laravel\Pulse\Facades\Pulse;

Pulse::user(fn ($request) => $request->user());

Daha ayrıntılı kontrol için config/pulse.php içindeki middleware dizisine kendi yetkilendirme middleware'inizi ekleyebilirsiniz. Varsayılan davranışa güvenip paneli herkese açık bırakmayın.

İkisini Birlikte Kullanma

Tipik bir kurulum şöyle görünür:

• Yerel geliştirme: Telescope açık, Pulse kapalı veya sınırlı. Amaç, tek tek istekleri ve sorguları incelemek.
• Ön üretim (staging): İkisi de açık. Pulse ile genel sağlık, Telescope ile şüpheli durumların ayrıntısı incelenir.
• Üretim: Pulse açık, Telescope yalnızca filtrelenmiş olaylar (başarısız job, raporlanabilir exception) için açık ve erişim dar bir gruba kısıtlı.

Bu katmanlama, hem veri hacmini hem de hassas bilgi maruziyetini kontrol altında tutar.

Yaygın Hatalar

• Telescope'u üretimde filtresiz bırakmak. Tüm istek gövdeleri ve sorgular kaydedilir; hem disk/veritabanı şişer hem de hassas veri panelde görünür hâle gelir.
• Gate tanımlamayı unutmak. Panel varsayılan olarak uygulamaya erişimi olan herkese açık olabilir. Yetkilendirmeyi ayrıca yapılandırın.
• sync kuyruk sürücüsüyle Pulse kullanmak. Veri toplama işi istek döngüsüne eklenir; gecikme artar.
• Prune/schedule görevlerini kurmamak. Eski kayıtlar temizlenmez, tablolar kontrolsüz büyür.
• Hassas alanları maskelemeyi atlamak. hideSensitiveRequestDetails ve benzeri ayarlar olmadan parola, token gibi veriler kayda düşebilir.

Güvenlik Etkileri

Her iki araç da uygulamanın iç durumunu dışarıya açar. Bu nedenle:

• Panel erişimini kimlik doğrulama ve yetkilendirmeye bağlayın; mümkünse IP kısıtı veya ayrı bir alt alan adı üzerinden erişim verin.
• Kayıt tutulan veriyi minimumda tutun; gereksiz istek gövdelerini ve başlıkları filtreleyin.
• Kayıtları üretim veritabanından ayrı bir bağlantıda tutmayı değerlendirin; böylece izleme yükü asıl veriyi etkilemez.
• Erişim listelerini düzenli gözden geçirin; ayrılan çalışanların hesaplarını listeden çıkarın.

Sonuç

Telescope ve Pulse, aynı ihtiyacın iki farklı ölçeğine cevap verir: biri olay bazlı derinlik, diğeri sistem geneli görünürlük. Doğru kurulumun anahtarı, hangi ortamda hangi aracın açık olacağını netleştirmek ve panel erişimini baştan yetkilendirmeye bağlamaktır. Kurulum adımlarını uygularken sürüm ve yapılandırma ayrıntılarını kendi ortamınızda doğrulayın; özellikle gate ve filtre ayarlarını üretime çıkmadan önce test edin.