Dokumen ini menjelaskan alasan kami merekomendasikan agar Anda mengirim data rekaman aktivitas ke project Google Cloud menggunakan Telemetry (OTLP) API, yang menerapkan OpenTelemetry Line Protocol. Panduan ini juga memberikan petunjuk tentang cara menginstrumentasi aplikasi dan tempat Anda dapat melihat data rekaman aktivitas. Anda dapat menggunakan Telemetry API saat menginstrumentasi aplikasi menggunakan salah satu SDK OpenTelemetry atau saat menggunakan OpenTelemetry Collector.
Kami merekomendasikan Telemetry API karena alasan berikut:
API ini memberikan kompatibilitas dengan ekosistem OpenTelemetry open source dan batasnya sering kali lebih besar daripada batas Cloud Trace API, yang merupakan API Google Cloud eksklusif
Data rekaman aktivitas Anda disimpan dalam format yang umumnya konsisten dengan file proto yang ditentukan oleh OpenTelemetry Line Protocol. Beberapa kolom mungkin dikonversi dari jenis data khusus OpenTelemetry ke jenis data JSON sebelum penyimpanan. Untuk mempelajari format penyimpanan lebih lanjut, lihat Skema untuk data rekaman aktivitas.
Pengukuran Anda tidak bergantung pada eksportir khusus Google Cloud.
Beberapa fitur, seperti Pemantauan Aplikasi, mengandalkan informasi yang hanya tersedia saat Anda mengirim data rekaman aktivitas ke Telemetry API.
OpenTelemetry adalah project open source yang didukung Google Cloud-dengan staf teknisi untuk memastikan dukungan penyerapan dan visualisasi telemetri Anda. Google Cloud
Google Cloud Observability memverifikasi bahwa Cloud Trace API diaktifkan di project Anda sebelum menyimpan data aktivitas. Google Cloud Artinya, jika Anda menonaktifkan Cloud Trace API, Google Cloud Observability akan menghapus data trace yang Anda kirim ke Telemetry API.
Praktik terbaik
Saat menginstrumentasi aplikasi untuk mengirim data rekaman aktivitas ke projectGoogle Cloud , sebaiknya gunakan eksportir yang menulis data berformat OTLP ke Pengumpul, yang kemudian mengirimkan data rekaman aktivitas Anda ke Telemetry API. Di pengumpul Anda, tentukan hanya URL root:
exporters:
otlphttp:
encoding: proto
endpoint: https://telemetry.googleapis.com
OpenTelemetry mendeteksi jenis data dan otomatis menambahkan /v1/traces,
/v1/metrics, atau /v1/logs sebagaimana mestinya. Untuk mengetahui informasi selengkapnya, lihat
Permintaan OTLP/HTTP.
Untuk contoh yang mengekspor data metrik atau rekaman aktivitas ke Telemetry API, lihat dokumen berikut:
Jika tidak dapat menggunakan pengumpul, Anda dapat menggunakan library OpenTelemetry yang berisi eksportir OTLP dalam proses untuk mengirim telemetri ke Telemetry API. Untuk mempelajari cara mengekspor data rekaman aktivitas secara langsung, lihat Pengekspor Cloud Trace ke endpoint OTLP.
Autentikasi
Anda harus mengonfigurasi pengekspor dengan kredensial yang diperlukan untuk mengirim
data ke project Google Cloud Anda. Misalnya, saat menggunakan pengumpul, biasanya
Anda menggunakan ekstensi googleclientauth untuk mengautentikasi dengan kredensial
Google.
Untuk melihat contoh autentikasi saat menggunakan ekspor langsung data rekaman aktivitas, lihat Mengonfigurasi autentikasi. Contoh ini menggambarkan cara mengonfigurasi eksportir dengan Google Cloud Kredensial Default Aplikasi (ADC) dan menambahkan Google Auth Library khusus bahasa ke aplikasi Anda.
Untuk mengirim data telemetri ke project Google Cloud menggunakan Telemetry API, Anda juga harus melakukan hal berikut:
- Konfigurasi project kuota. Untuk mempelajari lebih lanjut, lihat Menetapkan project kuota.
- Berikan peran
Service Usage Consumer (
roles/serviceusage.serviceUsageConsumer) kepada pengguna atau akun layanan yang digunakan aplikasi di project kuota tersebut. Berikan peran berikut kepada pengguna atau akun layanan yang digunakan aplikasi di project Anda:
- Logs Writer (
roles/logging.logWriter) - Monitoring Metric Writer (
roles/monitoring.metricWriter) - Cloud Telemetry Traces Writer (
roles/telemetry.tracesWriter)
- Logs Writer (
Cloud Trace dan residensi data
Jika Anda menggunakan Assured Workloads karena Anda memiliki persyaratan residensi data atau Tingkat Dampak 4 (IL4), jangan gunakan Telemetry API untuk mengirim rentang aktivitas ke project Anda.
Tempat melihat data yang diserap
Anda dapat melihat data rekaman aktivitas menggunakan halaman Trace Explorer dan Observability Analytics. Untuk mengetahui informasi, lihat referensi berikut: