Instrumentasi otomatis berbasis OpenTelemetry Azure Monitor untuk aplikasi Java

Artikel ini menjelaskan cara mengaktifkan dan mengonfigurasikan penawaran Java Azure Monitor berbasis OpenTelemetry. Setelah Anda menyelesaikan petunjuk dalam artikel ini, Anda akan dapat menggunakan Aplikasi Azure Monitor Insights untuk memantau aplikasi Anda.

Mulai

Instrumentasi otomatis Java dapat diaktifkan tanpa perubahan kode.

Prasyarat

Mengaktifkan Azure Monitor Application Insights

Bagian ini menunjukkan kepada Anda cara mengunduh file jar instrumentasi otomatis.

Unduh file jar

Unduh file applicationinsights-agent-3.2.3.jar.

Peringatan

Jika Anda memutakhirkan dari Pratinjau 3.0:

  • Tinjau semua opsi konfigurasi dengan cermat. Struktur JSON telah benar-benar berubah. Nama file sekarang semua huruf kecil.

Jika Anda memutakhirkan dari 3.0.x:

  • Nama operasi dan nama telemetri permintaan sekarang diawali dengan metode HTTP, seperti GET dan POST . Perubahan ini dapat memengaruhi dasbor atau peringatan kustom jika mengandalkan nilai sebelumnya. Untuk lebih detail, lihat catatan rilis 3.1.0.

Jika Anda memutakhirkan dari 3.1.x:

  • Nama dependensi database sekarang lebih ringkas dengan kueri lengkap (dibersihkan) masih ada di bidang data. Nama dependensi HTTP sekarang lebih deskriptif. Perubahan ini dapat memengaruhi dasbor atau peringatan kustom jika mengandalkan nilai sebelumnya. Untuk lebih detail, lihat catatan rilis 3.2.0.

Arahkan JVM ke file jar

Tambahkan -javaagent:path/to/applicationinsights-agent-3.2.3.jar ke args JVM aplikasi Anda.

Tip

Untuk bantuan dalam mengonfigurasi args JVM aplikasi Anda, lihat Tips untuk memperbarui args JVM Anda.

Mengatur string koneksi Insights Aplikasi

  1. Ada dua cara Anda dapat mengarahkan file jar ke sumber daya aplikasi Insights Anda:

    • Anda dapat mengatur variabel lingkungan:

      APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=...
      
    • Atau Anda dapat membuat file konfigurasi bernama applicationinsights.json . Tempatkan di direktori yang sama applicationinsights-agent-3.2.3.jar seperti dengan konten berikut:

      {
        "connectionString": "InstrumentationKey=..."
      }
      
  2. Temukan string koneksi di sumber daya aplikasi Insights Anda.

    Cuplikan layar yang memperlihatkan string koneksi Insights Aplikasi.

Mengonfirmasi data sedang mengalir

Jalankan aplikasi Anda dan buka tab Aplikasi Insights Resource Anda di portal Azure. Diperlukan beberapa menit agar data muncul di portal.

Catatan

Jika Anda tidak dapat menjalankan aplikasi atau Anda tidak mendapatkan data seperti yang diharapkan, lihat bagian Pemecahan Masalah.

Cuplikan layar yang memperlihatkan tab Gambaran Umum Insights Aplikasi dengan permintaan server dan waktu respons server disorot.

Penting

Jika Anda memiliki dua atau lebih layanan yang memancarkan telemetri ke sumber daya aplikasi Insights yang sama, Anda diminta untuk mengatur nama peran cloud untuk mewakilinya dengan benar di peta aplikasi.

Sebagai bagian dari penggunaan instrumentasi Application Insights, kami mengumpulkan dan mengirim data diagnostik ke Microsoft. Data ini membantu kami menjalankan dan meningkatkan Application Insights. Anda memiliki opsi untuk menonaktifkan pengumpulan data yang tidak penting. Untuk mempelajari lebih lanjut, lihat Statsbeat in Azure Application Insights.

Opsi konfigurasi

Dalam file applicationinsights.json, Anda juga dapat mengonfigurasi pengaturan ini:

  • Nama peran cloud
  • Instans peran cloud
  • Pengambilan sampel
  • Metrik JMX
  • Dimensi kustom
  • Prosesor telemetri (pratinjau)
  • Log otomatis
  • Metrik Mikrometer autocollected, yang meliputi metrik Spring Boot Actuator
  • Heartbeat
  • Proksi HTTP
  • Diagnostik mandiri

Untuk informasi selengkapnya, lihat Opsi konfigurasi.

