Gambaran umum pemecahan masalah untuk Azure SDK untuk Java

Artikel ini memperkenalkan banyak alat pemecahan masalah yang tersedia saat Anda menggunakan Azure SDK untuk Java, dan tautan ke artikel lain dengan detail lebih lanjut.

Azure SDK untuk Java terdiri dari banyak pustaka klien - satu atau beberapa untuk setiap layanan Azure yang ada. Microsoft memastikan bahwa semua pustaka klien dibangun ke standar yang konsisten dan tinggi, dengan pola umum untuk konfigurasi, pengelogan, penanganan pengecualian, dan pemecahan masalah. Untuk informasi selengkapnya, lihat Menggunakan Azure SDK untuk Java.

Karena pemecahan masalah dapat mencakup area subjek yang begitu luas, Microsoft mengembangkan panduan pemecahan masalah berikut yang mungkin ingin Anda tinjau:

• Memecahkan masalah autentikasi Azure Identity mencakup teknik investigasi kegagalan autentikasi, kesalahan umum untuk jenis kredensial di pustaka klien Azure Identity Java, dan langkah-langkah mitigasi untuk mengatasi kesalahan ini.
• Menyelesaikan masalah konflik versi dependensi mencakup subjek yang terkait dengan mendiagnosis, mitigasi, dan meminimalkan konflik dependensi. Konflik ini dapat muncul saat Anda menggunakan pustaka klien Azure SDK for Java dalam sistem yang dibangun dengan alat seperti Maven dan Gradle.
• Memecahkan masalah jaringan mencakup topik yang berkaitan dengan debugging HTTP di luar pustaka klien, dengan menggunakan alat seperti Fiddler dan Wireshark.

Seiring dengan panduan pemecahan masalah umum ini, Microsoft juga menyediakan panduan pemecahan masalah khusus pustaka. Saat ini, panduan berikut tersedia:

• Memecahkan masalah Azure Event Hubs
• Memecahkan masalah Azure Service Bus

Di luar dokumen-dokumen ini, konten berikut memberikan panduan untuk memanfaatkan pencatatan dan penanganan pengecualian sebaik mungkin yang berkaitan dengan Azure SDK untuk Java.

Menggunakan pengelogan di Azure SDK untuk Java

Bagian berikut menjelaskan cara mengaktifkan berbagai jenis pengelogan.

Aktifkan pengelogan klien

Untuk memecahkan masalah, pertama-tama aktifkan pengelogan untuk memantau perilaku aplikasi Anda. Kesalahan dan peringatan dalam log umumnya memberikan wawasan yang berguna tentang apa yang salah dan terkadang menyertakan tindakan korektif untuk memperbaiki masalah. Azure SDK untuk Java memiliki dukungan pengelogan yang komprehensif. Untuk informasi selengkapnya, lihat Mengonfigurasi pengelogan di Azure SDK untuk Java.

Mengaktifkan pengelogan permintaan/respons HTTP

Saat memecahkan masalah, tinjau permintaan HTTP saat dikirim dan diterima antara layanan Azure. Untuk mengaktifkan pengelogan payload permintaan dan respons HTTP, konfigurasikan hampir semua Azure SDK untuk pustaka klien Java di penyusun klien mereka seperti yang ditunjukkan dalam contoh berikut. Secara khusus, beri perhatian khusus pada metode httpLogOptions di pembangun klien, dan pada nilai enum yang tersedia di HttpLogDetailLevel.

ConfigurationClient configurationClient = new ConfigurationClientBuilder()
        .connectionString(connectionString)
        .httpLogOptions(new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BODY_AND_HEADERS))
        .buildClient();

Kode ini mengubah permintaan HTTP dan pengelogan respons untuk satu instans klien. Atau, Anda dapat mengonfigurasi pengelogan permintaan dan respons HTTP untuk seluruh aplikasi Anda dengan mengatur AZURE_HTTP_LOG_DETAIL_LEVEL variabel lingkungan ke salah satu nilai dalam tabel berikut. Perubahan ini memungkinkan pengelogan untuk setiap klien Azure yang mendukung pengelogan permintaan dan respons HTTP.

