Mengonfigurasi pengelogan di Azure SDK untuk Java

Artikel ini memberikan gambaran umum tentang cara mengaktifkan pengelogan dalam aplikasi yang menggunakan Azure SDK untuk Java. Pustaka klien Azure untuk Java menawarkan dua opsi pengelogan:

• Kerangka kerja pencatatan bawaan untuk tujuan debugging sementara.
• Dukungan untuk pengelogan dengan menggunakan antarmuka SLF4J .

Gunakan SLF4J karena terkenal dalam ekosistem Java dan didokumenkan dengan baik. Untuk informasi selengkapnya, lihat manual pengguna SLF4J.

Artikel ini menautkan ke artikel lain yang mencakup banyak kerangka kerja pengelogan Java populer. Artikel lain ini menyediakan contoh konfigurasi dan menjelaskan bagaimana pustaka klien Azure dapat menggunakan kerangka kerja pengelogan.

Apa pun konfigurasi pengelogan yang Anda gunakan, Anda akan mendapatkan keluaran log yang sama karena semua keluaran log di pustaka klien Azure untuk Java dirutekan melalui abstraksi azure-core ClientLogger.

Sisa artikel ini merinci konfigurasi semua opsi pengelogan yang tersedia.

Mengaktifkan pengelogan permintaan dan respons HTTP

Pengelogan permintaan dan respons HTTP nonaktif secara default. Anda dapat mengonfigurasi klien yang berkomunikasi dengan layanan Azure melalui HTTP untuk menulis catatan log untuk setiap permintaan dan respons (atau pengecualian) yang mereka terima.

Jika Anda menggunakan OpenTelemetry, pertimbangkan untuk menggunakan pelacakan terdistribusi alih-alih pengelogan untuk permintaan HTTP. Untuk informasi selengkapnya, lihat Mengonfigurasi pelacakan di Azure SDK untuk Java.

Mengonfigurasi pengelogan HTTP dengan variabel lingkungan

AZURE_HTTP_LOG_DETAIL_LEVEL Gunakan variabel lingkungan untuk mengaktifkan log HTTP untuk semua klien. Atur variabel ini ke salah satu nilai berikut:

• NONE: Log HTTP dinonaktifkan. Nilai ini adalah default.
• BASIC: Log HTTP mencakup metode permintaan, URL permintaan yang disanitasi, jumlah percobaan, kode respons, dan panjang konten untuk badan permintaan dan respons.
• HEADERS: Log HTTP menyertakan semua detail dasar dan juga menyertakan header yang diketahui aman untuk tujuan pengelogan - yaitu, mereka tidak berisi rahasia atau informasi sensitif. Daftar lengkap nama header tersedia di kelas HttpLogOptions .
• BODY_AND_HEADERS: Log HTTP mencakup semua detail yang disediakan oleh level HEADERS dan juga menyertakan badan permintaan dan respons selama ukurannya lebih kecil atau sama dengan 16 KB dan dapat dicetak.

Misalnya, URL tanda tangan akses bersama (SAS) Azure Blob Storage dicatat dalam format berikut: 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

Mengonfigurasi pengelogan HTTP dalam kode

Penyusun klien Azure yang mengimplementasikan antarmuka HttpTrait<T> mendukung konfigurasi pengelogan HTTP berbasis kode. Konfigurasi berbasis kode berlaku untuk instans klien individual dan menyediakan lebih banyak opsi dan penyesuaian dibandingkan dengan konfigurasi variabel lingkungan.

Untuk mengonfigurasi log, teruskan instans HttpLogOptions ke httpLogOptions metode pada penyusun klien yang sesuai. Kode berikut menunjukkan contoh untuk layanan App Configuration:

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

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

Kode ini memungkinkan log HTTP dengan header dan menambahkan Accept-Ranges header respons dan label parameter kueri ke daftar izin yang sesuai. Setelah perubahan ini, nilai-nilai ini muncul di log yang diproduksi.

Untuk daftar lengkap opsi konfigurasi, lihat dokumentasi HttpLogOptions .

Logger default (untuk debugging sementara)

Seperti yang disebutkan, semua pustaka klien Azure menggunakan SLF4J untuk pencatatan, tetapi ada logger bawaan sebagai cadangan yang disertakan dalam pustaka klien Azure untuk Java. Logger bawaan ini digunakan saat Anda men-deploy aplikasi dan memerlukan logging, tetapi tidak dapat men-deploy ulang aplikasi yang menyertakan logger SLF4J. Untuk mengaktifkan pencatat ini, pertama-tama pastikan bahwa tidak ada pencatat SLF4J (karena lebih diutamakan), lalu atur AZURE_LOG_LEVEL variabel lingkungan. Tabel berikut ini memperlihatkan nilai yang diizinkan untuk variabel lingkungan ini:

Setelah Anda mengatur variabel lingkungan, hidupkan ulang aplikasi untuk mengaktifkan variabel lingkungan. Pencatat ini mencatat ke konsol, dan tidak menyediakan kemampuan kustomisasi tingkat lanjut dari implementasi SLF4J, seperti rollover dan pengelogan ke file. Untuk menonaktifkan pengelogan, hapus variabel lingkungan dan mulai ulang aplikasi.

Pengelogan SLF4J

Secara default, konfigurasikan pengelogan dengan menggunakan kerangka kerja pengelogan yang didukung SLF4J. Pertama, sertakan implementasi pengelogan SLF4J yang relevan sebagai dependensi dari proyek Anda. Untuk informasi selengkapnya, lihat Mendeklarasikan dependensi proyek untuk pengelogan di manual pengguna SLF4J. Selanjutnya, konfigurasikan pencatat Anda agar berfungsi seperlunya di lingkungan Anda, seperti mengatur tingkat log, mengonfigurasi kelas mana yang melakukan dan tidak mencatat, dan sebagainya. Beberapa contoh disediakan melalui tautan dalam artikel ini, tetapi untuk informasi selengkapnya, lihat dokumentasi untuk kerangka kerja pengelogan yang Anda pilih.

Format Log

Kerangka kerja pengelogan mendukung pemformatan dan tata letak pesan log kustom. Sertakan setidaknya bidang-bidang berikut agar pemecahan masalah pustaka klien Azure dapat dilakukan:

• Tanggal dan waktu dengan presisi milidetik
• Tingkat keparahan dari log
• Nama pencatat
• Nama alur
• Pesan

Misalnya, lihat dokumentasi untuk kerangka kerja pengelogan yang Anda gunakan.

Pengelogan terstruktur

Selain mencatat properti umum yang disebutkan sebelumnya, klien Azure membuat anotasi pesan log dengan konteks tambahan jika berlaku. Misalnya, Anda mungkin melihat log yang diformat dalam JSON yang berisi az.sdk.message dengan konteks ditulis sebagai properti akar lainnya, seperti yang ditunjukkan dalam contoh berikut:

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}

Saat mengirim log ke Azure Monitor, Anda bisa menggunakan bahasa kueri Kusto untuk mengurainya. Kueri berikut ini menyediakan contoh:

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)

Langkah berikutnya

Sekarang setelah Anda mengetahui cara kerja pengelogan di Azure SDK untuk Java, pertimbangkan untuk meninjau artikel berikut. Artikel ini memberikan panduan tentang cara mengonfigurasi beberapa kerangka kerja pengelogan Java yang lebih populer untuk bekerja dengan SLF4J dan pustaka klien Java:

• java.util.logging
• Logback
• Log4J
• Pelacakan