az webapp deploy’da Zenginleştirilmiş Hata Çıktıları

Azure App Service üzerinde yapılan dağıtımlar başarısız olduğunda, dağıtım API’sinin döndürdüğü hata mesajları çoğu zaman sorunun kaynağını ya da atılması gereken adımları net biçimde ortaya koymuyor. Bu belirsizlik, özellikle Linux üzerinde çalışan App Service uygulamalarına yapılan yayınlarda geliştiricileri fazladan log incelemesine ve deneme yanılmayla ilerlemeye itiyor. Azure App Service ekibi bu deneyimi iyileştirmek için az webapp deploy komutuna yeni bir anahtar ekledi: --enriched-errors.

–enriched-errors ne işe yarıyor?

Yeni eklenen --enriched-errors true anahtarı, Linux için Azure App Service’e yapılan dağıtımlarda başarısız olan işlemlere ilişkin bağlam açısından zenginleştirilmiş tanılama bilgilerini doğrudan Azure CLI çıktısında gösteriyor. Böylece hatayı yorumlamak için ayrı log dosyalarına ya da portal ekranlarına gitmek gerekmiyor; ilgili bilgiler dağıtım komutunun çıktısında toplu halde sunuluyor.

Zenginleştirilmiş çıktıda şu bilgiler yer alabiliyor:

• Bir hata kodu (error code)
• Dağıtım bağlamı (deployment context)
• Ham hata mesajı (raw error)
• Önerilen çözümler (suggested fixes)
• GitHub Copilot ile birlikte kullanabileceğiniz hazır bir prompt

Anahtar varsayılan olarak devre dışı geliyor; mevcut çıktı davranışı korunuyor. Zenginleştirilmiş bilgileri görmek isteyen kullanıcıların dağıtım komutunda bu bayrağı açıkça etkinleştirmesi gerekiyor.

Komutun kullanımı

Zenginleştirilmiş hataları etkinleştirmek için mevcut az webapp deploy komutuna --enriched-errors true parametresini eklemek yeterli. Genel kullanım şöyle:

az webapp deploy \
--resource-group <resource-group-name> \
--name <app-name> \
--src-path <path-to-package> \
--enriched-errors true

Burada kaynak grubu adı, uygulama adı ve dağıtılacak paketin yolu her zamanki gibi belirtiliyor. Tek fark, komutun sonuna eklenen zenginleştirilmiş hata anahtarı.

Örnek bir hata çıktısı

Zenginleştirilmiş hata modu açıkken başarısız bir dağıtım şu tarzda bir çıktı üretebiliyor:

Error Code  : ArtifactStackMismatch
Stage       : Deployment
Runtime     : DOTNETCORE|9.0
Deploy Type : WarDeploy
Kudu Status : 400
Raw Error:
Artifact type = 'War' cannot be deployed to stack = 'DOTNETCORE'.
Suggested Fixes:
- Ensure the artifact type matches the app's runtime stack
- Check the current linuxFxVersion
- Update the runtime stack if needed

Bu örnekte hata kodu, dağıtımın hangi aşamada başarısız olduğu, hedef runtime, kullanılan dağıtım türü ve Kudu’nun döndürdüğü HTTP durum kodu bir arada görülüyor. Ham hata mesajı, sorunun WAR türünde bir artefaktın DOTNETCORE stack’ine dağıtılmaya çalışılmasından kaynaklandığını doğrudan söylüyor. Önerilen çözümler bölümünde ise artefakt türünün uygulamanın runtime yığınıyla eşleştirilmesi, mevcut linuxFxVersion değerinin kontrol edilmesi ve gerekirse runtime yığınının güncellenmesi öneriliyor.

Hangi durumlarda daha net bir tanı sağlıyor?

Zenginleştirilmiş çıktılar sayesinde başarısızlığın kökeninin şunlardan hangisi olduğunu ayırt etmek kolaylaşıyor:

• Artefakt türü ile runtime yığını arasındaki uyumsuzluklar
• Geçersiz bir dağıtım yolu (deployment path) kullanımı
• Zorunlu parametrelerin eksik verilmesi
• WEBSITE_RUN_FROM_PACKAGE gibi ayarlardan doğan yapılandırma çatışmaları

Bu tür durumlar klasik hata mesajlarında genellikle tek satırlık bir açıklamaya sıkışıyor; zenginleştirilmiş modda ise daha yapılandırılmış biçimde raporlandığından, sorunun kaynağını izole etmek ve çözüm adımlarını belirlemek kolaylaşıyor.

GitHub Copilot ile birlikte kullanım

Zenginleştirilmiş çıktının bir başka pratik yönü, GitHub Copilot’a devredilmek üzere hazırlanmış bir prompt içermesi. Çıktıda yer alan tam hata detaylarını aşağıdaki prompt ile birlikte Copilot’a yapıştırarak daha spesifik yönlendirmeler alabilirsiniz:

Why did my Linux App Service deployment fail and how do I fix it?

Bu yaklaşım, dağıtım yapılandırmanıza ve karşılaşılan hataya özgü, bağlama duyarlı öneriler almaya yardımcı oluyor. Hata çıktısını manuel yorumlamak yerine, Copilot’un elinizdeki tanılama bilgilerini işleyerek yol göstermesini sağlayabiliyorsunuz.

Özet

--enriched-errors anahtarı, Azure CLI üzerinden Linux için Azure App Service’e dağıtım yapan geliştiricilere hata kodu, dağıtım bağlamı, ham hata, önerilen düzeltmeler ve Copilot’a hazır bir prompt içeren, çok daha eyleme dönük bir hata çıktısı sunuyor. Varsayılan olarak kapalı olduğundan mevcut senaryoları etkilemiyor; komuta eklendiğinde ise hata ayıklama sürecini belirgin biçimde hızlandırabiliyor. App Service for Linux üzerinde az webapp deploy kullanan ekipler için, bir sonraki başarısız dağıtımda denemeye değer bir seçenek.

Kaynaklar ve İleri Okuma

• Better Deployment Errors in az webapp deploy — Azure App Service
• Azure App Service Slot Deployment azd ile Kolaylaştı
• Azure Container Apps’ta Blue-Green Deployment: Canlı Geçiş Artık Bu Kadar Kolay