Java için Azure SDK'sında günlüğe kaydetmeyi yapılandırma

Bu makale, Java için Azure SDK’sını kullanan uygulamalarda günlük kaydının nasıl etkinleştirileceğine genel bir bakış sunar. Java için Azure istemci kitaplıkları iki günlüğe kaydetme seçeneği sunar:

  • Geçici hata ayıklama amacıyla yerleşik bir kayıt sistemi.
  • SLF4J arabirimini kullanarak günlüğe kaydetme desteği.

SLF4J'yi kullanın çünkü Java ekosisteminde iyi bilinir ve iyi belgelenmiştir. Daha fazla bilgi içinSLF4J kullanıcı kılavuzuna bakın.

Bu makale, popüler Java günlük çerçevelerinin çoğunu kapsayan diğer makalelere bağlantılar sağlar. Bu diğer makaleler yapılandırma örnekleri sağlar ve Azure istemci kitaplıklarının günlük çerçevelerini nasıl kullanabileceğini açıklar.

Hangi günlükleme yapılandırmasını kullanırsanız kullanın, aynı günlük çıktısını elde edersiniz çünkü Java için Azure istemci kitaplıklarındaki tüm günlük çıktıları azure-core ClientLogger soyutlaması üzerinden yönlendirilir.

Bu makalenin geri kalanı, tüm kullanılabilir günlük seçeneklerinin konfigürasyonunu ayrıntılı şekilde açıklamaktadır.

HTTP isteği ve yanıt günlüğünü etkinleştirme

HTTP isteği ve yanıt günlüğü varsayılan olarak kapalıdır. Http üzerinden Azure hizmetleriyle iletişim kuran istemcileri, aldıkları her istek ve yanıt (veya özel durum) için bir günlük kaydı yazmak üzere yapılandırabilirsiniz.

OpenTelemetry kullanıyorsanız, HTTP istekleri için günlük yerine dağıtılmış izleme kullanmayı düşünün. Daha fazla bilgi için bkz. Java için Azure SDK'da izlemeyi yapılandırma.

Ortam değişkeniyle HTTP günlüğünü yapılandırma

Tüm istemciler için HTTP günlüklerini etkinleştirmek üzere AZURE_HTTP_LOG_DETAIL_LEVEL ortam değişkenini kullanın. Bu değişkeni aşağıdaki değerlerden birine ayarlayın:

  • NONE: HTTP günlükleri kapalı. Bu değer varsayılan değerdir.
  • BASIC: HTTP günlükleri istek yöntemini, temizlenmiş istek URL'sini, deneme sayısını, yanıt kodunu ve istek ve yanıt gövdeleri için içerik uzunluğunu içerir.
  • HEADERS: HTTP günlükleri tüm temel ayrıntıları içerir ve ayrıca günlüğe kaydetme amacıyla güvenli olduğu bilinen üst bilgileri içerir; yani gizli diziler veya hassas bilgiler içermez. Üst bilgi adlarının tam listesi HttpLogOptions sınıfında kullanılabilir.
  • BODY_AND_HEADERS: HTTP günlükleri, düzey tarafından HEADERS sağlanan tüm ayrıntıları içerir ve ayrıca 16 KB'tan küçük ve yazdırılabilir oldukları sürece istek ve yanıt gövdelerini içerir.

Uyarı

İstek URL'si temizlenir; diğer bir ifadeyle, api-version değeri hariç tüm sorgu parametresi değerleri gizlenir. Tek tek istemci kitaplıkları, izin verilenler listesine güvenli olduğu bilinen diğer sorgu parametrelerini ekleyebilir.

Örneğin, Azure Blob Depolama paylaşılan erişim imzası (SAS) URL'si aşağıdaki biçimde günlüğe kaydedilir: https://myaccount.blob.core.windows.net/pictures/profile.jpg?sv=REDACTED&st=REDACTED&se=REDACTED&sr=REDACTED&sp=REDACTED&rscd=REDACTED&rsct=REDACTED&sig=REDACTED

Uyarı

İstek ve yanıt gövdelerini üretim ortamında günlüğe kaydetmeyin; çünkü hassas bilgiler içerebilir, performansı önemli ölçüde etkileyebilir, içeriğin nasıl arabelleğe alındığını değiştirebilir ve diğer yan etkilere neden olabilir.

Kod içinde HTTP kaydını konfigüre et

HttpTrait<T> arabirimini uygulayan Azure istemci oluşturucuları, kod tabanlı HTTP günlük yapılandırmasını destekler. Kod tabanlı yapılandırma tek tek istemci örnekleri için geçerlidir ve ortam değişkeni yapılandırmasına kıyasla daha fazla seçenek ve özelleştirme sağlar.

Günlükleri yapılandırmak için, HttpLogOptions örneğini ilgili istemci oluşturucusunun httpLogOptions yöntemine geçirin. Aşağıdaki kod, Uygulama Yapılandırma hizmeti için bir örnek gösterir:

HttpLogOptions httpLogOptions = new HttpLogOptions()
        .setLogLevel(HttpLogDetailLevel.HEADERS)
        .addAllowedHeaderName("Accept-Ranges")
        .addAllowedQueryParamName("label");

ConfigurationClient configurationClient = new ConfigurationClientBuilder()
        .httpLogOptions(httpLogOptions)
        ...
        .buildClient();

Bu kod, üst bilgilerle HTTP günlüklerini etkinleştirir ve Accept-Ranges yanıt üst bilgisini ve label sorgu parametresini ilgili izin verilenler listelerine ekler. Bu değişiklik sonrasında, bu değerler üretilen günlüklerde görünür.

