Instrumen untuk Cloud Trace

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

Dokumen ini memberikan ringkasan tentang 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

Lengkapi 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 agentic Anda, beberapa framework dapat mengumpulkan perintah dan respons Anda atau meneruskan konteks yang memungkinkan pelacakan beberapa panggilan server MCP Google Cloud jarak jauh.

Untuk melengkapi aplikasi Anda, sebaiknya gunakan framework instrumentasi open source yang netral terhadap vendor, seperti OpenTelemetry, bukan API atau library klien khusus vendor dan produk. Untuk mengetahui informasi tentang framework ini, lihat Kemampuan observasi untuk developer aplikasi dan Memilih pendekatan instrumentasi.

Cara melengkapi aplikasi

Ada beberapa pendekatan yang dapat Anda gunakan untuk melengkapi aplikasi:

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

  • Gunakan OpenTelemetry dan konfigurasi aplikasi Anda dengan pengekspor OTLP yang mengirimkan data trace ke project Google Cloud 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.

  • Memanggil Telemetry API atau Cloud Trace API secara langsung.

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

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

Contoh instrumentasi

Contoh instrumentasi yang kami sediakan menggunakan OpenTelemetry:

Membuat span kustom

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

Anda juga dapat menambahkan informasi yang relevan ke aplikasi dengan menambahkan anotasi dan tag kustom ke span yang ada, atau Anda dapat membuat span turunan baru dengan anotasi dan tag-nya sendiri untuk melacak perilaku aplikasi dengan perincian yang lebih mendetail.

Library biasanya mempertahankan konteks trace global yang menyimpan informasi tentang span saat ini, termasuk ID trace dan status sampling-nya. Aplikasi dapat mengakses span saat ini melalui konteks trace global. Karena konteksnya bersifat global, pastikan aplikasi multi-thread menyebarkan konteks di seluruh thread untuk mempertahankan data trace yang akurat.

Memaksa pengambilan sampel trace

Anda tidak dapat memaksa span untuk diambil sampelnya karena setiap komponen dalam jalur permintaan membuat keputusan pengambilan sampel yang independen. Namun, Anda dapat memengaruhi komponen downstream dengan menetapkan flag sampled di header trace ke true. Setelan ini adalah petunjuk bagi komponen turunan untuk mengambil sampel permintaan. Untuk mengetahui informasi selengkapnya tentang header trace, 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 bahwa flag sampling induk dihormati.

  • LayananGoogle Cloud : Setiap layanan menentukan dukungan pelacakannya sendiri. Secara umum, layanan menerima flag sampling induk sebagai petunjuk sekaligus menerapkan batas frekuensi samplingnya sendiri.

Menghubungkan metrik dan trace dengan contoh

Anda dapat menghubungkan data metrik dengan trace menggunakan contoh. Contoh adalah permintaan atau span sampel representatif yang terkait dengan pengukuran metrik. Misalnya, contoh dapat berisi link ke trace, yang memungkinkan Anda menghubungkan data metrik dan trace. Untuk contoh berbasis OpenTelemetry, lihat Menghubungkan metrik dan trace menggunakan contoh.

Anda mungkin melihat contoh yang dihasilkan sistem di diagram dasbor yang menampilkan hasil kueri SQL untuk data trace. Contoh ini menautkan hasil kueri tertentu langsung ke trace. Untuk mengetahui informasi selengkapnya, lihat Membuat dan menampilkan contoh trace.

Mengonfigurasi project dan platform

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 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 API dan Cloud Trace API, jika belum diaktifkan.

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 Service Usage Admin (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

Aktifkan API

Memberikan peran IAM

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

  • Untuk mendapatkan izin yang diperlukan guna melihat data trace menggunakan konsol Google Cloud , minta administrator 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 untuk memberi Anda peran IAM Cloud Trace Agent (roles/cloudtrace.agent) di project Anda.

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

Autentikasikan

Bagian ini menjelaskan cara melakukan autentikasi saat aplikasi Anda berjalan di Google Cloud dan saat 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 project ID meskipun dihosting di Google Cloud.

Pastikan 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 mencakup trace.append. Perintah berikut mengilustrasikan penetapan 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.

Library klienGoogle 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 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 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 berikutnya