WP-CLI ile Hata Ayıklama: –debug ve –verbose Kullanımı

Tarafındankomut
0 Comments

WordPress sitelerinde bir şeyler ters gittiğinde, çoğu sysadmin önce wp-admin’e giriş yapar, ekrana bakar ve “neden çalışmıyor ki bu?” diye düşünür. Oysa WP-CLI’nin sunduğu hata ayıklama araçları, sana tarayıcıdan hiçbir zaman göremeyeceğin bilgileri saniyeler içinde getirebilir. --debug ve --verbose bayrakları, WP-CLI komutlarının perde arkasında tam olarak ne yaptığını görmeni sağlar. Bu yazıda bu iki parametreyi derinlemesine inceleyecek, gerçek dünya senaryolarında nasıl kullanacağını adım adım göstereceğiz.

–debug ve –verbose Arasındaki Fark

Önce kafaları karıştıran bu soruyu netleştirelim. Bu iki parametre birbirinin yerine geçmez, farklı bilgi katmanları sunar.

–verbose parametresi, komutun çalışırken yaptığı işlemleri daha ayrıntılı listeler. Örneğin bir eklenti güncellemesi yapıyorsan hangi dosyaların indirildiğini, hangi adımların tamamlandığını gösterir. Kullanıcı dostu bir ayrıntı katmanıdır.

–debug parametresi ise çok daha derin bir düzeye iner. PHP hata mesajları, hook’ların tetiklenme süreleri, veritabanı sorguları, WordPress bootstrap süreci ve WP-CLI’nin iç mekanizmasına dair her şeyi döker. Bir nevi “her şeyi bana göster” modudur.

Pratikte şunu söyleyebilirim: Bir komutun ne yaptığını anlamak istiyorsan --verbose, neden çalışmadığını anlamak istiyorsan --debug kullan.

–debug Parametresinin Anatomisi

Temel Kullanım

En basit haliyle --debug şöyle kullanılır:

wp plugin list --debug

Bu komutu çalıştırdığında ekrana akan çıktının ilk satırları şöyle görünür:

Debug (bootstrap): Beginning WordPress load... (0.021s)
Debug (bootstrap): wp-settings.php loaded. (0.487s)
Debug (bootstrap): Loaded WordPress 6.4.2 in 0.508s.
Debug (core): Called wp_cache_flush(). (0.002s)

Her satırdaki parantez içindeki etiket (bootstrap, core vb.) hangi bileşenden geldiğini gösterir. Süre bilgisi ise o noktaya kadar geçen toplam zamanı verir.

Belirli Bir Gruba Odaklanmak

--debug parametresine bir değer vererek sadece belirli bir grubun çıktısını filtreleyebilirsin:

wp plugin activate woocommerce --debug=bootstrap

Bu şekilde sadece bootstrap sürecine ait debug mesajlarını görürsün. Diğer gruplar için de şu etiketleri kullanabilirsin:

  • bootstrap: WordPress yüklenme süreci
  • hooks: Action ve filter hook’larının tetiklenme bilgileri
  • db: Veritabanı sorguları
  • plugin: Eklenti yükleme aşamaları
  • core: WP-CLI çekirdek işlemleri

Performans Sorunlarını Tespit Etmek

Bir sitenin WP-CLI komutlarına yavaş yanıt verdiğini düşün. --debug çıktısındaki zaman damgaları sana çok şey söyler:

wp option get siteurl --debug 2>&1 | grep -E "Debug|Warning|Error"
Debug (bootstrap): Beginning WordPress load... (0.019s)
Debug (bootstrap): wp-settings.php loaded. (2.847s)
Debug (bootstrap): Loaded WordPress 6.4.2 in 2.861s.

İkinci satırdaki 2.847s rakamı alarm verici. WordPress ayarları yüklenirken neredeyse 3 saniye geçiyor. Bu genellikle şu sorunlara işaret eder:

  • Veritabanı bağlantı gecikmesi
  • Autoload seçeneği aktif çok fazla eklenti
  • Yavaş bir harici API çağrısı yapan bir eklenti

–verbose Parametresinin Kullanımı

Güncelleme Süreçlerini İzlemek

