Instrumen untuk Cloud Trace

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

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

Kapan harus menginstrumentasikan aplikasi

Jika data rekaman aktivitas tidak otomatis diambil, Anda perlu melakukan instrumentasi aplikasi untuk mengumpulkan data ini.

Anda dapat melengkapi aplikasi dengan instrumen sehingga aplikasi tersebut mengumpulkan informasi khusus aplikasi. Beberapa framework instrumentasi open source memungkinkan Anda mengumpulkan metrik, log, dan trace dari aplikasi, lalu mengirim data tersebut ke vendor mana pun, termasuk Google Cloud. Untuk melengkapi aplikasi Anda, sebaiknya gunakan framework instrumentasi netral vendor yang bersifat open source, seperti OpenTelemetry, bukan API atau library klien khusus vendor dan produk.

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

Cara membuat instrumentasi aplikasi

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

Kapan harus membuat span

Library klien Cloud Trace biasanya mempertahankan konteks rekaman aktivitas global yang menyimpan informasi tentang span saat ini, termasuk ID rekaman aktivitasnya dan apakah rekaman aktivitas diambil sampelnya. Library ini biasanya membuat span pada batas RPC. Namun, Anda mungkin perlu membuat span jika algoritma pembuatan default tidak memadai untuk kebutuhan Anda.

Span aktif saat ini dapat diakses oleh konteks rekaman aktivitas global, yang terkadang digabungkan dalam objek Pelacak. Anda dapat menambahkan informasi yang relevan dengan aplikasi menggunakan anotasi dan tag kustom ke span yang ada, atau Anda dapat membuat span turunan baru dengan anotasi dan tagnya sendiri untuk melacak perilaku aplikasi dengan tingkat perincian yang lebih baik. Karena konteks bersifat global, aplikasi multi-thread yang mengupdate konteks harus menggunakan isolasi yang sesuai.

Kapan harus memberikan kredensial autentikasi

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

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

Untuk mengetahui detailnya, buka halaman penyiapan khusus bahasa.

Cara memaksa permintaan untuk dilacak

Kecuali jika aplikasi Anda selalu mengambil sampel setiap span, secara umum, Anda tidak dapat memaksa permintaan untuk dilacak secara menyeluruh karena setiap komponen dalam permintaan menyeluruh membuat keputusan sampling-nya 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 informasi selengkapnya tentang header rekaman aktivitas, lihat Protokol untuk penyebaran konteks.

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

Layanan Google Cloud yang mencatat informasi pelacakan ke Cloud Trace biasanya menerima tanda sampling induk sebagai petunjuk; namun, sebagian besar layanan juga membatasi sampling berdasarkan kapasitas. Setiap layanan Google Cloud menentukan apakah layanan tersebut mendukung pelacakan, cara flag sampling induk digunakan, dan batas kapasitas sampling.

Cara mengorelasikan data metrik dan rekaman aktivitas

Anda dapat mengaitkan 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 informasi selengkapnya, lihat Mengaitkan metrik dan rekaman aktivitas menggunakan contoh.

Mengonfigurasi project dan platform

  1. Pastikan Cloud Trace API diaktifkan.

    Secara default, project Google Cloud 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.

    Enable the Cloud Trace API.

    Enable the API

  2. Konfigurasikan platform Anda.

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

    • Google Cloud: Saat aplikasi 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 cakupan akses default mencakup cakupan akses Cloud Trace API:

      Jika 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 cakupannya menyertakan trace.append. Perintah berikut menggambarkan penetapan flag --scopes:

      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 diberi peran agen Cloud Trace (roles/cloudtrace.agent). Untuk informasi tentang peran, lihat Mengontrol akses dengan IAM.

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

Langkah selanjutnya

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