Membuat trace dan metrik dengan Java

Dokumen ini menjelaskan cara memodifikasi aplikasi Java untuk mengumpulkan data pelacakan dan metrik menggunakan framework OpenTelemetry open source, dan cara menulis log JSON terstruktur ke standard out. Dokumen ini juga memberikan informasi tentang contoh aplikasi Java Spring Boot yang dapat Anda instal dan jalankan. Aplikasi dikonfigurasi untuk menghasilkan metrik, trace, dan log. Langkah-langkahnya akan sama, terlepas dari apakah Anda menggunakan Framework Spring Boot atau tidak.

Tentang instrumentasi manual dan otomatis

Instrumentasi yang dijelaskan dalam dokumen ini mengandalkan instrumentasi otomatis OpenTelemetry untuk mengirim telemetri ke project Google Cloud Anda. Untuk Java, instrumentasi otomatis mengacu pada praktik memasukkan bytecode secara dinamis ke dalam library dan framework untuk menangkap telemetri. Instrumentasi otomatis dapat mengumpulkan telemetri untuk hal-hal seperti panggilan HTTP masuk dan keluar. Untuk mengetahui informasi selengkapnya, lihat Instrumentasi Otomatis untuk Java.

OpenTelemetry juga menyediakan API untuk menambahkan instrumentasi kustom ke kode Anda sendiri. OpenTelemetry menyebut hal ini sebagai instrumentasi manual. Dokumen ini tidak menjelaskan instrumentasi manual. Untuk contoh dan informasi tentang topik tersebut, lihat Instrumentasi manual.

Sebelum memulai

Aktifkan API Cloud Logging API, Cloud Monitoring API, and Cloud Trace API.

Mengaktifkan API

Melengkapi aplikasi untuk mengumpulkan trace, metrik, dan log

Untuk melengkapi aplikasi Anda guna mengumpulkan data pelacakan dan metrik, serta untuk menulis JSON terstruktur ke standard out, lakukan langkah-langkah berikut seperti yang dijelaskan di bagian selanjutnya dari dokumen ini:

Mengonfigurasi aplikasi untuk menggunakan Agen Java OpenTelemetry
Mengonfigurasi OpenTelemetry
Mengonfigurasi logging terstruktur
Menulis log terstruktur

Mengonfigurasi aplikasi Anda untuk menggunakan Agen Java OpenTelemetry

Untuk mengonfigurasi aplikasi agar dapat menulis log terstruktur serta mengumpulkan metrik dan data trace menggunakan OpenTelemetry, perbarui pemanggilan aplikasi Anda untuk menggunakan OpenTelemetry Java Agent. Metode instrumentasi aplikasi Anda ini dikenal sebagai instrumentasi otomatis karena tidak memerlukan modifikasi kode aplikasi.

Contoh kode berikut mengilustrasikan Dockerfile yang mendownload file JAR OpenTelemetry Java Agent dan mengupdate pemanggilan command line untuk meneruskan flag -javaagent.

RUN wget -O /opentelemetry-javaagent.jar https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v1.31.0/opentelemetry-javaagent.jar
CMD sh -c "java -javaagent:/opentelemetry-javaagent.jar -cp app:app/lib/* com.example.demo.DemoApplication \
	2>&1 | tee /var/log/app.log"

Atau, Anda juga dapat menetapkan tanda -javaagent dalam variabel lingkungan JAVA_TOOL_OPTIONS:

export JAVA_TOOL_OPTIONS="-javaagent:PATH/TO/opentelemetry-javaagent.jar"

Konfigurasi OpenTelemetry

Konfigurasi default untuk Agen Java OpenTelemetry mengekspor trace dan metrik menggunakan protokol OTLP. API ini juga mengonfigurasi OpenTelemetry untuk menggunakan format Konteks Rekaman Aktivitas W3C untuk menyebarkan konteks rekaman aktivitas. Konfigurasi ini memastikan bahwa span memiliki hubungan induk-turunan yang benar di dalam rekaman aktivitas.

Untuk mengetahui informasi selengkapnya dan opsi konfigurasi, lihat instrumentasi otomatis Java OpenTelemetry.

Mengonfigurasi logging terstruktur

Untuk menyertakan informasi rekaman aktivitas sebagai bagian dari log berformat JSON yang ditulis ke output standar, konfigurasikan aplikasi Anda untuk menghasilkan log terstruktur dalam format JSON. Sebaiknya gunakan Logback sebagai penerapan logging Anda. Contoh kode berikut mengilustrasikan file logback.xml yang dikonfigurasi untuk menghasilkan log terstruktur JSON menggunakan Encoder Logstash:

