Mengaktifkan sinyal telemetri di Library Klien Cloud untuk Java

Google Cloud menyediakan pemantauan, logging, dan diagnostik yang andal untuk aplikasi Java.

Library klien Java diinstrumentasikan untuk memancarkan data tracing, metrik, dan logging. Pengukuran ini bersifat keikutsertaan; Anda harus mengaktifkannya secara eksplisit. Dokumen ini menjelaskan sinyal yang tersedia dan cara mengaktifkannya.

Sinyal yang tersedia

Sinyal Emas mencakup data telemetri berikut, yang mematuhi Konvensi Semantik OpenTelemetry:

  • Trace: Trace HTTP/gRPC tingkat rendah yang merepresentasikan permintaan jaringan yang dibuat oleh library klien.
  • Metrik: Metrik permintaan klien, yang melacak latensi dan kecepatan permintaan. Metrik utama adalah gcp.client.request.duration.
  • Log: Log error yang dapat ditindaklanjuti di tingkat DEBUG, yang memberikan detail untuk permintaan yang gagal di lapisan transportasi, meskipun akhirnya dicoba lagi dengan berhasil.

Sinyal mencakup atribut OpenTelemetry standar (misalnya, http.response.status_code dan rpc.system.name) dan atribut kustom khusus Google Cloud, yang dapat mencakup atribut ini dan atribut serupa:

  • gcp.client.service: Nama layanan (misalnya, pubsub atau storage).
  • gcp.client.repo: Repositori library klien (misalnya, googleapis/google-cloud-java).
  • gcp.client.version: Versi library klien.
  • gcp.client.artifact: Jalur modul tertentu (misalnya, com.google.cloud:google-cloud-secretmanager).
  • gcp.resource.destination.id: ID resource yang sedang ditindaklanjuti.
  • gcp.errors.domain: Domain error untuk log error yang dapat ditindaklanjuti.
  • gcp.errors.metadata.<key>: Kunci metadata error tambahan untuk permintaan yang gagal (diratakan).

Untuk daftar lengkap atribut standar, lihat konvensi semantik HTTP dan gRPC OpenTelemetry.

Mengaktifkan telemetri

Untuk melindungi data sensitif, sinyal telemetri dinonaktifkan secara default. Anda harus mengaktifkannya secara eksplisit untuk menggunakannya.

Pelacakan dan metrik

Di library klien Java yang dihasilkan, Anda harus mengaktifkan pelacakan dan metrik secara terprogram dengan memberikan factory tracer yang sesuai ke setelan klien Anda selama inisialisasi:

  • Pelacakan: Konfigurasi klien dengan OpenTelemetryTracingFactory.
  • Metrik: Konfigurasi klien dengan OpenTelemetryMetricsFactory.
  • Keduanya: Jika Anda ingin mengaktifkan pelacakan dan metrik, konfigurasi klien dengan CompositeTracerFactory yang mencakup kedua factory.

Logging

Log error yang dapat ditindaklanjuti diintegrasikan langsung ke framework ApiTracer inti. Untuk mengaktifkan log error yang dapat ditindaklanjuti secara global di seluruh library klien Google CloudAnda, gunakan variabel lingkungan berikut:

export GOOGLE_SDK_JAVA_LOGGING=true

Penerapan konteks pelacakan

Propagasi konteks trace di library klien Java mengharuskan tracing diaktifkan secara eksplisit.

Jika pembuatan rekaman aktivitas diaktifkan (misalnya, dengan mengonfigurasi OpenTelemetryTracingFactory) dan aplikasi Anda memiliki rentang OpenTelemetry yang aktif dalam konteks saat ini saat metode library klien dipanggil, library akan menggunakannya untuk memberikan konteks pelacakan untuk permintaan keluar. Hal ini memastikan bahwa rekaman aktivitas tingkat aplikasi Anda dapat dikorelasikan dengan log dan perilaku layanan backend.

Mengekspor telemetri

Setelah telemetri diaktifkan di library klien, aplikasi Anda harus dikonfigurasi untuk mengumpulkan dan mengekspor data ini ke backend kemampuan pengamatan Anda.

Pelacakan dan metrik

Untuk mengekspor rekaman aktivitas dan metrik yang dihasilkan oleh library klien Java, lakukan inisialisasi OpenTelemetry SDK dengan pengekspor pilihan Anda (misalnya, OTLP) dan siapkan propagator peta teks global di aplikasi Anda.

Untuk mengetahui detail selengkapnya tentang cara mengumpulkan dan mengekspor data OpenTelemetry ke Cloud Monitoring atau Cloud Trace, lihat Memilih pendekatan instrumentasi.

Logging

Library klien Java menggunakan framework logging standar seperti SLF4J dan java.util.logging. Jika GOOGLE_SDK_JAVA_LOGGING=true ditetapkan, log error yang dapat ditindaklanjuti akan dimunculkan di tingkat DEBUG.

Untuk merutekan log terstruktur ini ke Cloud Logging, konfigurasi framework logging Anda (misalnya, Logback) untuk menulis JSON ke output standar (stdout). Jika Anda men-deploy ke lingkungan seperti Google Kubernetes Engine atau Cloud Run, agen bawaan akan otomatis meng-scrape log ini.

Untuk mengetahui petunjuk mendetail tentang cara mengonfigurasi Logback atau java.util.logging untuk menghasilkan JSON yang kompatibel dengan Cloud Logging, termasuk korelasi aktivitas, lihat Mengonfigurasi logging terstruktur untuk Java.