Instrumen untuk Cloud Trace

Anda dapat melengkapi aplikasi untuk Cloud Trace guna merekam data pelacakan terdistribusi, memeriksa latensi untuk setiap permintaan, dan melihat latensi gabungan di seluruh layanan Anda di konsol Trace.

Dokumen ini memberikan ringkasan pendekatan instrumentasi dan opsi konfigurasi. Untuk mengetahui petunjuk langkah demi langkah untuk bahasa pemrograman tertentu, lihat halaman penyiapan khusus bahasa.

Kapan harus menginstrumentasikan aplikasi Anda

Jika data rekaman aktivitas untuk memvalidasi performa atau memecahkan masalah tidak diambil secara otomatis, lakukan instrumentasi pada aplikasi Anda.

Instrumentasikan aplikasi Anda untuk mengumpulkan informasi spesifik yang membantu Anda memahami performanya dan memecahkan masalah kegagalan. Beberapa framework instrumentasi open source mengumpulkan data log, metrik, dan trace, serta dapat mengirim data tersebut ke vendor mana pun, termasuk Google Cloud. Untuk aplikasi agentik Anda, beberapa framework dapat mengumpulkan perintah dan respons Anda atau meneruskan konteks yang memungkinkan pelacakan beberapa panggilan server MCP Google Cloud jarak jauh.

Untuk menginstrumentasi aplikasi, sebaiknya gunakan framework instrumentasi open source yang netral terhadap vendor, seperti OpenTelemetry, bukan API atau library klien khusus produk dan vendor. Untuk mengetahui informasi tentang framework ini, lihat Pengukuran dan kemampuan observasi dan Memilih pendekatan pengukuran.

Cara menginstrumentasi aplikasi

Ada beberapa pendekatan yang dapat Anda gunakan untuk menginstrumentasi aplikasi:

  • Direkomendasikan: Gunakan OpenTelemetry, konfigurasi aplikasi Anda dengan pengekspor OTLP yang mengirim data aktivitas ke pengumpul, dan konfigurasi pengumpul untuk mengirim data aktivitas ke project Google Cloud Anda menggunakan Telemetry (OTLP) API. Untuk mempelajari rekomendasi kami lebih lanjut, lihat artikel Memilih pendekatan instrumentasi.

  • Gunakan OpenTelemetry dan konfigurasi aplikasi Anda dengan pengekspor OTLP yang mengirimkan data trace ke Google Cloud project Anda menggunakan Telemetry API.

  • Jika Anda menulis aplikasi yang berjalan di Compute Engine, Anda dapat menggunakan Agen Operasional dan penerima OpenTelemetry Protocol (OTLP) untuk mengumpulkan trace dan metrik dari aplikasi Anda. Agen Operasional juga dapat mengumpulkan log, tetapi tidak menggunakan OTLP. Untuk mengetahui informasi selengkapnya, lihat Menggunakan Agen Operasional dan OTLP dan Ringkasan Agen Operasional.

  • Panggil langsung Telemetry API atau Cloud Trace API.

  • Untuk aplikasi Spring Boot, konfigurasikan aplikasi tersebut untuk meneruskan data trace yang dikumpulkannya ke Cloud Trace. Untuk mengetahui informasi tentang prosedur ini, lihat Spring Cloud for Google Cloud: Cloud Trace.

  • Gunakan library klien Cloud Trace atau gunakan pengekspor Cloud Trace untuk OpenTelemetry.

Contoh instrumentasi

Contoh instrumentasi yang kami berikan menggunakan OpenTelemetry:

Membuat rentang kustom

Meskipun OpenTelemetry dan library klien memungkinkan Anda membuat rentang kustom, Anda mungkin tidak perlu membuatnya secara manual karena library ini otomatis membuat rentang di batas RPC.

Anda juga dapat menambahkan informasi yang relevan dengan aplikasi Anda dengan menambahkan anotasi dan tag kustom ke rentang yang ada, atau Anda dapat membuat rentang turunan baru dengan anotasi dan tagnya sendiri untuk melacak perilaku aplikasi dengan perincian yang lebih baik.

Biasanya, library mempertahankan konteks pelacakan global yang menyimpan informasi tentang rentang saat ini, termasuk ID pelacakan dan status pengambilan sampelnya. Aplikasi dapat mengakses rentang saat ini melalui konteks rekaman aktivitas global. Karena konteksnya bersifat global, pastikan aplikasi multi-thread menyebarkan konteks di seluruh thread untuk mempertahankan data rekaman aktivitas yang akurat.

Memaksa pengambilan sampel rekaman aktivitas