Pustaka instrumentasi

Java 3.x menyertakan pustaka instrumentasi berikut.

Permintaan otomatis

  • Konsumen JMS
  • Konsumen Kafka
  • Netty/WebFlux
  • Servlet
  • Penjadwalan musim semi

Dependensi otomatis

Dependensi autocollected ditambah propagasi jejak terdistribusi hilir:

  • Apache HttpClient
  • Apache HttpAsyncClient
  • AsyncHttpClient
  • Google HttpClient
  • gRPC
  • java.net.HttpURLConnection
  • Java 11 HttpClient
  • Klien JAX-RS
  • Jetty HttpClient
  • JMS
  • Kafka
  • Klien netty
  • OkHttp

Dependensi autocollected tanpa propagasi jejak terdistribusi hilir:

  • Cassandra
  • JDBC
  • MongoDB (asinkron dan sinkronisasi)
  • Redis (Lettuce dan Jedis)

Log yang diolek otomatis

  • java.util.logging
  • Log4j, yang mencakup properti MDC
  • SLF4J/Logback, yang mencakup properti MDC

Metrik yang dicollek otomatis

  • Mikrometer, yang mencakup metrik Spring Boot Actuator
  • Metrik JMX

Azure SDK

Telemetri yang dipancarkan oleh SDK Azure ini dikalik otomatis secara default:

Mengubah telemetri

Bagian ini menjelaskan cara memodifikasi telemetri.

Menambahkan atribut rentang

Anda dapat menggunakan opentelemetry-api untuk menambahkan atribut ke rentang. Atribut ini dapat mencakup penambahan dimensi bisnis kustom ke telemetri Anda. Anda juga dapat menggunakan atribut untuk mengatur bidang opsional dalam skema Insights Aplikasi, seperti User ID atau CLIENT IP.

Menambahkan dimensi kustom

Menambahkan satu atau beberapa dimensi kustom akan mengisi bidang customDimensions di tabel permintaan, dependensi, atau pengecualian.

Catatan

Fitur ini hanya ada di 3.2.0 dan yang lebih baru.

  1. Tambahkan opentelemetry-api-1.6.0.jar ke aplikasi Anda:

    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-api</artifactId>
      <version>1.6.0</version>
    </dependency>
    
  2. Tambahkan dimensi kustom dalam kode Anda:

    import io.opentelemetry.api.trace.Span;
    
    Span.current().setAttribute("mycustomdimension", "myvalue1");
    

Mengatur ID pengguna

Mengisi bidang ID pengguna dalam tabel permintaan, dependensi, atau pengecualian.

Penting

Konsultasikan undang-undang privasi yang berlaku sebelum Anda menetapkan ID Pengguna yang Diautentikasi.

Catatan

Fitur ini hanya ada di 3.2.0 dan yang lebih baru.

  1. Tambahkan opentelemetry-api-1.6.0.jar ke aplikasi Anda:

    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-api</artifactId>
      <version>1.6.0</version>
    </dependency>
    
  2. Atur user_Id kode Anda:

    import io.opentelemetry.api.trace.Span;
    
    Span.current().setAttribute("enduser.id", "myuser");
    

Dapatkan ID jejak atau SPAN ID

Anda dapat menggunakan opentelemetry-api untuk mendapatkan id jejak atau span ID. Tindakan ini dapat dilakukan untuk menambahkan pengidentifikasi ini ke telemetri penebangan yang ada untuk meningkatkan korelasi ketika Anda men-debug dan mendiagnosis masalah.

Catatan

Fitur ini hanya ada di 3.2.0 dan yang lebih baru.

  1. Tambahkan opentelemetry-api-1.6.0.jar ke aplikasi Anda:

    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-api</artifactId>
      <version>1.6.0</version>
    </dependency>
    
  2. Dapatkan ID pelacakan permintaan dan ID rentang dalam kode Anda:

    import io.opentelemetry.api.trace.Span;
    
    String traceId = Span.current().getSpanContext().getTraceId();
    String spanId = Span.current().getSpanContext().getSpanId();
    

Telemetri kustom

Tujuan kami dalam Aplikasi Insights Java 3.x adalah untuk memungkinkan Anda mengirim telemetri kustom Anda dengan menggunakan API standar.

Saat ini kami mendukung Micrometer, kerangka kerja pengelogan populer, dan Application Insights Java 2.x SDK. Aplikasi Insights Java 3.x secara otomatis menangkap telemetri yang dikirim melalui API ini dan menghubungkannya dengan telemetri autocollected.