<encoder class="net.logstash.logback.encoder.LogstashEncoder">
  <!-- Format JSON logs for the Logging agent
  https://cloud.google.com/logging/docs/structured-logging#special-payload-fields -->
  <provider class="net.logstash.logback.composite.loggingevent.LoggingEventPatternJsonProvider">
    <pattern>
      {
        "logging.googleapis.com/trace": "%mdc{trace_id}",
        "logging.googleapis.com/spanId": "%mdc{span_id}",
        "logging.googleapis.com/trace_sampled": "#asBoolean{%replace(%mdc{trace_flags}){'01', 'true'}}"
      }
    </pattern>
  </provider>

  <!-- Rename fields for the Logging agent -->
  <fieldNames>
    <level>severity</level>
    <timestamp>timestamp</timestamp>
    <levelValue>[ignore]</levelValue>
  </fieldNames>

  <!-- Exclude tracing MDC keys which are handled above -->
  <excludeMdcKeyName>trace_id</excludeMdcKeyName>
  <excludeMdcKeyName>span_id</excludeMdcKeyName>
  <excludeMdcKeyName>trace_flags</excludeMdcKeyName>
</encoder>

Konfigurasi sebelumnya mengekstrak informasi tentang span aktif dari Mapped Diagnostic Context SLF4J dan menambahkan informasi tersebut sebagai atribut ke log. Atribut ini kemudian dapat digunakan untuk mengkorelasikan log dengan trace:

logging.googleapis.com/trace: Nama resource trace yang terkait dengan entri log.
logging.googleapis.com/spanId: ID span dengan pelacakan yang dikaitkan dengan entri log.
logging.googleapis.com/trace_sampled: Nilai kolom ini harus true atau false.

Untuk mengetahui informasi selengkapnya tentang kolom ini, lihat struktur LogEntry.

Menulis log terstruktur

Untuk menulis log terstruktur yang tertaut ke suatu rekaman aktivitas, gunakan logging API SLF4J. Misalnya, pernyataan berikut menunjukkan cara memanggil metode Logger.info():

logger.info("handle /multi request with subRequests={}", subRequests);

Agen Java OpenTelemetry secara otomatis mengisi Konteks Diagnostik yang Dipetakan SLF4J dengan konteks span dari span aktif saat ini dalam OpenTelemetry Context. Konteks Diagnostik yang Dipetakan kemudian disertakan dalam log JSON seperti yang dijelaskan dalam Mengonfigurasi logging terstruktur.

Menjalankan aplikasi contoh yang dikonfigurasi untuk mengumpulkan telemetri

Aplikasi contoh menggunakan format yang tidak bergantung pada vendor, termasuk JSON untuk log dan OTLP untuk metrik dan trace, serta Spring Boot Framework. Untuk merutekan telemetri ke Google Cloud, contoh ini menggunakan Collector OpenTelemetry yang dikonfigurasi dengan pengekspor Google. Aplikasi ini memiliki dua endpoint:

Endpoint /multi ditangani oleh fungsi handleMulti. Generator beban di aplikasi mengeluarkan permintaan ke endpoint /multi. Saat menerima permintaan, endpoint ini akan mengirimkan antara tiga hingga tujuh permintaan ke endpoint /single di server lokal.

/**
 * handleMulti handles an http request by making 3-7 http requests to the /single endpoint.
 *
 * <p>OpenTelemetry instrumentation requires no changes here. It will automatically generate a
 * span for the controller body.
 */
@GetMapping("/multi")
public Mono<String> handleMulti() throws Exception {
  int subRequests = ThreadLocalRandom.current().nextInt(3, 8);

  // Write a structured log with the request context, which allows the log to
  // be linked with the trace for this request.
  logger.info("handle /multi request with subRequests={}", subRequests);

  // Make 3-7 http requests to the /single endpoint.
  return Flux.range(0, subRequests)
      .concatMap(
          i -> client.get().uri("http://localhost:8080/single").retrieve().bodyToMono(Void.class))
      .then(Mono.just("ok"));
}

Endpoint /single ditangani oleh fungsi handleSingle. Saat menerima permintaan, endpoint ini akan tidur dalam waktu singkat, lalu merespons dengan string.

/**
 * handleSingle handles an http request by sleeping for 100-200 ms. It writes the number of
 * milliseconds slept as its response.
 *
 * <p>OpenTelemetry instrumentation requires no changes here. It will automatically generate a
 * span for the controller body.
 */
@GetMapping("/single")
public String handleSingle() throws InterruptedException {
  int sleepMillis = ThreadLocalRandom.current().nextInt(100, 200);
  logger.info("Going to sleep for {}", sleepMillis);
  Thread.sleep(sleepMillis);
  logger.info("Finishing the request");
  return String.format("slept %s\n", sleepMillis);
}

Mendownload dan men-deploy aplikasi

Untuk menjalankan contoh, lakukan hal berikut:

Di konsol Google Cloud, aktifkan Cloud Shell.

Aktifkan Cloud Shell

Di bagian bawah Google Cloud Console, Cloud Shell sesi akan terbuka dan menampilkan perintah command line. Cloud Shell adalah lingkungan shell dengan Google Cloud CLI yang sudah terinstal, dan dengan nilai yang sudah ditetapkan untuk project Anda saat ini. Diperlukan waktu beberapa detik untuk melakukan inisialisasi sesi.

Meng-cloning repository

git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-java

Buka direktori contoh:

cd opentelemetry-operations-java/examples/instrumentation-quickstart

Buat dan jalankan contoh:

docker compose up --abort-on-container-exit

Jika Anda tidak menjalankan Cloud Shell, jalankan aplikasi dengan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS yang mengarah ke file kredensial. Kredensial Default Aplikasi menyediakan file kredensial di $HOME/.config/gcloud/application_default_credentials.json.

# Set environment variables
export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/application_default_credentials.json"
export USERID="$(id -u)"

# Run
docker compose -f docker-compose.yaml -f docker-compose.creds.yaml up --abort-on-container-exit

Melihat metrik Anda

Instrumentasi OpenTelemetry di aplikasi contoh menghasilkan metrik Prometheus yang dapat Anda tampilkan menggunakan Metrics Explorer:

Prometheus/http_server_duration_milliseconds/histogram mencatat durasi permintaan server dan menyimpan hasilnya dalam histogram.
Prometheus/http_client_duration_milliseconds/histogram mencatat durasi permintaan klien dan menyimpan hasilnya dalam histogram.

Untuk melihat metrik yang dihasilkan oleh aplikasi contoh, lakukan hal berikut:

Di panel navigasi Konsol Google Cloud, pilih Monitoring, lalu pilih Metrics Explorer:
Buka Metrics Explorer
Pada elemen Metrik, luaskan menu Pilih metrik, masukkan http_server di panel filter, lalu gunakan submenu untuk memilih jenis dan metrik resource tertentu:
1. Di menu Active resources, pilih Prometheus Target.
2. Di menu Active metric criteria, pilih Http.
3. Di menu Metrik aktif, pilih metrik.
4. Klik Terapkan.
Konfigurasi cara data ditampilkan.
Jika pengukuran untuk metrik bersifat kumulatif, Metrics Explorer otomatis menormalisasi data yang diukur berdasarkan periode penyelarasan, sehingga diagram akan menampilkan rasio. Untuk mengetahui informasi selengkapnya, lihat Jenis, jenis, dan konversi.

Saat nilai bilangan bulat atau ganda diukur, seperti dengan dua metrik counter, Metrics Explorer otomatis menjumlahkan semua deret waktu. Untuk melihat data rute HTTP /multi dan /single, tetapkan menu pertama entri Aggregation ke None.

Untuk informasi selengkapnya tentang cara mengonfigurasi diagram, lihat Memilih metrik saat menggunakan Metrics Explorer.

Melihat trace Anda

Untuk melihat data trace, lakukan langkah berikut:

Di panel navigasi konsol Google Cloud, pilih Trace, lalu pilih Trace explorer:
Buka Trace explorer
Di diagram sebar, pilih rekaman aktivitas dengan URI /multi.
Pada diagram Gantt di panel Trace details, pilih span yang berlabel /multi.

Sebuah panel yang menampilkan informasi tentang permintaan HTTP akan terbuka. Detail ini mencakup metode, kode status, jumlah byte, dan agen pengguna pemanggil.
Untuk melihat log yang terkait dengan rekaman aktivitas ini, pilih tab Logs & Events.

Tab ini menunjukkan log individual. Untuk melihat detail entri log, luaskan entri log. Anda juga dapat mengklik View Logs dan melihat log menggunakan Logs Explorer.

Untuk mengetahui informasi selengkapnya tentang cara menggunakan penjelajah Cloud Trace, lihat Menemukan dan menjelajahi trace.

Melihat log

Dari Logs Explorer, Anda dapat memeriksa log, dan Anda juga dapat melihat rekaman aktivitas terkait, jika ada.

Di panel navigasi konsol Google Cloud, pilih Logging, lalu pilih Logs Explorer:
Buka Logs Explorer
Temukan log dengan deskripsi handle /multi request.

Untuk melihat detail log, luaskan entri log.
Klik Traces pada entri log dengan pesan "handle /multi request", lalu pilih View trace details.

Panel Trace details akan terbuka dan menampilkan trace yang dipilih.

Untuk mengetahui informasi selengkapnya tentang penggunaan Logs Explorer, baca Melihat log menggunakan Logs Explorer.