Agen Application Real-Time Monitoring Service (ARMS) secara otomatis menginstrumentasi framework Java umum untuk mengumpulkan data jejak tanpa perubahan kode. Untuk menangkap data jejak yang mencerminkan logika bisnis spesifik Anda, tambahkan instrumentasi kustom menggunakan SDK OpenTelemetry untuk Java. Topik ini menjelaskan cara menggunakan SDK OpenTelemetry untuk Java guna menambahkan instrumentasi kustom, mengakses konteks jejak, menentukan Baggage kustom, dan mengatur atribut kustom.
Untuk informasi mengenai komponen dan framework yang didukung oleh agen ARMS, lihat Komponen dan Framework Java yang Didukung ARMS.
Prasyarat
-
Aplikasi Anda telah terhubung ke Application Real-Time Monitoring Service (ARMS). Untuk informasi selengkapnya, lihat Ikhtisar integrasi Pemantauan Aplikasi.
-
Versi agen ARMS Anda adalah 2.9.1.2 atau lebih baru. Untuk melakukan upgrade agen, lihat Upgrade agen ARMS.
Tambahkan dependensi
Tambahkan dependensi Maven berikut ke proyek Anda. Untuk informasi selengkapnya, lihat dokumentasi resmi OpenTelemetry.
<dependencies>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-api</artifactId>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-sdk-trace</artifactId>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-sdk</artifactId>
</dependency>
</dependencies>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-bom</artifactId>
<version>1.23.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
Kompatibilitas agen ARMS dengan instrumentasi OpenTelemetry
Konsep utama
Bagian ini hanya menjelaskan istilah umum. Untuk informasi selengkapnya tentang istilah lainnya, lihat Spesifikasi OpenTelemetry.
-
span: operasi spesifik dalam sebuah permintaan, seperti titik masuk panggilan remote atau pemanggilan metode internal.
-
SpanContext: konteks dari suatu jejak, termasuk informasi seperti trace ID dan span ID.
-
attribute: bidang tambahan pada span yang mencatat informasi penting.
-
Baggage: pasangan kunci-nilai yang dipropagasikan sepanjang keseluruhan jejak.
Gunakan SDK OpenTelemetry untuk Java
Anda dapat menggunakan SDK OpenTelemetry untuk melakukan operasi berikut:
-
Menambahkan instrumentasi untuk menghasilkan span.
-
Menambahkan atribut ke span.
-
Mempropagasikan Baggage dalam konteks jejak.
-
Mendapatkan konteks jejak saat ini dan mencetak informasi seperti trace ID dan span ID.
Kode contoh berikut menunjukkan cara menggunakan SDK OpenTelemetry untuk melakukan operasi tersebut.
Penting: Anda harus mendapatkan instans OpenTelemetry dengan memanggil GlobalOpenTelemetry.get(). Jangan gunakan instans yang Anda buat secara manual dengan SDK OpenTelemetry. Jika tidak, pada agen ARMS v4.x, span yang dihasilkan oleh instrumentasi SDK tidak akan terlihat.
@RestController
@RequestMapping("/ot")
public class OpenTelemetryController {
private Tracer tracer;
private ScheduledExecutorService ses = Executors.newSingleThreadScheduledExecutor();
@PostConstruct
public void init() {
OpenTelemetrySdk.builder()
.setPropagators(ContextPropagators.create(W3CTraceContextPropagator.getInstance()))
.buildAndRegisterGlobal();
tracer = GlobalOpenTelemetry.get().getTracer("manual-sdk", "1.0.0");
ses.scheduleAtFixedRate(new Runnable() {
@Override
public void run() {
Span span = tracer.spanBuilder("schedule")
.setAttribute("schedule.time", System.currentTimeMillis())
.startSpan();
try (Scope scope = span.makeCurrent()) {
System.out.println("scheduled!");
Thread.sleep(500L);
span.setAttribute("schedule.success", true);
System.out.println(Span.current().getSpanContext().getTraceId()); // Dapatkan trace ID
} catch (Throwable t) {
span.setStatus(StatusCode.ERROR, t.getMessage());
} finally {
span.end();
}
}
}, 10, 30, TimeUnit.SECONDS);
}
@ResponseBody
@RequestMapping("/parent")
public String parent() {
Span span = tracer.spanBuilder("parent").setSpanKind(SpanKind.SERVER).startSpan();
try (Scope scope = span.makeCurrent()) {
// Gunakan Baggage untuk mempropagasikan tag bisnis kustom.
Baggage baggage = Baggage.current().toBuilder()
.put("user.id", "1")
.put("user.name", "name")
.build();
try (Scope baggageScope = baggage.storeInContext(Context.current()).makeCurrent()) {
child();
}
span.setAttribute("http.method", "GET");
span.setAttribute("http.uri", "/parent");
} finally {
span.end();
}
return "parent";
}
private void child() {
Span span = tracer.spanBuilder("child").startSpan();
try (Scope scope = span.makeCurrent()) {
System.out.println("current traceId = " + Span.current().getSpanContext().getTraceId());
System.out.println("userId in baggage = " + Baggage.current().getEntryValue("user.id"));
Thread.sleep(1000);
} catch (Throwable e) {
span.setStatus(StatusCode.ERROR, e.getMessage());
} finally {
span.end();
}
}
}
Penjelasan contoh:
-
Pada metode
initdiOpenTelemetryController, sebuah Tugas terjadwal dimulai. Sebuah span dibuat di awal setiap eksekusi dan diakhiri saat selesai. -
Pada metode
parentdiOpenTelemetryController, beberapa metode SDK OpenTelemetry dipanggil.-
Setiap kali metode dipanggil, sebuah span bernama
parentdibuat dan diakhiri saat metode selesai. -
SDK Baggage digunakan untuk menambahkan dua item Baggage:
user.iddanuser.name. Item-item ini dipropagasikan ke aplikasi downstream. -
Dua atribut ditambahkan ke span yang dibuat pada langkah 2.a.
-
-
Metode
childdiOpenTelemetryControllermelakukan operasi berikut:
Perbedaan antar versi agen ARMS
Dukungan terhadap operasi dalam kode sebelumnya berbeda antara versi agen ARMS.
|
Langkah |
Agen ARMS v4.x dan lebih baru |
Agen ARMS v3.x dan versi sebelumnya |
|
1 |
Didukung. Span baru dihasilkan. |
Didukung. Span baru dihasilkan. |
|
2.a |
Didukung |
Didukung |
|
2.b |
Didukung |
Tidak didukung |
|
2.c |
Didukung |
Didukung |
|
3.a |
Didukung |
Didukung. Span ini muncul sebagai stack metode di dalam span yang dibuat pada langkah 2.a. |
|
3.b |
Didukung. Trace ID yang dicetak sama dengan trace ID di ARMS. |
Tidak didukung. Trace ID yang dicetak berbeda dari trace ID di agen ARMS. |
|
3.c |
Didukung |
Didukung |
Hasil instrumentasi
v4.x dan lebih baru
-
Hasil instrumentasi Langkah 1:
Anda dapat melihat span yang dihasilkan oleh SDK OpenTelemetry.
Pada Detail Span suatu jejak di Konsol ARMS, Anda dapat melihat informasi dasar, seperti nama aplikasi (misalnya,
elastic-search-8), nama operasi (misalnya,schedule), jenis span (INTERNAL), dan Durasi. Pada tab Attributes, Anda dapat melihat atribut OpenTelemetry, sepertiotel.scope.name=manual-sdkdanotel.scope.version=1.0.0, serta atribut bisnis kustom, sepertischedule.success=true, yang mengonfirmasi bahwa instrumentasi berfungsi. -
Hasil instrumentasi Langkah 2.x dan Langkah 3.x:
Span yang dihasilkan oleh SDK OpenTelemetry muncul dalam jejak yang sama dengan span Tomcat yang dihasilkan oleh agen. Selain itu, atribut terkait untuk span yang dihasilkan SDK diatur sesuai harapan.
Pada detail jejak, nama operasi span yang dihasilkan oleh instrumentasi agen Tomcat adalah
/opentelemetry/parent. Span yang dihasilkan oleh SDK OpenTelemetry diberi namaparentdan span anaknyachild. Pada atribut span,http.methodadalahGET,http.uriadalah/parent, dan atribut kustomotel.scope.nameadalahmanual-sdk.
v3.x dan lebih lama
-
Hasil instrumentasi Langkah 1:
Pada halaman detail jejak di Konsol ARMS, Anda dapat melihat data jejak yang dikumpulkan oleh instrumentasi. Grafik air terjun di sebelah kiri menunjukkan hubungan pemanggilan span. Misalnya, metode
scheduledari aplikasielastic-search-9ditangkap sebagai span dengan tipe komponenuser_methoddan total waktu respons 567 ms. Panel Span Details di sebelah kanan menampilkan informasi dasar seperti nama aplikasi, nama span, alamat IP, span ID, dan status code. Bagian Attributes di bawahnya menampilkan atribut tambahan dalam kelompok, termasuk Informasi HTTP (http.path,http.status_code), Informasi RPC (rpc.type), dan Informasi Bawaan (component.name=user_method,slow=1). -
Hasil instrumentasi Langkah 2.x dan Langkah 3.x:
Span
childditampilkan di dalam stack metode spanparent. Selain itu, atribut untuk span yang dihasilkan SDK diatur sesuai harapan.Pada tampilan method stack, hierarki jejak menunjukkan OpenTelemetry Entry Span memanggil span parent, yang kemudian memanggil span child. Ketiga pemanggilan bersarang ini masing-masing memakan waktu sekitar 1,01 detik. Atribut metode child mencakup
line=-1danrpc.type=98.
Dokumen terkait
Mengkorelasikan informasi trace ID dengan log bisnis aplikasi Anda memungkinkan Anda dengan cepat menemukan log terkait untuk troubleshooting saat terjadi masalah. Untuk informasi selengkapnya, lihat Kaitkan trace ID dengan log bisnis untuk aplikasi Java.