Telemetri kustom yang didukung

Tabel berikut mewakili jenis telemetri kustom yang didukung saat ini yang dapat Anda aktifkan untuk melengkapi agen Java 3.x. Untuk meringkas:

  • Metrik kustom didukung melalui mikrometer.
  • Pengecualian dan jejak khusus didukung melalui kerangka kerja penebangan.
  • Permintaan kustom, dependensi, dan pengecualian didukung melalui opentelemetry-api .
  • Semua jenis telemetri kustom didukung melalui Aplikasi Insights Java 2.x SDK.
Tipe telemetri kustom Mikrometer Log4j, logback, JUL 2.x SDK opentelemetry-api
Peristiwa kustom Ya
Metrik kustom Ya Ya
Dependensi Ya Ya
Pengecualian Ya Ya Ya
Tampilan halaman Ya
Permintaan Ya Ya
Jejak Ya Ya

Saat ini, kami tidak berencana untuk merilis SDK dengan Application Insights 3.x.

Application Insights Java 3.x sudah mendengarkan telemetri yang dikirim ke Application Insights Java 2.x SDK. Fungsi ini merupakan bagian penting dari cerita upgrade untuk pengguna 2.x yang ada. Dan itu mengisi celah penting dalam dukungan telemetri khusus kami sampai API OpenTelemetry umumnya tersedia.

Mengirim metrik kustom dengan menggunakan Micrometer

  1. Tambahkan Mikrometer ke aplikasi Anda:

    <dependency>
      <groupId>io.micrometer</groupId>
      <artifactId>micrometer-core</artifactId>
      <version>1.6.1</version>
    </dependency>
    
  2. Gunakan registri global Micrometer untuk membuat meter:

    static final Counter counter = Metrics.counter("test_counter");
    
  3. Gunakan penghitung untuk merekam metrik:

    counter.increment();
    

Mengirim jejak dan pengecualian kustom dengan menggunakan kerangka pembuatan log favorit Anda

Log4j, Logback, dan java.util.logging diproseskan secara otomatis. Penebangan yang dilakukan melalui kerangka kerja penebangan ini secara otomatis dipilih sebagai jejak dan telemetri pengecualian.

Secara default, pengelogan hanya dikumpulkan ketika logging tersebut dilakukan pada tingkat INFO atau di atasnya. Untuk mengubah tingkat ini, lihat opsi konfigurasi.

Jika Anda ingin melampirkan dimensi kustom ke log Anda, gunakan Log4j 1.2 MDC,Log4j 2 MDC,atau Logback MDC. Application Insights Java 3.x secara otomatis mengambil properti MDC ini sebagai dimensi kustom pada telemetri pelacakan dan pengecualian Anda.

Mengirim telemetri kustom dengan menggunakan SDK 2.x

  1. Tambahkan applicationinsights-core-2.6.3.jar ke aplikasi Anda. Semua versi 2.x didukung oleh Aplikasi Insights Java 3.x. Jika Anda punya pilihan. Ada baiknya menggunakan versi terbaru:

    <dependency>
      <groupId>com.microsoft.azure</groupId>
      <artifactId>applicationinsights-core</artifactId>
      <version>2.6.3</version>
    </dependency>
    
  2. Membuat TelemetryClient:

    static final TelemetryClient telemetryClient = new TelemetryClient();
    
  3. Gunakan klien untuk mengirim telemetri kustom:

    Acara
    telemetryClient.trackEvent("WinGame");
    
    Metrik
    telemetryClient.trackMetric("queueLength", 42.0);
    
    Dependensi
    boolean success = false;
    long startTime = System.currentTimeMillis();
    try {
        success = dependency.call();
    } finally {
        long endTime = System.currentTimeMillis();
        RemoteDependencyTelemetry telemetry = new RemoteDependencyTelemetry();
        telemetry.setSuccess(success);
        telemetry.setTimestamp(new Date(startTime));
        telemetry.setDuration(new Duration(endTime - startTime));
        telemetryClient.trackDependency(telemetry);
    }
    
    Log
    telemetryClient.trackTrace(message, SeverityLevel.Warning, properties);
    
    Pengecualian
    try {
        ...
    } catch (Exception e) {
        telemetryClient.trackException(e);
    }
    

Pemecahan Masalah

Untuk bantuan pemecahan masalah, lihat Pemecahan masalah.

Dukungan

Untuk mendapatkan dukungan:

Umpan balik OpenTelemetry

Untuk memberikan umpan balik:

Langkah berikutnya