Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
Artikel ini memberikan gambaran umum tentang cara mengaktifkan pengelogan dalam aplikasi yang menggunakan Azure SDK untuk Java. Pustaka klien Azure untuk Java memiliki dua opsi pengelogan:
- Kerangka kerja pencatatan bawaan untuk tujuan debugging sementara.
- Dukungan untuk pengelogan menggunakan antarmuka SLF4J.
Kami menyarankan agar Anda menggunakan SLF4J karena terkenal di 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, output log yang sama tersedia dalam kedua kasus karena semua output pengelogan 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/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. Nilai ini adalah 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 levelHEADERSdan juga menyertakan badan permintaan dan respons selama ukurannya lebih kecil atau sama dengan 16 KB dan dapat dicetak.
Nota
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
Mencatat badan permintaan dan respons tidak disarankan dalam lingkungan produksi karena mungkin berisi informasi sensitif, secara signifikan memengaruhi performa, mengubah cara 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 .
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. Pencatat log bawaan ini disediakan untuk kasus di mana aplikasi disebarkan, dan pencatatan log diperlukan, tetapi tidak mungkin untuk menyebarkan ulang aplikasi dengan pencatat SLF4J yang 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 ini memperlihatkan nilai yang diizinkan untuk variabel lingkungan ini:
| Tingkat log | Nilai variabel lingkungan yang diizinkan |
|---|---|
| PENYEDEHANAAN KATA |
verbose, debug |
| INFORMATIF |
info, , informationinformational |
| PERINGATAN |
warn, warning |
| KESALAHAN |
err, error |
Setelah variabel lingkungan diatur, hidupkan ulang aplikasi untuk mengaktifkan variabel lingkungan agar berlaku. Pencatat ini mencatat ke konsol, dan tidak menyediakan kemampuan kustomisasi tingkat lanjut dari implementasi SLF4J, seperti rollover dan pengelogan ke file. Untuk menonaktifkan pengelogan lagi, cukup hapus variabel lingkungan dan mulai ulang aplikasi.
Pengelogan SLF4J
Secara default, Anda harus mengonfigurasi pengelogan 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. Sebaiknya sertakan setidaknya bidang berikut untuk memungkinkan pemecahan masalah pustaka klien Azure:
- 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)
Nota
Log pustaka klien Azure dimaksudkan untuk debugging 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 Java Application Insights menyediakan jaminan stabilitas untuk telemetri permintaan dan ketergantungan. 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: