Java dan OpenTelemetry

Halaman ini ditujukan bagi developer aplikasi yang ingin mengumpulkan data Cloud Trace untuk aplikasi Java menggunakan OpenTelemetry. OpenTelemetry adalah framework instrumentasi yang tidak bergantung pada vendor yang dapat Anda gunakan untuk mengumpulkan data trace dan metrik. Untuk mengetahui informasi tentang cara menginstrumentasikan kode, lihat Instrumentasi dan kemampuan observasi.

Halaman ini akan memandu Anda melakukan langkah-langkah berikut:

  • Instal paket OpenTelemetry.
  • Konfigurasi aplikasi Anda untuk mengekspor span ke Cloud Trace.
  • Konfigurasi platform Anda.

Untuk informasi rilis, lihat referensi berikut:

Untuk konten referensi OpenTelemetry, lihat hal berikut:

Untuk detail terbaru tentang OpenTelemetry untuk Java, beserta dokumentasi dan contoh tambahan, lihat OpenTelemetry.

Sebelum memulai

  • Anda harus menggunakan Java 8 atau yang lebih baru.

  • Di panel navigasi Konsol Google Cloud, pilih APIs & Services, klik Enable APIs and Services, lalu aktifkan Cloud Trace API:

    Buka setelan Cloud Trace API

  • Jika API enabled ditampilkan, berarti API sudah diaktifkan. Jika belum, klik tombol Enable.

Menginstal paket OpenTelemetry

Untuk mengumpulkan rekaman aktivitas, tambahkan pelacakan OpenTelemetry dan pengekspor Cloud Trace untuk OpenTelemetry ke file Maven atau Gradle aplikasi Anda:

  • Untuk daftar dependensi OpenTelemetry yang baru dipublikasikan, lihat Maven dan Gradle.

  • Untuk dependensi pengekspor yang diperlukan, lihat tabel berikut:

    Maven

    <dependency>
  <groupId>com.google.cloud.opentelemetry</groupId>
  <artifactId>exporter-trace</artifactId>
  <version>0.15.0</version>
</dependency>

    Pernyataan sebelumnya menentukan versi pengekspor. Pastikan Anda memilih rilis pengekspor terbaru.

    Gradle

    implementation 'com.google.cloud.opentelemetry:exporter-trace:0.15.0'

    Pernyataan sebelumnya menentukan versi pengekspor. Pastikan Anda memilih rilis pengekspor terbaru.

Mengonfigurasi ekspor span ke Cloud Trace

Untuk mengekspor data Trace yang dikumpulkan, gunakan objek TraceExporter. Berikut adalah ilustrasi cara membuat objek ini dengan konfigurasi default:

TraceExporter traceExporter = TraceExporter.createWithDefaultConfiguration();

Anda juga dapat menentukan konfigurasi, lalu meneruskannya ke pengekspor. Misalnya, kode berikut menetapkan project Google Cloud:

TraceExporter traceExporter = TraceExporter.createWithConfiguration(
  TraceConfiguration.builder().setProjectId("MY_PROJECT").build());

Setelah pengekspor dikonfigurasi, tetapkan TracerProvider:

OpenTelemetrySdk.builder()
          .setTracerProvider(
              SdkTracerProvider.builder()
                  .addSpanProcessor(BatchSpanProcessor.builder(traceExporter).build())
                  .build())
          .buildAndRegisterGlobal();

Pada contoh sebelumnya, panggilan ke BatchSpanProcessor mengonfigurasi penyedia untuk mengirim span dengan proses latar belakang.

Untuk mengetahui informasi tentang cara menetapkan kolom autentikasi, lihat bagian penyiapan pengekspor Cloud Trace untuk OpenTelemetry.

Membuat span

Untuk mengetahui informasi tentang cara mengonfigurasi aplikasi Anda guna merekam durasi rekaman aktivitas, lihat Pelacakan OpenTelemetry. Halaman ini menjelaskan cara melakukan semua tindakan berikut:

  • Membuat span
  • Membuat span bertingkat
  • Menetapkan atribut span
  • Membuat span dengan peristiwa
  • Membuat span dengan link

Mengonfigurasi pengambilan sampel

Untuk mengetahui informasi tentang cara mengonfigurasi kapan rekaman aktivitas diambil sampelnya, lihat OpenTelemetry Sampler. Halaman ini menjelaskan opsi pengambilan sampel yang tersedia untuk Anda.

Contoh aplikasi

Untuk aplikasi contoh, lihat TraceExporterExample.java.

Konfigurasi platform Anda

Anda dapat menggunakan Cloud Trace di Google Cloud dan platform lainnya.

Berjalan di Google Cloud

Saat aplikasi Anda berjalan di Google Cloud, Anda tidak perlu memberikan kredensial autentikasi dalam bentuk akun layanan ke library klien. Namun, Anda harus memastikan bahwa platform Google Cloud Anda telah mengaktifkan cakupan akses Cloud Trace API.

Untuk mengetahui daftar lingkungan Google Cloud yang didukung, lihat Dukungan lingkungan.

Untuk konfigurasi berikut, setelan cakupan akses default akan mengaktifkan Cloud Trace API:

Jika menggunakan cakupan akses kustom, Anda harus memastikan cakupan akses API Cloud Trace diaktifkan:

  • Untuk mengetahui informasi cara mengonfigurasi cakupan akses untuk lingkungan Anda menggunakan Konsol Google Cloud, lihat Mengonfigurasi project Google Cloud.

  • Untuk pengguna gcloud, tentukan cakupan akses menggunakan flag --scopes dan sertakan cakupan akses Cloud Trace API trace.append. Misalnya, untuk membuat cluster GKE dengan hanya Cloud Trace API yang diaktifkan, lakukan hal berikut:

    gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append

Berjalan secara lokal dan di tempat lain

Jika aplikasi Anda berjalan di luar Google Cloud, Anda harus memberikan kredensial autentikasi dalam bentuk akun layanan ke library klien. Akun layanan harus berisi peran agen Cloud Trace. Untuk mengetahui petunjuknya, lihat Membuat akun layanan.

Library klien Google Cloud menggunakan Kredensial Default Aplikasi (ADC) untuk menemukan kredensial aplikasi Anda.

Anda dapat memberikan kredensial ini dengan salah satu dari tiga cara:

  • Jalankan gcloud auth application-default login

  • Tempatkan akun layanan di jalur default untuk sistem operasi Anda. Berikut ini daftar jalur default untuk Windows dan Linux:

    • Windows: %APPDATA%/gcloud/application_default_credentials.json

    • Linux: $HOME/.config/gcloud/application_default_credentials.json

  • Tetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS ke jalur ke akun layanan Anda:

Linux/macOS

    export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

Windows

    set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

PowerShell:

    $env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"

Lihat pelacakan

Di panel navigasi konsol Google Cloud, pilih Trace, lalu pilih Trace explorer:

Buka Trace explorer

Pemecahan masalah

Untuk mengetahui informasi tentang cara memecahkan masalah terkait Cloud Trace, buka halaman Pemecahan masalah.

Referensi