Aracılığıyla paylaş

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

  • Makale

Bu makalede, Java için Azure SDK'sını kullanan uygulamalarda günlüğe kaydetmeyi etkinleştirmeye yönelik genel bir bakış sağlanır. Java için Azure istemci kitaplıklarının iki günlük seçeneği vardır:

Java ekosisteminde iyi bilinen ve iyi belgelenmiş olduğundan SLF4J kullanmanızı öneririz. Daha fazla bilgi için bkz. SLF4J kullanıcı kılavuzu.

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.

Kullandığınız günlük yapılandırması ne olursa olsun, Her iki durumda da aynı günlük çıkışı kullanılabilir çünkü Java için Azure istemci kitaplıklarındaki tüm günlük çıkışı bir azure-core ClientLogger soyutlaması üzerinden yönlendirilir.

Bu makalenin geri kalanında tüm kullanılabilir günlük seçeneklerinin yapılandırması ayrıntılı olarak açıklanabilir.

HTTP isteği/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üğe kaydetmek yerine dağıtılmış izleme kullanmayı göz önünde bulundurun. 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

HTTP günlüklerini genel olarak etkinleştirmek için ortam değişkenini kullanabilirsiniz AZURE_HTTP_LOG_DETAIL_LEVEL . Bu değişken aşağıdaki değerleri destekler:

  • NONE: HTTP günlükleri devre dışı bırakıldı. Bu değer varsayılandır.
  • 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.

Not

İstek URL'si temizlenir; diğer bir ifadeyle, değer dışındaki api-version tüm sorgu parametresi değerleri yeniden işlemden çıkarılır. Tek tek istemci kitaplıkları, izin verilenler listesine güvenli olduğu bilinen başka sorgu parametreleri 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ı

Hassas bilgiler içerebileceği, performansı önemli ölçüde etkileyebileceği, içeriğin arabelleğe alınıp alınmadığı ve başka yan etkileri olabileceği için üretim ortamında günlüğe kaydetme isteği ve yanıt gövdeleri önerilmez.

Kodda HTTP günlüğünü yapılandırma

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, httplogoptionshttpLogOptions örneğini ilgili istemci oluşturucusunun yöntemine geçirin. Aşağıdaki kodda Uygulama Yapılandırması hizmeti için bir örnek gösterilmektedir:

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 yanıt üst bilgisini ve label sorgu parametresini ilgili izin verilenler listesine eklerAccept-Ranges. Bu değişiklik sonrasında, bu değerler üretilen günlüklerde görünmelidir.

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 kitaplıkları günlük kaydı için SLF4J kullanır, ancak Java için Azure istemci kitaplıklarına yerleşik olarak bir geri dönüş, varsayılan günlükçü vardır. Bu varsayılan günlükçü, bir uygulamanın dağıtıldığı ve günlüğe kaydetmenin gerekli olduğu durumlar için sağlanır, ancak uygulamayı bir SLF4J günlükçü ile yeniden dağıtmak mümkün değildir. Bu günlükçü'leri etkinleştirmek için önce SLF4J günlükçüsü olmadığından emin olmanız (öncelik aldığı için) ve ardından ortam değişkenini AZURE_LOG_LEVEL ayarlamanız gerekir. 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şkeni ayarlandıktan sonra, ortam değişkeninin etkili olmasını sağlamak için uygulamayı yeniden başlatın. Bu günlükçü konsolda oturum açar ve bir SLF4J uygulamasının rollover ve dosyaya günlük kaydı gibi gelişmiş özelleştirme özelliklerini sağlamaz. Günlüğü yeniden kapatmak için ortam değişkenini kaldırın ve uygulamayı yeniden başlatın.

SLF4J günlüğü

Varsayılan olarak, SLF4J tarafından desteklenen bir günlük çerçevesi kullanarak günlüğü yapılandırmanız gerekir. İlk olarak, projenizden bağımlılık olarak ilgili bir SLF4J günlük uygulaması ekleyin. Daha fazla bilgi için bkz . SLF4J kullanıcı kılavuzunda günlüğe kaydetme için proje bağımlılıklarını bildirme. 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ı eklemenizi öneririz:

  • Milisaniye duyarlıklı tarih ve saat
  • Günlük önem derecesi
  • Günlükçü adı
  • İş parçacığı adı
  • İleti

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

Yapılandırılmış günlüğe kaydetme

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)

Not

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üvenmenizi önermeyiz. Azure istemci kitaplıkları günlük iletilerinin veya bağlam anahtarlarının kararlılığını garanti vermez. Bu tür amaçlar için dağıtılmış izleme kullanmanızı öneririz. Application Analizler 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: