All Products
Search
Document Center

Application Real-Time Monitoring Service:Tambahkan instrumentasi kustom dengan OpenTelemetry untuk Java

Last Updated:Jun 22, 2026

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

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

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:

  1. Pada metode init di OpenTelemetryController, sebuah Tugas terjadwal dimulai. Sebuah span dibuat di awal setiap eksekusi dan diakhiri saat selesai.

  2. Pada metode parent di OpenTelemetryController, beberapa metode SDK OpenTelemetry dipanggil.

    1. Setiap kali metode dipanggil, sebuah span bernama parent dibuat dan diakhiri saat metode selesai.

    2. SDK Baggage digunakan untuk menambahkan dua item Baggage: user.id dan user.name. Item-item ini dipropagasikan ke aplikasi downstream.

    3. Dua atribut ditambahkan ke span yang dibuat pada langkah 2.a.

  3. Metode child di OpenTelemetryController melakukan operasi berikut:

    1. Setiap kali metode dipanggil, sebuah span bernama child dibuat dan diakhiri saat metode selesai. Span ini merupakan anak dari span yang dibuat pada langkah 2.a.

    2. Trace ID diambil dari konteks jejak dan dicetak.

    3. Baggage yang ditambahkan pada langkah 2.b diambil dan nilainya dicetak.

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, seperti otel.scope.name=manual-sdk dan otel.scope.version=1.0.0, serta atribut bisnis kustom, seperti schedule.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 nama parent dan span anaknya child. Pada atribut span, http.method adalah GET, http.uri adalah /parent, dan atribut kustom otel.scope.name adalah manual-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 schedule dari aplikasi elastic-search-9 ditangkap sebagai span dengan tipe komponen user_method dan 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 child ditampilkan di dalam stack metode span parent. 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=-1 dan rpc.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.