Instrumen untuk Cloud Trace

Dokumen ini memberikan ringkasan singkat tentang cara melengkapi aplikasi Anda untuk Cloud Trace. Untuk mengetahui petunjuk mendetail tentang cara menyiapkan Cloud Trace, lihat halaman penyiapan khusus bahasa.

Cloud Trace menyediakan data pelacakan terdistribusi untuk aplikasi Anda. Setelah menginstrumentasi aplikasi, Anda dapat memeriksa data latensi untuk satu permintaan dan melihat latensi gabungan untuk seluruh aplikasi di konsol Cloud Trace.

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 rekaman aktivitas, serta dapat mengirimkan 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 mengukur 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 serta Ringkasan Agen Operasional.

  • Panggil Telemetry API atau Cloud Trace API secara langsung.

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

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

Contoh instrumentasi yang kami berikan menggunakan OpenTelemetry:

  • Untuk mempelajari server MCP Google Cloud jarak jauh mana yang mendukung pembuatan rekaman aktivitas, dan untuk mempelajari cara mengonfigurasi aplikasi Anda agar menginstruksikan server ini untuk membuat rentang, lihat Menyelidiki panggilan MCP menggunakan Trace.

Kapan harus membuat rentang

Library klien Cloud Trace biasanya mempertahankan konteks trace global yang menyimpan informasi tentang rentang saat ini, termasuk ID trace-nya dan apakah trace tersebut diambil sampelnya. Library ini biasanya membuat rentang pada batas RPC. Namun, Anda mungkin perlu membuat rentang jika algoritma pembuatan default tidak cukup untuk kebutuhan Anda.

Rentang aktif saat ini dapat diakses oleh konteks trace global, yang terkadang di-wrap dalam objek Tracer. Anda dapat menambahkan informasi yang relevan dengan aplikasi menggunakan 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. Karena konteks bersifat global, aplikasi multithread yang memperbarui konteks harus menggunakan isolasi yang sesuai.

Waktu untuk memberikan kredensial autentikasi

Anda umumnya tidak perlu memberikan kredensial autentikasi ke aplikasi atau menentukan ID project di aplikasi saat Anda berjalan di Google Cloud. Google Cloud Untuk beberapa bahasa, Anda perlu menentukan ID project Google Cloud meskipun Anda menjalankan di Google Cloud. Selain itu, jika Anda menggunakan mode Autopilot untuk Google Kubernetes Engine, atau jika Anda mengaktifkan Workload Identity Federation for GKE, Anda harus mengonfigurasi aplikasi Anda untuk menggunakan Workload Identity Federation for GKE.

Jika menjalankan di luar Google Cloud, Anda harus memberikan kredensial autentikasi ke aplikasi Anda. Anda juga harus menentukan project IDGoogle Cloud di aplikasi Anda.

Untuk mengetahui detailnya, buka halaman penyiapan khusus bahasa.

Cara memaksa permintaan untuk dilacak

Kecuali jika aplikasi Anda selalu mengambil sampel setiap rentang, secara umum, permintaan tidak dapat dipaksa untuk dilacak secara menyeluruh karena setiap komponen dalam permintaan menyeluruh membuat keputusan pengambilan sampel sendiri. Namun, Anda dapat memengaruhi keputusan dengan menambahkan tanda sampled ke header rekaman aktivitas, dengan tanda ini ditetapkan 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.

Untuk komponen hilir yang kodenya Anda miliki, Anda harus menentukan apakah logika instrumentasi Anda mematuhi tanda sampled. Misalnya, saat menggunakan OpenTelemetry untuk instrumentasi, Anda dapat menggunakan sampler ParentBased untuk memastikan tanda sampel induk dipatuhi.

Google Cloud layanan yang mencatat informasi pelacakan ke Cloud Trace biasanya menerima tanda pengambilan sampel induk sebagai petunjuk; namun, sebagian besar layanan juga membatasi pengambilan sampel. Setiap layanan Google Cloud menentukan apakah layanan tersebut mendukung pelacakan, cara penggunaan tanda sampling induk, dan batas frekuensi pada sampling.

Cara menghubungkan data metrik dan rekaman aktivitas

Anda dapat mengorelasikan data metrik bernilai distribusi dengan rekaman aktivitas dengan melampirkan contoh ke titik data metrik. Jika Anda menyelesaikan langkah-langkah konfigurasi yang diperlukan, OpenTelemetry, yang merupakan library instrumentasi yang direkomendasikan, akan otomatis menambahkan contoh ini. Untuk mengetahui informasi selengkapnya, lihat Mengorelasikan metrik dan rekaman aktivitas menggunakan contoh.

Mengonfigurasi project dan platform Anda

  1. Pastikan Cloud Trace API diaktifkan.

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

    Aktifkan Cloud Trace API.

    Peran yang diperlukan untuk mengaktifkan API

    Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.

    Mengaktifkan API

  2. Konfigurasi platform Anda.

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

    • 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 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 menyetel 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 dalam bentuk akun layanan 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 akun layanan di jalur default untuk sistem operasi Anda. Berikut adalah 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 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

Untuk mengetahui informasi konfigurasi mendetail, contoh, dan link ke GitHub serta repositori open source lainnya, buka halaman penyiapan untuk bahasa Anda.