Konfigurasi pengelogan di Azure SDK for Java

Artikel
05/30/2023

Artikel ini memberikan gambaran umum tentang cara mengonfigurasi Azure SDK for Java untuk mengintegrasikan fungsi pelacakan.

Anda dapat mengaktifkan penelusuran di pustaka klien Azure dengan menggunakan dan mengonfigurasi SDK OpenTelemetry atau 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.

Ada dua konsep kunci yang terkait dengan pelacakan: rentang dan jejak. Rentang mewakili satu operasi dalam jejak. Rentang dapat mewakili permintaan HTTP, panggilan prosedur jarak jauh (RPC), kueri database, atau bahkan jalur yang diambil kode Anda. Jejak adalah pohon bentang yang menunjukkan jalur kerja melalui sistem. Anda dapat membedakan jejak itu sendiri dengan urutan 16 byte unik yang disebut TraceID. Untuk informasi selengkapnya tentang konsep ini dan bagaimana kaitannya dengan OpenTelemetry, lihat dokumentasi OpenTelemetry.

Pelacakan Azure SDK dengan agen Azure Monitor Java

Dengan menggunakan agen in-proses Azure Monitor Java, Anda dapat mengaktifkan pemantauan aplikasi Anda tanpa perubahan kode apa pun. Untuk informasi lebih lanjut, lihat Instrumentasi otomatis berbasis OpenTelemetry Azure Monitor untuk aplikasi Java. Dukungan Azure SDK diaktifkan secara bawaan dimulai dengan agen versi 3.2.

Melacak panggilan Azure SDK dengan agen OpenTelemetry

Jika Anda menggunakan agen OpenTelemetry Java, instrumentasi Azure SDK diaktifkan secara langsung mulai dari versi 1.12.0.

Untuk detail selengkapnya tentang cara mengonfigurasi eksportir, menambahkan instrumentasi manual, atau memperkaya telemetri, lihat Instrumentasi OpenTelemetry untuk Java.

Catatan

Artefak agen OpenTelemetry stabil, tetapi tidak memberikan jaminan stabilitas telemetri over-the-wire, yang dapat menyebabkan nama rentang dan nama atribut yang diproduksi oleh Azure SDK yang mungkin berubah dari waktu ke waktu jika Anda memperbarui agen. Untuk informasi selengkapnya, lihat Persyaratan kompatibilitas.

Instrumen aplikasi secara manual dengan OpenTelemetry SDK (pratinjau)

Jika Anda menggunakan OpenTelemetry SDK secara langsung, pastikan untuk mengonfigurasi SDK dan eksportir untuk backend pilihan Anda. Untuk informasi selengkapnya, lihat dokumentasi OpenTelemetry.

Untuk mengaktifkan pelacakan Azure SDK, tambahkan paket com.azure:azure-core-tracing-opentelemetry terbaru ke aplikasi Anda. Misalnya, di Maven, tambahkan entri berikut ke file pom.xml Anda:

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-core-tracing-opentelemetry</artifactId>
</dependency>

Jika Anda menjalankan aplikasi sekarang, Anda akan mendapatkan rentang Azure SDK di backend Anda. Namun dengan panggilan tidak sinkron, korelasi antara Azure SDK dan rentang aplikasi dapat rusak.

Secara bawaan, Azure SDK menggunakan io.opentelemetry.context.Context.current(), yang secara implisit disebarkan oleh OpenTelemetry, sebagai induk dari rentang baru. Dalam panggilan tidak sinkron, penyebaran konteks implisit rusak. Agen OpenTelemetry memecahkan masalah ini dengan membantu menyebarkan konteks, tetapi OpenTelemetry SDK tidak memiliki kemampuan seperti itu.

Meneruskan konteks jejak secara eksplisit

Azure SDK memungkinkan meneruskan konteks jejak eksplisit secara com.azure.core.util.Context di bawah trace-context kunci. Saat Anda memberikan konteks jejak eksplisit, Azure SDK menggunakannya alih-alih yang implisit, yang memungkinkan korelasi antara aplikasi dan rentang Azure SDK.

Dalam contoh berikut, ketika permintaan web masuk dilacak secara manual, Pustaka Klien Konfigurasi Aplikasi dipanggil secara tidak sinkron dalam cakupan permintaan ini.

Span span = TRACER.spanBuilder("incoming request").startSpan();
io.opentelemetry.context.Context traceContext = io.opentelemetry.context.Context.root().with(span);

// Put the incoming-request span (wrapped into the OpenTelemetry Context) into the Azure SDK Context
// and pass it over to the Application Configuration call.
appConfigClient.setConfigurationSettingWithResponse(settings, true, new com.azure.core.util.Context("trace-context", traceContext));

// You could also pass the context using the reactor `contextWrite` method under the same `trace-context` key.
appConfigAsyncClient.setConfigurationSettingWithResponse(settings)
   .contextWrite(reactor.util.context.Context.of("trace-context", traceContext))

//...

Konvensi pelacakan Azure SDK

Untuk mengetahui rentang dan atribut mana yang dipancarkan SDK, lihat spesifikasi konvensi semantik Azure SDK. Konvensi semantik Azure SDK (dan OpenTelemetry) tidak stabil dan dapat berubah di masa mendatang.

Langkah berikutnya

Sekarang setelah Anda terbiasa dengan fungsionalitas lintas sektoral inti di Azure SDK for Java, lihat autentikasi Azure dengan Java dan Azure Identity untuk mempelajari cara membuat aplikasi yang aman.

Bagikan melalui