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 agregat untuk seluruh aplikasi di konsol Cloud Trace.

Kapan harus menginstrumentasikan aplikasi Anda

Jika data rekaman aktivitas tidak diambil secara otomatis, Anda harus menginstrumentasi aplikasi untuk mengumpulkan data ini.

Anda dapat menginstrumentasi aplikasi agar mengumpulkan informasi khusus aplikasi. Beberapa framework instrumentasi open source memungkinkan Anda mengumpulkan metrik, log, dan rekaman aktivitas dari aplikasi Anda serta mengirim data tersebut ke vendor mana pun, termasuk Google Cloud. Untuk menginstrumentasi aplikasi, sebaiknya gunakan framework instrumentasi netral vendor yang bersifat open source, seperti OpenTelemetry, bukan API atau library klien khusus produk dan vendor.

Untuk mengetahui informasi tentang cara melengkapi aplikasi Anda menggunakan framework instrumentasi netral vendor, lihat Instrumentasi dan kemampuan observasi.

Cara mengukur aplikasi

Untuk menginstrumentasi aplikasi Anda guna mengumpulkan data rekaman aktivitas, Anda dapat melakukan salah satu hal berikut:

Kapan harus membuat rentang

Library klien Cloud Trace biasanya mempertahankan konteks rekaman aktivitas global yang menyimpan informasi tentang rentang saat ini, termasuk ID rekaman aktivitasnya dan apakah rekaman aktivitas 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 pelacakan 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 multi-thread yang memperbarui konteks harus menggunakan isolasi yang sesuai.

Waktu untuk memberikan kredensial autentikasi

Anda umumnya tidak perlu memberikan kredensial autentikasi ke aplikasi atau menentukan project ID 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 untuk GKE, maka Anda harus mengonfigurasi aplikasi Anda untuk menggunakan Workload Identity Federation untuk 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 disetel ke true. Setelan ini adalah petunjuk untuk komponen turunan guna mengambil sampel permintaan. Untuk mengetahui informasi selengkapnya tentang header pelacakan, 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 berdasarkan kecepatan. Setiap Google Cloud layanan menentukan apakah layanan tersebut mendukung pelacakan, cara penggunaan flag pengambilan sampel induk, dan batas frekuensi pengambilan sampel.

Cara mengorelasikan 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 yang terbatas Google Cloud .

    Enable the Cloud Trace API.

    Enable the 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 Anda telah mengaktifkan cakupan akses Cloud Trace API. Google Cloud

      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 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.