--verbose parametresi özellikle toplu işlemlerde işe yarar. Şu komutu ele alalım:

wp plugin update --all --verbose

Normal çıktı şöyle görünür:

Enabling Maintenance mode...
Downloading update from https://...
Unpacking the update...
Installing the latest version...
Removing the old version of the plugin...
Plugin updated successfully.
Disabling Maintenance mode...

Bu bilgi seviyesi çoğu durumda yeterlidir. Hangi URL’den indirme yapıldığını, bakım modunun ne zaman açılıp kapandığını, sıranın nerede takıldığını görmek için idealdir.

Import İşlemlerinde verbose Kullanımı

WooCommerce ürün import’ları veya büyük WordPress içerik aktarımlarında --verbose hayat kurtarır:

wp import /var/www/html/wp-content/uploads/export.xml --authors=create --verbose

Bu komut çalışırken her bir post, kategori ve medya öğesinin işlenip işlenmediğini anlık olarak gösterir. 10.000 ürünlük bir import’ta hangi satırda takıldığını anlamak için başka türlü saatlerce beklemek zorunda kalırsın.

Gerçek Dünya Senaryoları

Senaryo 1: Eklenti Aktivasyonu Neden Çöküyor?

Bir müşteri sitesinde eklenti aktive etmeye çalışıyorsun ama komut hata veriyor ya da sessizce başarısız oluyor:

wp plugin activate my-custom-plugin --debug 2>&1
wp plugin activate my-custom-plugin --debug 2>&1 | tee /tmp/debug-output.txt

İkinci komut hem ekrana yazdırır hem de /tmp/debug-output.txt dosyasına kaydeder. Çıktıda şuna benzer bir şey görebilirsin:

Debug (bootstrap): wp-settings.php loaded. (0.312s)
Warning: Cannot redeclare my_custom_function() (previously declared in /wp-content/plugins/other-plugin/functions.php:45) in /wp-content/plugins/my-custom-plugin/functions.php on line 23
Error: Plugin could not be activated because it triggered a fatal error.

İşte sorun: Başka bir eklentide zaten tanımlı olan bir fonksiyon ismi çakışması var. --debug olmadan sadece “Plugin could not be activated” hatası görürdün, sorunun kaynağını bulamazdın.

Senaryo 2: WooCommerce Cron İşleri Neden Çalışmıyor?

WooCommerce siparişlerin durumları otomatik güncellenmiyorsa, cron işlerini debug modunda inceleyebilirsin:

wp cron event run woocommerce_scheduled_sales --debug 2>&1

Çıktıda şunu görüyorsun:

Debug (bootstrap): Loaded WordPress 6.4.1 in 0.445s.
Debug (hooks): Running action: woocommerce_scheduled_sales
PHP Fatal error: Allowed memory size of 134217728 bytes exhausted (tried to allocate 20971520 bytes)

Bellek sınırına çarpmış. Şimdi ne yapacağını biliyorsun. PHP bellek limitini artırman ya da cron görevini daha küçük parçalara bölmem gerekiyor.

Senaryo 3: Database Migration Sonrası URL Sorunları

Siteyi bir sunucudan diğerine taşıdıktan sonra URL değişikliği yapıyorsun ama bir şeyler ters gidiyor:

wp search-replace 'https://eski-domain.com' 'https://yeni-domain.com' --dry-run --verbose --debug 2>&1

--dry-run ile gerçek değişiklik yapmadan önce ne olacağını görebilirsin. --verbose ile hangi tablolarda kaç satır etkilendiğini, --debug ile ise işlemin her adımında ne yapıldığını takip edebilirsin. Bu üçlü kombinasyon production ortamlarında değişiklik yapmadan önce olmazsa olmaz.

wp search-replace 'https://eski-domain.com' 'https://yeni-domain.com' 
  --tables=wp_options,wp_posts,wp_postmeta 
  --verbose 
  --report-changed-only

Belirli tablolarla sınırlandırılmış bu versiyon daha hızlı çalışır ve sadece değişen satırları raporlar.

Senaryo 4: Toplu Kullanıcı İşlemlerinde Hata Takibi

10.000 kullanıcılı bir sitede belirli kullanıcı rollerini güncellemek istiyorsun:

wp user list --role=subscriber --field=ID | 
  xargs -I {} wp user set-role {} contributor --debug 2>&1 | 
  grep -E "^(Debug|Error|Warning|Success)" | 
  tee /var/log/wp-user-update.log

Bu komut zinciri şunları yapar:

  • Tüm subscriber ID’lerini listeler
  • Her biri için rolü contributor olarak günceller
  • Debug, Error, Warning ve Success satırlarını filtreler
  • Hem ekrana yazar hem de log dosyasına kaydeder

Debug Çıktısını Yönetmek

stderr’e Yönlendirme

WP-CLI, --debug çıktısını stderr kanalına yazar, normal komut çıktısını ise stdout‘a. Bu ayrımı kullanarak debug bilgisini normal çıktıdan ayırabilirsin:

# Sadece debug çıktısını görmek için
wp plugin list --debug 2>&1 1>/dev/null

# Sadece normal çıktıyı görmek için (debug'ı yok saymak)
wp plugin list --debug 2>/dev/null

# Her ikisini ayrı dosyalara kaydetmek için
wp plugin list --debug 1>/tmp/normal-output.txt 2>/tmp/debug-output.txt

grep ile Filtrelemek

Uzun bir debug çıktısında sadece belirli bilgileri aramak için grep kullanımı:

# Sadece zamanlama bilgilerini görmek
wp theme activate twentytwentyfour --debug 2>&1 | grep -E "([0-9]+.[0-9]+s)"

# Sadece hata ve uyarıları görmek
wp core update --debug 2>&1 | grep -iE "(error|warning|fatal|critical)"

# Bootstrap süresini ölçmek
wp eval 'echo "OK";' --debug 2>&1 | grep "Loaded WordPress"

Zaman Damgalı Loglama

Uzun süren işlemleri izlemek için zaman damgası ekleyebilirsin:

wp media regenerate --yes --verbose 2>&1 | 
  while IFS= read -r line; do
    echo "$(date '+%Y-%m-%d %H:%M:%S') $line"
  done | tee /var/log/wp-media-regenerate.log

Bu yöntem özellikle büyük sitelerde medya yeniden oluşturma işlemlerinde ne kadar süreceğini ve hangi adımda takıldığını anlamak için çok işe yarar.

WP_DEBUG ile WP-CLI –debug Arasındaki İlişki

Burada önemli bir nokta var: WP-CLI’nin --debug parametresi ile wp-config.php‘deki WP_DEBUG sabiti birbirinden bağımsızdır.

WP_DEBUG tanımlı olmasa bile WP-CLI’nin --debug bayrağı kendi iç debug mekanizmasını çalıştırır. Ancak bazı eklentiler sadece WP_DEBUG aktifken hata çıktısı üretir. Bu yüzden gerçek anlamda kapsamlı bir hata ayıklama için ikisini birlikte kullanman gerekebilir:

wp --debug eval '
define("WP_DEBUG", true);
define("WP_DEBUG_LOG", true);
$plugin = "woocommerce/woocommerce.php";
include_once(WP_PLUGIN_DIR . "/" . $plugin);
'

Ya da doğrudan wp-config.php değerlerini kontrol edebilirsin:

wp config get WP_DEBUG --debug
wp config get WP_DEBUG_LOG --debug
wp config get WP_DEBUG_DISPLAY --debug

Otomasyon ve CI/CD Süreçlerinde Kullanım

Deployment Script’lerinde Hata Yönetimi

Bir deployment script’inde WP-CLI komutlarını hata yönetimiyle birlikte kullanmak:

#!/bin/bash

DEPLOY_LOG="/var/log/wp-deploy-$(date +%Y%m%d-%H%M%S).log"
WP_PATH="/var/www/html"

echo "=== Deployment başladı: $(date) ===" | tee -a $DEPLOY_LOG

# Core güncelle, hata çıkışını yakala
if ! wp --path=$WP_PATH core update --verbose 2>&1 | tee -a $DEPLOY_LOG; then
    echo "HATA: Core güncellemesi başarısız!" | tee -a $DEPLOY_LOG
    exit 1
fi

# Eklentileri güncelle, debug bilgisiyle
wp --path=$WP_PATH plugin update --all --verbose 2>&1 | tee -a $DEPLOY_LOG

# Başarısız güncelleme var mı kontrol et
FAILED=$(grep -c "Error|Fatal|failed" $DEPLOY_LOG)
if [ $FAILED -gt 0 ]; then
    echo "UYARI: $FAILED hata tespit edildi. Log: $DEPLOY_LOG"
    # Slack bildirimi gönder, email at vb.
fi

echo "=== Deployment tamamlandı: $(date) ===" | tee -a $DEPLOY_LOG

Health Check Script’i

Sunucu monitoring için WP-CLI debug çıktısını kullanan basit bir health check:

#!/bin/bash

WP_PATH="/var/www/html"

# WordPress yüklenme süresini ölç
LOAD_TIME=$(wp --path=$WP_PATH eval 'echo "OK";' --debug 2>&1 | 
  grep "Loaded WordPress" | 
  grep -oE "[0-9]+.[0-9]+s")

echo "WordPress yüklenme süresi: $LOAD_TIME"

# Kritik eşik kontrolü
LOAD_SECONDS=$(echo $LOAD_TIME | sed 's/s//')
if (( $(echo "$LOAD_SECONDS > 2.0" | bc -l) )); then
    echo "KRITIK: WordPress $LOAD_SECONDS saniyede yükleniyor!"
    # Alert gönder
fi

Sık Yapılan Hatalar

Debug çıktısını parse etmeye çalışmak: Debug formatı garantili değildir, WP-CLI sürümleri arasında değişebilir. Otomasyon scriptlerinde debug çıktısını parse etmek yerine komutun çıkış kodunu ($?) kullan.

Her zaman –debug kullanmak: --debug çıktısı çok büyük olabilir ve özellikle büyük sitelerde performansı etkiler. Production ortamında sürekli debug modunda çalışma.

stderr’i ignore etmek: WP-CLI önemli uyarıları ve hataları stderr’e yazar. Script’lerinde 2>&1 eklemeden hata mesajlarını kaçırabilirsin.

Çıktıyı log’a kaydetmemek: Debug modunda çalıştırdığın bir komutun çıktısı ekrandan kaydıktan sonra geri getiremezsin. Kritik işlemlerde her zaman tee ile log’a kaydet.

Pratik İpuçları

WP-CLI’nin --prompt parametresini --debug ile birleştirerek interaktif debug oturumları açabilirsin. Büyük sitelerde wp --debug shell ile interaktif WP-CLI shell’i açıp komutları tek tek test edebilirsin.

wp doctor check --all komutu (wp-cli/doctor-command paketi kuruluysa) da --debug ile birlikte kullanıldığında sitenin sağlık sorunlarını çok daha ayrıntılı raporlar.

Multisite kurulumlarında debug yaparken hangi siteyi hedeflediğini mutlaka belirt:

wp --url=https://alt-site.example.com plugin list --debug 2>&1

Aksi halde hata network genelinde mi yoksa sadece bir alt sitede mi diye saatlerce kafa yorabilirsin.

Sonuç

WP-CLI’nin --debug ve --verbose parametreleri, WordPress site yönetiminde gerçek anlamda görünürlük sağlar. Bir eklentinin neden aktive olmadığını, bir cron görevinin neden çalışmadığını ya da WordPress bootstrap sürecinin nerede yavaşladığını bu araçlar olmadan bulmak kör adamın fil tarifi gibi olur.

Günlük iş akışında önerim şu: Bir komutun davranışını anlamak istediğinde --verbose ile başla. Komut beklendiği gibi çalışmıyorsa ya da hata veriyorsa --debug ekle ve çıktıyı bir dosyaya kaydet. Grep ile filtrele, zaman damgalarına bak, hata mesajlarını incele.

Deployment scriptlerinde bu parametreleri log mekanizmasıyla birleştirmek ise seni gece yarısı “neden çöktü ki?” sorusuyla boğuşmaktan kurtarır. Çünkü iyi bir sysadmin sorunu çözen değil, sorunun neden çıktığını bilen ve bir dahaki seferinde önleyen kişidir.

Bir yanıt yazın

E-posta adresiniz yayınlanmayacak. Gerekli alanlar * ile işaretlenmişlerdir