Konfigurasi pengelogan di Azure SDK for Java

  • Artikel

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

  • Kerangka kerja pengelogan bawaan untuk tujuan penelusuran kesalahan sementara.
  • Dukungan untuk pengelogan menggunakan antarmuka SLF4J.

Kami menyarankan Anda menggunakan SLF4J karena terkenal di ekosistem Java dan terdokumentasikan dengan baik. Untuk informasi selengkapnya, lihat manual pengguna SLF4J.

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

Konfigurasi pencatatan apa pun yang Anda gunakan, output log yang sama tersedia dalam kasus mana pun karena semua output pengelogan di pustaka klien Azure untuk Java dirutekan melalui abstraksi ClientLogger inti azure.

Sisa artikel ini memerinci konfigurasi semua opsi pengelogan yang tersedia.

Mengaktifkan pengelogan permintaan/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

Anda dapat menggunakan AZURE_HTTP_LOG_DETAIL_LEVEL variabel lingkungan untuk mengaktifkan log HTTP secara global. Variabel ini mendukung nilai berikut:

  • NONE: Log HTTP dinonaktifkan. Ini adalah nilai default.
  • BASIC: Log HTTP berisi 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 HEADERS tingkat dan juga menyertakan badan permintaan dan respons selama lebih kecil dari 16 KB dan dapat dicetak.

Catatan

URL permintaan dibersihkan - yaitu, semua nilai parameter kueri diredaksi kecuali untuk nilainya api-version . Pustaka klien individual dapat menambahkan parameter kueri lain yang diketahui aman ke daftar yang diizinkan.

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

Peringatan

Badan permintaan pengelogan dan respons tidak disarankan dalam produksi karena mungkin berisi informasi sensitif, secara signifikan memengaruhi performa, mengubah bagaimana konten di-buffer, dan memiliki efek samping lainnya.

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 akan muncul di log yang diproduksi.

Untuk daftar lengkap opsi konfigurasi, lihat dokumentasi HttpLogOptions .

Pencatat default (untuk penelusuran kesalahan sementara)

Seperti yang disebutkan, semua pustaka klien Azure menggunakan SLF4J untuk pengelogan, tetapi ada fallback, pencatat default yang dibangun ke dalam pustaka klien Azure untuk Java. Pencatat default ini disediakan untuk kasus di mana aplikasi disebarkan, dan pengelogan diperlukan, tetapi tidak mungkin untuk menyebarkan ulang aplikasi dengan pencatat SLF4J disertakan. Untuk mengaktifkan pencatat ini, Anda harus terlebih dahulu yakin bahwa tidak ada pencatat SLF4J (karena lebih diutamakan), lalu mengatur AZURE_LOG_LEVEL variabel lingkungan. Tabel berikut menunjukkan nilai yang diizinkan untuk variabel lingkungan ini:

Tingkat log Nilai variabel lingkungan yang diizinkan
VERBOSE verbose, debug
INFORMATIF info, , informationinformational
PERINGATAN warn, warning
KESALAHAN err, error

Setelah variabel lingkungan diatur, mulai ulang aplikasi untuk memungkinkan variabel lingkungan untuk berjalan. Pencatat ini mencatat ke konsol, dan tidak menyediakan kemampuan kustomisasi tingkat lanjut dari implementasi SLF4J, seperti rollover dan pengelogan ke file. Untuk mematikan pengelogan lagi, cukup hapus variabel lingkungan dan mulai ulang aplikasi.

Pengelogan SLF4J

Secara default, Anda harus mengonfigurasi pengelogan menggunakan kerangka 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. Sebaiknya sertakan setidaknya bidang berikut untuk memungkinkan pemecahan masalah pustaka klien Azure:

  • Tanggal dan waktu dengan presisi milidetik
  • Tingkat keparahan 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 berformat JSON yang berisi az.sdk.message konteks yang 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)

Catatan

Log pustaka klien Azure ditujukan untuk penelusuran kesalahan ad-hoc. Sebaiknya jangan mengandalkan format log untuk memperingatkan atau memantau aplikasi Anda. Pustaka klien Azure tidak menjamin stabilitas pesan log atau kunci konteks. Untuk tujuan tersebut, sebaiknya gunakan pelacakan terdistribusi. Agen Application Insights Java memberikan jaminan stabilitas untuk telemetri permintaan dan dependensi. Untuk informasi selengkapnya, lihat Mengonfigurasi pelacakan di Azure SDK untuk Java.

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: