Halaman ini menjelaskan cara mengaktifkan trace sisi klien dengan OpenTelemetry saat Anda menggunakan library klien Cloud Storage untuk berinteraksi dengan Cloud Storage. Anda dapat mengumpulkan dan melihat data trace menggunakan library klien Cloud Storage yang didukung berikut:
Ringkasan
Dengan mengaktifkan trace di library klien Cloud Storage, Anda dapat memantau performa, menemukan masalah latensi, dan melakukan proses debug dengan cepat untuk permintaan Cloud Storage. Trace memungkinkan Anda melihat urutan permintaan yang telah selesai, sehingga memberikan tampilan mendetail tentang cara permintaan diterima, dikelola, dan direspons oleh Cloud Storage. Satu trace terdiri dari beberapa span, yang merupakan data mendetail dan diberi stempel waktu dari setiap fungsi atau operasi yang dilakukan aplikasi Anda selama permintaan Cloud Storage.
Manfaat
Mengumpulkan dan menyebarkan data trace memberikan manfaat berikut untuk aplikasi Anda:
Visibilitas performa yang ditingkatkan: karena data trace dibuat hampir real-time saat Cloud Storage menyelesaikan setiap permintaan yang Anda buat, Anda dapat dengan cepat mengidentifikasi bottleneck dalam performa dan mendeteksi masalah latensi.
Penanganan error: Anda dapat menentukan tempat timbulnya masalah, mempercepat analisis akar masalah, dan mengurangi periode nonaktif menggunakan informasi tentang setiap permintaan Cloud Storage yang disediakan dalam trace.
Cara kerja trace sisi klien
Bagian berikut memberikan gambaran mendetail tentang cara kerja pengumpulan trace.
Cara kerja pengumpulan trace dengan OpenTelemetry
Library klien Cloud Storage mendukung pengumpulan data trace menggunakan OpenTelemetry SDK untuk menyiapkan komponen berikut yang diperlukan untuk mengumpulkan dan menyebarkan data trace:
Penyedia trace: digunakan oleh library klien Cloud Storage, penyedia trace bertanggung jawab untuk membuat dan mengelola sistem pelacakan, termasuk membuat dan mengelola trace dan span di aplikasi Anda.
Pengekspor trace: digunakan oleh OpenTelemetry SDK, pengekspor trace bertanggung jawab untuk mengirim data trace ke platform kemampuan observasi backend seperti Cloud Trace, tempat Anda dapat menganalisis dan memvisualisasikan data trace. Untuk mempelajari lebih lanjut pengekspor trace, lihat Cara kerja pengekspor trace.
Cara kerja pengekspor trace
Mengonfigurasi trace menggunakan SDK OpenTelemetry mencakup pemilihan backend kemampuan observasi untuk mengekspor data ke tempat data tersebut dianalisis, disimpan, dan divisualisasikan. Meskipun Anda dapat mengekspor data trace ke backend kemampuan observasi pilihan Anda, sebaiknya gunakan Cloud Trace, yang dapat diakses menggunakan konsol Google Cloud dan menyediakan integrasi dengan layanan Google Cloud lainnya.
Setelah penyedia trace dan pengekspor trace dikonfigurasi dan diaktifkan, Anda dapat melihat data trace hampir secara real-time karena trace dan span dibuat untuk setiap permintaan Cloud Storage.
Dengan menggunakan Cloud Trace Explorer di konsolGoogle Cloud , Anda dapat melihat setiap trace yang berisi hal berikut:
Tampilan tingkat tinggi dari permintaan Cloud Storage secara menyeluruh.
Beberapa span, dengan setiap span mencatat satu operasi yang diberi stempel waktu dalam permintaan Cloud Storage yang dilakukan.
Untuk membaca lebih lanjut tentang trace dan span, lihat dokumentasi OpenTelemetry tentang trace dan span.
Harga
Data rekaman aktivitas dapat dikenai biaya. Biaya didasarkan pada jumlah span trace yang diserap dan dipindai oleh Cloud Trace. Untuk mempelajari lebih lanjut span trace yang dapat dikenai biaya dan contoh harga, lihat Biaya Cloud Trace.
Sebelum memulai
Sebelum dapat mengumpulkan trace untuk penggunaan Cloud Storage API, Anda harus menyelesaikan langkah-langkah berikut:
-
Aktifkan 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 Cloud Storage API.
Peran yang diperlukan
Untuk mendapatkan izin yang
diperlukan guna menulis trace ke Cloud Trace,
minta administrator untuk memberi Anda
peran IAM Cloud Trace Agent (roles/cloudtrace.agent) pada project yang digunakan oleh klien.
Peran yang telah ditetapkan ini berisi izin cloudtrace.traces.patch, yang diperlukan untuk menulis trace ke Cloud Trace.
Anda mungkin juga bisa mendapatkan izin ini dengan peran bawaan, atau Anda dapat membuat peran khusus untuk memberikan izin tertentu. Untuk mengetahui petunjuk cara memberikan peran pada project, lihat Memberikan atau mencabut peran. Untuk mengetahui informasi selengkapnya tentang peran Cloud Trace Agent, lihat dokumentasi Identity and Access Management (IAM).
Mengonfigurasi pelacakan untuk aplikasi Anda
Gunakan petunjuk berikut untuk mengonfigurasi pelacakan dan mulai mengumpulkan data trace menggunakan library klien Cloud Storage:
C++
Instal versi berikut:
Library klien C++ versi v2.16.0 atau yang lebih baru
C++ versi 14 atau yang lebih baru
Untuk mengaktifkan instrumentasi pelacakan OpenTelemetry di library klien C++, perbarui konfigurasi sistem build untuk CMake atau Bazel.
Buat instance klien Cloud Storage dengan trace OpenTelemetry diaktifkan.
Java
Instal versi library klien Java Cloud Storage berikut:
com.google.cloud:google-cloud-storage:2.47.0atau yang lebih barucom.google.cloud:libraries-bom:26.53.0atau yang lebih baru
Instal pengekspor Cloud Trace untuk OpenTelemetry. Anda juga dapat menggunakan pengekspor pilihan Anda.
Instal propagator Cloud Trace.
Buat instance klien Cloud Storage dengan trace OpenTelemetry diaktifkan.
Python
Instal library klien Python Cloud Storage:
pip install google-cloud-storage[tracing]>=2.18.0
Instal pengekspor dan propagator Cloud Trace. Anda juga dapat menggunakan pengekspor apa pun pilihan Anda.
pip install opentelemetry-exporter-gcp-trace opentelemetry-propagator-gcp
Instal instrumentasi permintaan OpenTelemetry untuk melacak permintaan HTTP yang mendasarinya.
pip install opentelemetry-instrumentation-requests
Tetapkan variabel lingkungan untuk mengaktifkan pelacakan secara selektif bagi klien penyimpanan Python:
export ENABLE_GCS_PYTHON_CLIENT_OTEL_TRACES=True
Konfigurasikan pengekspor trace dan penyedia trace.
Rust
Tambahkan library klien Rust Cloud Storage serta crate
tracingdan OpenTelemetry ke file manifesCargo.tomlAnda:cargo add google-cloud-storage opentelemetry opentelemetry_sdk opentelemetry-otlp tracing tracing-opentelemetry tracing-subscriber
Konfigurasikan struct
SdkTracerProviderOpenTelemetry dengan pengekspor OTLP (misalnya, mengirim span ke OpenTelemetry Collector atau Telemetry API), daftarkan pelanggantracing, dan bangun klienStoragedengan metode.with_tracing()diaktifkan:
Melihat trace Anda
Gunakan Cloud Trace Explorer untuk melihat data trace Anda di konsol Google Cloud :
-
Di konsol Google Cloud , buka halaman
Trace explorer:
Anda juga dapat menemukan halaman ini menggunakan kotak penelusuran.
Di halaman Trace explorer, klik trace tertentu dalam diagram sebar untuk melihat detail trace.
Panel Trace details menampilkan tabel span trace.
Opsional: klik baris span untuk melihat informasi mendetail tentang span tertentu, seperti informasi berikut:
Atribut: key-value pair yang memberikan informasi tambahan tentang span.
Logs & events: entri log yang terkait dengan span.
Stack trace: stack trace yang terkait dengan span.
Metadata & Links: link ke layanan Google Cloud lain yang terkait dengan span.
Untuk mengetahui informasi selengkapnya tentang cara menggunakan Cloud Trace Explorer, lihat Menemukan dan menjelajahi trace.