Yapılandırma seçeneklerinin tam listesi için HttpLogOptions belgelerine bakın.

Varsayılan günlükçü (geçici hata ayıklama için)

Belirtildiği gibi, tüm Azure istemci kütüphaneleri günlük kaydı için SLF4J kullanır, ancak Java için Azure istemci kütüphanelerinde varsayılan bir günlükleyici olarak başka bir alternatif mevcuttur. Bu varsayılan logger, bir uygulamayı dağıttığınızda günlük kaydı yapmanız gerektiği ancak uygulamayı SLF4J logger’ı eklenmiş olarak yeniden dağıtamadığınız durumlar içindir. Bu günlük kaydediciyi etkinleştirmek için önce hiçbir SLF4J günlük kaydedicisinin bulunmadığından emin olun (çünkü öncelikli olarak o kullanılır) ve ardından AZURE_LOG_LEVEL ortam değişkenini ayarlayın. Aşağıdaki tabloda bu ortam değişkeni için izin verilen değerler gösterilmektedir:

Günlük Düzeyi İzin verilen ortam değişkeni değerleri
AYRINTILI verbose, debug
BİLGİLENDİRİCİ info, information, informational
UYARI warn, warning
HATA err, error

Ortam değişkenini ayarladıktan sonra, ortam değişkenini etkinleştirmek için uygulamayı yeniden başlatın. Bu kayıt tutucu konsola yazar ve bir SLF4J uygulamasının kayıt devri ve dosyaya kayıt gibi gelişmiş özelleştirme imkanlarını sağlamaz. Günlük kaydını devre dışı bırakmak için ortam değişkenini kaldırın ve uygulamayı yeniden başlatın.

SLF4J loglama

Varsayılan olarak, SLF4J tarafından desteklenen bir günlük çerçevesi kullanarak günlüğü yapılandırın. İlk olarak, projenize bağımlılık olarak ilgili bir SLF4J günlük uygulaması ekleyin. Daha fazla bilgi için, SLF4J kullanıcı kılavuzunda proje bağımlılıklarının günlüğe kaydedilmeye yönelik ilanı kısmına bakınız. Ardından günlük düzeylerini ayarlama, hangi sınıfların günlüğe kaydedilip kaydedilmeyeceklerini yapılandırma gibi günlükçünüzü ortamınızda gerektiği gibi çalışacak şekilde yapılandırın. Bu makaledeki bağlantılar aracılığıyla bazı örnekler verilmiştir, ancak daha fazla bilgi için seçtiğiniz günlük çerçevesinin belgelerine bakın.

Günlük biçimi

Günlük çerçeveleri özel günlük iletisi biçimlendirme ve düzenlerini destekler. Azure istemci kitaplıklarında sorun gidermeyi mümkün kılmak için en azından aşağıdaki alanları ekleyin:

  • Milisaniye duyarlıklı tarih ve saat
  • Log seviyesi
  • Günlükçü adı
  • İş parçacığı adı
  • Mesaj

Örnekler için kullandığınız günlükleme çerçevesinin belgelerine bakın.

Yapılandırılmış loglama

Azure istemci kitaplıkları, daha önce bahsedilen yaygın özellikleri günlüğe kaydetmeye ek olarak, uygun olduğunda ek bağlam içeren günlük iletilerine ek açıklama ekler. Örneğin, aşağıdaki örnekte gösterildiği gibi diğer kök özellikler olarak yazılmış bağlamı içeren az.sdk.message JSON biçimli günlükler görebilirsiniz:

16:58:51.038 INFO  c.a.c.c.i.C.getManifestProperties - {"az.sdk.message":"HTTP request","method":"GET","url":"<>","tryCount":"1","contentLength":0}
16:58:51.141 INFO  c.a.c.c.i.C.getManifestProperties - {"az.sdk.message":"HTTP response","contentLength":"558","statusCode":200,"url":"<>","durationMs":102}

Azure İzleyici'ye günlük gönderirken, bunları ayrıştırmak için Kusto sorgu dilini kullanabilirsiniz. Aşağıdaki sorgu bir örnek sağlar:

traces
| where message startswith "{\"az.sdk.message"
| project timestamp, logger=customDimensions["LoggerName"], level=customDimensions["LoggingLevel"], thread=customDimensions["ThreadName"], azSdkContext=parse_json(message)
| evaluate bag_unpack(azSdkContext)

Uyarı

Azure istemci kitaplığı günlükleri geçici hata ayıklamaya yöneliktir. Uygulamanızı uyarmak veya izlemek için günlük biçimine güvenmeyin. Azure istemci kitaplıkları, günlük iletilerinin veya bağlam anahtarlarının kararlılığını garanti etmez. Bu tür amaçlar için dağıtılmış izlemeyi kullanın. Application Insights Java aracısı, istek ve bağımlılık telemetrisi için kararlılık garantileri sağlar. Daha fazla bilgi için bkz. Java için Azure SDK'da izlemeyi yapılandırma.

Sonraki adımlar

Java için Azure SDK'da günlüğün nasıl çalıştığını öğrendiğinize göre, aşağıdaki makaleleri gözden geçirmeyi göz önünde bulundurun. Bu makaleler, SLF4J ve Java istemci kitaplıklarıyla çalışmak için daha popüler Java günlük çerçevelerinden bazılarını yapılandırma konusunda rehberlik sağlar:

  • Last updated on