Anda tidak dapat memaksa rentang untuk diambil sampelnya karena setiap komponen di jalur permintaan membuat keputusan pengambilan sampel yang independen. Namun, Anda dapat memengaruhi komponen hilir dengan menyetel flag sampled di header rekaman aktivitas ke true. Setelan ini adalah petunjuk untuk komponen turunan guna mengambil sampel permintaan. Untuk mengetahui informasi selengkapnya tentang header rekaman aktivitas, lihat Protokol untuk propagasi konteks.

  • Aplikasi Anda: Anda mengonfigurasi cara logika instrumentasi mematuhi flag sampled. Misalnya, saat menggunakan OpenTelemetry, Anda dapat menggunakan sampler ParentBased untuk memastikan tanda sampling induk dipatuhi.

  • Google Cloud layanan: Setiap layanan menentukan dukungan pelacakannya sendiri. Secara umum, layanan menerima tanda pengambilan sampel induk sebagai petunjuk saat menerapkan batas kecepatan pengambilan sampelnya sendiri.

Menghubungkan metrik dan rekaman aktivitas dengan contoh

Anda dapat mengorelasikan data metrik dengan rekaman aktivitas menggunakan contoh. Contoh adalah rentang atau permintaan sampel perwakilan yang terkait dengan pengukuran metrik. Misalnya, contoh dapat berisi link ke rekaman aktivitas, yang memungkinkan Anda mengorelasikan data metrik dan rekaman aktivitas. Untuk contoh berbasis OpenTelemetry, lihat Mengorelasikan metrik dan trace menggunakan contoh.

Anda mungkin melihat contoh yang dibuat sistem pada diagram dasbor yang menampilkan hasil kueri SQL untuk data rekaman aktivitas. Contoh ini menautkan hasil kueri tertentu langsung ke rekaman aktivitas. Untuk mengetahui informasi selengkapnya, lihat bagian Membuat dan menampilkan contoh rekaman aktivitas.

Mengonfigurasi project dan platform Anda

Bagian ini menjelaskan API dan peran Identity and Access Management (IAM) yang diperlukan, serta menjelaskan cara mengonfigurasi kredensial autentikasi untuk platform Anda.

Mengaktifkan API

Secara default, Google Cloud project telah mengaktifkan Cloud Trace API dan Telemetry API, dan Anda tidak perlu melakukan tindakan apa pun. Namun, batasan keamanan yang ditentukan oleh organisasi Anda mungkin telah menonaktifkan salah satu atau kedua API ini. Untuk mengetahui informasi pemecahan masalah, lihat Mengembangkan aplikasi di lingkungan Google Cloud yang terbatas.

Aktifkan Telemetry dan Cloud Trace API.

Peran yang diperlukan untuk mengaktifkan API

Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Admin Penggunaan Layanan (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

Aktifkan API

Memberikan peran IAM

Peran IAM yang diperlukan bergantung pada apakah Anda melihat data rekaman aktivitas di konsol Google Cloud atau menulis data rekaman aktivitas ke project Anda:

  • Untuk mendapatkan izin yang diperlukan guna melihat data rekaman aktivitas menggunakan konsol Google Cloud , minta administrator Anda untuk memberi Anda peran IAM Cloud Trace User (roles/cloudtrace.user) di project Anda.

  • Untuk mendapatkan izin yang diperlukan guna menulis data rekaman aktivitas menggunakan Cloud Trace API, minta administrator Anda untuk memberi Anda peran IAM Cloud Trace Agent (roles/cloudtrace.agent) di project Anda.

  • Untuk mendapatkan izin yang diperlukan guna menulis data rekaman aktivitas menggunakan Telemetry API, minta administrator Anda untuk memberi Anda peran IAM Cloud Telemetry Writer (roles/telemetry.writer) di project Anda.

Autentikasikan

Bagian ini menjelaskan cara mengautentikasi saat aplikasi Anda berjalan di Google Cloud dan saat aplikasi berjalan di tempat lain.

Jalankan di Google Cloud

Saat aplikasi Anda berjalan di Google Cloud, Anda umumnya tidak perlu memberikan kredensial autentikasi. Namun, beberapa library klien bahasa memerlukan ID project meskipun dihosting di Google Cloud.

Pastikan Google Cloud platform Anda telah mengaktifkan cakupan akses Cloud Trace API. Untuk konfigurasi berikut, setelan access-scope default mencakup cakupan akses Cloud Trace API:

Jika Anda menggunakan cakupan akses kustom, Anda harus memastikan bahwa cakupan akses Cloud Trace API diaktifkan. Misalnya, jika Anda menggunakan Google Cloud CLI untuk membuat cluster GKE dan jika Anda menentukan flag --scopes, pastikan cakupan mencakup trace.append. Perintah berikut mengilustrasikan cara menetapkan flag --scopes:

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

Menjalankan secara lokal dan di tempat lain

Jika aplikasi Anda berjalan di luar Google Cloud, Anda harus memberikan kredensial autentikasi ke library klien. Akun layanan harus diberi peran Agen Cloud Trace (roles/cloudtrace.agent). Untuk mengetahui informasi tentang peran, lihat Mengontrol akses dengan IAM.

Google Cloud library klien menggunakan Kredensial Default Aplikasi (ADC) untuk menemukan kredensial aplikasi Anda. Anda dapat memberikan kredensial ini dengan salah satu dari tiga cara berikut:

  • Jalankan gcloud auth application-default login

  • Tempatkan file kunci akun layanan di jalur default untuk sistem operasi Anda. Berikut adalah 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 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"

Langkah berikutnya