Aracılığıyla paylaş

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

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 kayıt tutma seçeneği vardır.

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

Java ekosisteminde iyi bilinen ve iyi belgelenmiş olduğundan SLF4J kullanmanızı öneririz. 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.

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ı, tüm kullanılabilir günlük seçeneklerinin konfigürasyonunu ayrıntılı şekilde açıklamaktadır.

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ü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

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ı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 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ı

Üretim ortamında istek ve yanıt gövdelerinin günlüğe kaydedilmesi önerilmez çünkü hassas bilgiler içerebilir, performansı ciddi şekilde etkileyebilir, içeriğin arabelleğe alınma biçimini değiştirebilir ve başka yan etkiler yaratabilir.

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ü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 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 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 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üğü yeniden kapatmak 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ırmanız gerekir. İ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ı eklemenizi öneririz:

  • 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ü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 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