Tracy ile Başlangıç

PHP, geliştiricilere epey özgürlük tanıdığından, saptanması zor hatalar üretmeye çok uygun bir dildir. Bu da Tracy gibi bir hata ayıklama aracını daha da değerli kılar. PHP'nin tanılama araçları arasında mutlak zirveyi temsil eder.

Tracy ile bugün ilk kez karşılaşıyorsanız, inanın ki hayatınız Tracy'den önceki zaman ve Tracy'yle geçen zaman diye ikiye ayrılmaya başlayacak. İyi olan kısma hoş geldiniz!

Kurulum

Tracy'yi kurmanın en iyi yolu, en son paketi indirmek ya da Composer kullanmaktır:

composer require tracy/tracy

Alternatif olarak paketin tamamını ya da tracy.phar dosyasını indirebilirsiniz.

Kullanım

Tracy, programın en başında, herhangi bir çıktı gönderilmeden önce, olabildiğince erken Tracy\Debugger::enable() metodu çağrılarak etkinleştirilir:

use Tracy\Debugger;

require 'vendor/autoload.php'; // ya da tracy.phar

Debugger::enable();

Sayfada ilk fark edeceğiniz şey, sağ alt köşedeki Tracy Bar olacak. Onu göremiyorsanız, bu Tracy'nin üretim kipinde çalıştığı anlamına gelebilir. Çünkü Tracy güvenlik nedeniyle yalnızca localhost'ta görünür. Çalışıp çalışmadığını sınamak için Debugger::enable(Debugger::Development) parametresiyle onu geçici olarak geliştirme kipine alabilirsiniz.

Tracy Bar

Tracy Bar, sayfanın sağ alt köşesinde görüntülenen yüzen bir paneldir. Onu fareyle taşıyabilirsiniz; sayfa yeniden yüklendikten sonra konumunu anımsar.

Tracy Bar'a başka yararlı paneller ekleyebilirsiniz. İlginç olanları eklentilerde bulabilir ya da kendinizinkini yazabilirsiniz.

Tracy Bar'ı göstermek istemiyorsanız şunu ayarlayın:

Debugger::$showBar = false;

Hataların ve İstisnaların Görselleştirilmesi

PHP'nin hataları nasıl bildirdiğini elbette biliyorsunuz: sayfanın kaynak koduna şuna benzer bir şey yazdırır:

Parse error:  syntax error, unexpected '}' in HomePresenter.php on line 15

ya da yakalanmamış bir istisna:

Fatal error:  Uncaught Nette\MemberAccessException: Call to undefined method Nette\Application\UI\Form::addTest()? in /sandbox/vendor/nette/utils/src/Utils/ObjectMixin.php:100
Stack trace:
#0 /sandbox/vendor/nette/utils/src/Utils/Object.php(75): Nette\Utils\ObjectMixin::call(Object(Nette\Application\UI\Form), 'addTest', Array)
#1 /sandbox/app/Forms/SignFormFactory.php(32): Nette\Object->__call('addTest', Array)
#2 /sandbox/app/Presentation/Sign/SignPresenter.php(21): App\Forms\SignFormFactory->create()
#3 /sandbox/vendor/nette/component-model/src/ComponentModel/Container.php(181): App\Presentation\Sign\SignPresenter->createComponentSignInForm('signInForm')
#4 /sandbox/vendor/nette/component-model/src/ComponentModel/Container.php(139): Nette\ComponentModel\Container->createComponent('signInForm')
#5 /sandbox/temp/cache/latte/15206b353f351f6bfca2c36cc.php(17): Nette\ComponentModel\Co in /sandbox/vendor/nette/utils/src/Utils/ObjectMixin.php on line 100

Böyle bir çıktıda yol bulmak pek kolay değil. Tracy'yi açarsanız, hatalar ve istisnalar tümüyle farklı bir biçimde görüntülenir:

Hata mesajı resmen haykırır. Hatanın oluştuğu satırın vurgulandığı kaynak kod parçasını görürsünüz. Call to undefined method Nette\Http\User::isLogedIn() mesajı hatayı açıkça anlatır. Sayfanın tamamı etkileşimlidir; ayrıntılar için tıklayarak ilerleyebilirsiniz. Deneyin.

Ve tahmin edin ne oldu? Ölümcül hatalar da aynı şekilde yakalanır ve görüntülenir. Hiçbir eklenti kurmaya gerek kalmadan.

Bir değişken adındaki yazım hatası ya da var olmayan bir dosyayı açma girişimi gibi hatalar, E_NOTICE ya da E_WARNING düzeyinde raporlar üretir. Bunlar sayfanın grafik yerleşimi içinde kolayca gözden kaçabilir, hatta tümüyle görünmez olabilir (kaynak koda bakmazsanız). Bırakın onları Tracy yönetsin:

Ya da hata gibi görüntülenebilirler:

Debugger::$strictMode = true; // tüm hataları göster
Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // deprecated notice'lar dışında tüm hatalar

Not: Tracy, etkinleştirildiğinde hata bildirim düzeyini E_ALL yapar. Bunu değiştirmek isterseniz enable() çağrısından sonra yapın.

Geliştirme ve Üretim Kipi

Gördüğünüz gibi Tracy epey konuşkandır; bu geliştirme ortamında değerlidir, ama üretim sunucusunda felakete yol açardı. Çünkü orada hiçbir hata ayıklama bilgisi görüntülenmemelidir. Bu yüzden Tracy'nin ortamı otomatik saptama yeteneği vardır. Örnek canlı bir sunucuda çalıştırılırsa hata görüntülenmek yerine günlüklenir ve ziyaretçi yalnızca kullanıcı dostu bir mesaj görür:

Üretim kipi, dump() ile gönderilen tüm hata ayıklama bilgilerinin ve elbette PHP'nin ürettiği tüm hata mesajlarının görüntülenmesini bastırır. Yani kodda bir yerde dump($obj) unuttuysanız endişelenmenize gerek yok, üretim sunucusunda hiçbir şey görüntülenmeyecek.

Kip otomatik saptaması nasıl çalışır? Uygulama localhost'ta çalışıyorsa (yani IP adresi 127.0.0.1 ya da ::1 ise) ve bir proxy yoksa (yani onun HTTP header'ı bulunmuyorsa) kip geliştirmedir. Aksi hâlde üretim kipinde çalışır.

Geliştirme kipini başka durumlarda, örneğin belirli bir IP adresinden erişen geliştiriciler için açmak isterseniz, bunu enable() metodunun parametresi olarak belirtebilirsiniz:

Debugger::enable('23.75.345.200'); // IP adreslerinden oluşan bir dizi de verebilirsiniz

IP adresini bir çerezle birleştirmenizi kesinlikle öneririz. tracy-debug çerezinde gizli bir token, örneğin secret1234, saklayın; böylece geliştirme kipini yalnızca belirli bir IP adresinden erişen ve çerezinde sözü edilen token bulunan geliştiriciler için etkinleştirin:

Debugger::enable('secret1234@23.75.345.200');

Geliştirme/üretim kipini, enable() metodunun parametresi olarak Debugger::Development ya da Debugger::Production sabitleriyle doğrudan da ayarlayabilirsiniz.

Nette Framework kullanıyorsanız, kipin onun için nasıl ayarlanacağına bakın; o zaman Tracy için de kullanılır.

Hata Günlükleme

Üretim kipinde Tracy, tüm hataları ve yakalanan istisnaları otomatik olarak bir metin günlüğüne yazar. Günlüklemenin çalışması için $logDirectory değişkeninde günlük dizinine giden mutlak yolu ayarlamanız ya da onu enable() metoduna ikinci parametre olarak vermeniz gerekir:

Debugger::$logDirectory = __DIR__ . '/log';

Hata günlüklemesi son derece yararlıdır. Uygulamanızın tüm kullanıcılarının aslında sizin için bedavaya birinci sınıf iş yaparak hata bulan beta test kullanıcıları olduğunu düşünün; onların değerli raporlarını fark etmeden çöpe atmak akılsızca olurdu.

Kendi mesajlarınızı ya da yakalanan istisnaları günlüklemeniz gerekiyorsa log() metodunu kullanın:

Debugger::log('Beklenmedik hata'); // metin mesajı

try {
	criticalOperation();
} catch (Exception $e) {
	Debugger::log($e); // istisnayı günlükle
	// ya da
	Debugger::log($e, Debugger::ERROR); // ayrıca e-posta bildirimi gönderir
}

Tracy'nin E_NOTICE ya da E_WARNING gibi PHP hatalarını ayrıntılı bilgiyle (HTML raporuyla) günüklemesini istiyorsanız Debugger::$logSeverity ayarını yapın:

Debugger::$logSeverity = E_NOTICE | E_WARNING;

Gerçek bir profesyonel için hata günlüğü temel bir bilgi kaynağıdır ve her yeni hatadan hemen haberdar olmak ister. Tracy buna, yeni günlük kayıtları için e-posta bildirimi gönderebilerek uyum sağlar. $email değişkeni bu e-postaların nereye gönderileceğini belirler:

Debugger::$email = 'admin@example.com';

Nette Framework'ün tamamını kullanıyorsanız, bunu ve diğerlerini yapılandırma dosyasında ayarlayabilirsiniz.

E-posta kutunuzun dolup taşmasını önlemek için Tracy yalnızca bir mesaj gönderir ve bir email-sent dosyası oluşturur. Geliştirici e-posta bildirimini aldığında günlüğü denetler, uygulamayı düzeltir ve email-sent izleme dosyasını siler. Bu, e-posta göndermeyi yeniden etkinleştirir.

Markdown Raporları

Tracy, her log/exception-*.html dosyasının yanına aynı içeriği markdown biçiminde taşıyan bir .md kardeşi yazar: mesaj, çağrı yığını ve kaynak kod parçaları. Bu dosyalar, uygulamayla bir yapay zekâ ajanının çalışıp çalışmadığından bağımsız olarak koşulsuz oluşturulur.

Amaçları toplu işlemedir. Yüzlerce HTML raporunu tek tek tıklayarak gezmek yerine, günlük dizininin tamamını bir yapay zekâ ajanına devredip her raporu kodun güncel durumuyla karşılaştırmasını ve düzeltmeler önermesini sağlayabilirsiniz.

Yapay Zekâ Ajanı Desteği

Bir yapay zekâ ajanı uygulamanızı bir tarayıcı üzerinden sürdüğünde (Chrome DevTools MCP, Playwright, Puppeteer), Tracy bunu JavaScript'in navigator.webdriver özelliğiyle saptar ve temel tanılama bilgilerinin markdown sürümünü, standart arayüzün yanı sıra tarayıcı konsoluna gönderir:

• BlueScreen – kırmızı ekranın yanı sıra console.error() metoduna gönderilen istisna, çağrı yığını ve değişken değerleri; hem eşzamanlı render'da hem de AJAX hatalarında.
• Tracy Bar – ana panellerin (SQL, Errors, Dumps) console.log() metoduna gönderilen markdown özeti.
• Debugger::dump() – sıradan HTML çıktısının yanı sıra düz metin bir sürüm; böylece dökümler sayfanın içinde kaybolmaz.
• Üretimdeki 500 sayfası – console.error(), ajana bir hata oluştuğunu ve ayrıntıların sunucuda günlüklendiğini bildirir.

Saptama, tracy-webdriver=1 çerezini ayarlar; markdown çıktısını sıradan bir tarayıcıdan etkinleştirmek için onu DevTools'ta elle de ayarlayabilirsiniz. Ajan etkinleştirmesi, her log/exception-*.html dosyasının yanına yazılan .md kardeşlerini etkilemez; onlar koşulsuz üretilir ve üretim günlüklerinin toplu işlenmesinin temelini oluşturur.

Özel Tracy Bar panelleri, getAgentInfo() metodunu uygulayarak kendi markdown çıktılarını sağlayabilir. Claude Code kullanıcıları için Nette eklentisi, ajana Tracy'nin çıktısını list_console_messages() içinden nasıl okuyacağını öğreten tracy-debugging becerisini içerir.

Dosyaları Düzenleyicide Açma

Hata sayfası görüntülendiğinde dosya adlarına tıklayabilirsiniz; dosyalar düzenleyicinizde, imleç ilgili satırda olacak şekilde açılır. Dosyalar oluşturulabilir (create file eylemi) ya da içlerindeki hatalar düzeltilebilir (fix it eylemi). Bunun için tarayıcıyı ve sistemi yapılandırmanız gerekir.

Desteklenen PHP Sürümleri

En son yama sürümleri için geçerlidir.

Port'lar

Bu, diğer framework'lere ve CMS'lere yapılmış resmi olmayan port'ların listesidir:

• Drupal 7
• Laravel framework: recca0120/laravel-tracy, whipsterCZ/laravel-tracy
• OpenCart
• ProcessWire CMS/CMF
• Slim Framework
• Symfony framework: kutny/tracy-bundle, VasekPurchart/Tracy-Blue-Screen-Bundle
• WordPress