Nilai	Tingkat pengelogan
none	Pengelogan permintaan dan respons HTTP dinonaktifkan.
basic	Hanya mencatat URL, metode HTTP, dan waktu untuk menyelesaikan permintaan.
headers	Mencatat semuanya di BASIC, ditambah semua header permintaan dan respons.
body	Mencatat semua yang ada di BASIC, ditambah semua isi permintaan dan respons.
body_and_headers	Mencatat semua yang ada di HEADERS dan BODY.

Nota

Saat Anda mencatat isi permintaan dan respons, pastikan mereka tidak mengandung informasi rahasia. Saat Anda mencatat parameter dan header kueri, pustaka klien memiliki sekumpulan parameter dan header kueri default yang dianggap aman untuk dicatat. Anda bisa menambahkan parameter dan header kueri tambahan yang aman untuk dicatat, seperti yang diperlihatkan dalam contoh berikut:

clientBuilder.httpLogOptions(new HttpLogOptions()
    .addAllowedHeaderName("safe-to-log-header-name")
    .addAllowedQueryParamName("safe-to-log-query-parameter-name"))

Penanganan pengecualian di Azure SDK untuk Java

Sebagian besar Azure SDK untuk metode layanan klien Java melempar HttpResponseException atau subkelas yang lebih spesifik pada kegagalan. Jenis ini HttpResponseException mencakup objek kesalahan respons terperinci yang memberikan wawasan khusus yang berguna tentang apa yang salah dan menyertakan tindakan korektif untuk memperbaiki masalah umum. Anda dapat menemukan informasi kesalahan ini di dalam properti HttpResponseException pesan objek. Karena pengecualian ini adalah pengecualian runtime, dokumentasi referensi JavaDoc tidak secara eksplisit mencantumkannya.

Contoh berikut menunjukkan kepada Anda cara menangkap pengecualian ini dengan klien sinkron:

try {
    ConfigurationSetting setting = new ConfigurationSetting().setKey("myKey").setValue("myValue");
    client.getConfigurationSetting(setting);
} catch (HttpResponseException e) {
    System.out.println(e.getMessage());
    // Do something with the exception
}

Dengan klien asinkron, Anda dapat menangkap dan menangani pengecualian dalam panggilan balik kesalahan, seperti yang ditunjukkan dalam contoh berikut:

ConfigurationSetting setting = new ConfigurationSetting().setKey("myKey").setValue("myValue");
asyncClient.getConfigurationSetting(setting)
    .doOnSuccess(ignored -> System.out.println("Success!"))
    .doOnError(
        error -> error instanceof ResourceNotFoundException,
        error -> System.out.println("Exception: 'getConfigurationSetting' could not be performed."));

Menggunakan pelacakan di Azure SDK untuk Java

Azure SDK for Java menawarkan dukungan pelacakan yang komprehensif, memungkinkan Anda melihat alur eksekusi melalui kode aplikasi dan pustaka klien yang Anda gunakan. Anda dapat mengaktifkan pelacakan di pustaka klien Azure dengan menggunakan dan mengonfigurasi SDK OpenTelemetry atau dengan menggunakan agen yang kompatibel dengan OpenTelemetry. OpenTelemetry adalah kerangka pengamatan sumber terbuka yang populer untuk menghasilkan, menangkap, dan mengumpulkan data telemetri untuk perangkat lunak cloud-native.

Untuk informasi selengkapnya tentang cara mengaktifkan pelacakan di Azure SDK untuk Java, lihat Mengonfigurasi pelacakan di Azure SDK untuk Java.

Langkah selanjutnya

Jika panduan pemecahan masalah dalam artikel ini tidak membantu mengatasi masalah saat Anda menggunakan Azure SDK untuk pustaka klien Java, ajukan masalah di Azure SDK untuk repositori Java GitHub.