Ringkasan contoh instrumentasi berbasis pengumpul

Dokumen ini menjelaskan struktur contoh instrumentasi yang disediakan untuk bahasa Go, Java, Node.js, dan Python. Contoh ini memberikan panduan tentang cara menginstrumentasi aplikasi untuk menggunakan SDK OpenTelemetry dan pengumpul OpenTelemetry.

Pengukuran dalam contoh ini, yang mencakup penggunaan OpenTelemetry SDK dan pengekspor OTLP dalam proses SDK, bersifat netral terhadap vendor. Pengekspor dalam proses mengirim telemetri ke pengumpul OpenTelemetry, yang menerima data tersebut, lalu mengirimkannya ke project Google Cloud Anda. Pengumpul berisi binding ke Google Cloud. Contoh ini menggunakan eksportir Google Cloud untuk mengirim data log dan metrik ke project Anda. Namun, mereka mengirim data rekaman aktivitas ke project Anda menggunakan Telemetry API.

Anda mungkin tertarik dengan contoh lain yang menggambarkan berbagai konfigurasi:

• Bermigrasi dari eksportir Trace ke endpoint OTLP menjelaskan cara menggunakan instrumentasi dalam proses untuk mengirim data trace langsung ke project Google Cloud Anda.

  Sebaiknya gunakan pengumpul OpenTelemetry untuk mengekspor data telemetri saat lingkungan Anda mendukung penggunaan pengumpul. Jika Anda tidak dapat menggunakan pengumpul, Anda harus menggunakan pengekspor dalam proses yang mengirimkan data secara langsung ke project Google Cloud Anda.

• Mengorelasikan metrik dan rekaman aktivitas menggunakan contoh menjelaskan cara mengonfigurasi aplikasi Go untuk membuat contoh. Contoh adalah contoh titik data yang dilampirkan ke titik data metrik. Anda dapat menggunakan contoh untuk mengorelasikan data metrik dan rekaman aktivitas.

• Menggunakan Agen Operasional dan OpenTelemetry Protocol (OTLP) menjelaskan cara mengonfigurasi Agen Operasional dan penerima OTLP untuk mengumpulkan metrik dan trace dari aplikasi.

Catatan: Contoh hanya menampilkan bagian aplikasi yang berfungsi yang dipilih. Misalnya, contoh tidak menampilkan daftar paket yang diimpor. Namun, aplikasi lengkapnya tersedia di GitHub. Dari cuplikan kode, Anda dapat membuka GitHub menggunakan opsi Lainnya.

Cara kerja sampel

Contoh untuk Go, Java, Node.js, dan Python menggunakan protokol OpenTelemetry untuk mengumpulkan data trace dan metrik. Contoh mengonfigurasi framework logging untuk menulis log terstruktur dan pengumpul OpenTelemetry dikonfigurasi untuk membaca dari aliran stdout aplikasi. Untuk rekomendasi framework, lihat Memilih pendekatan instrumentasi.

Aplikasi dibangun dan di-deploy menggunakan Docker. Anda tidak perlu menggunakan Docker saat menginstrumentasi aplikasi dengan OpenTelemetry.

Anda dapat menjalankan contoh di Cloud Shell, di resource Google Cloud, atau di lingkungan pengembangan lokal.

Pembahasan mendalam

Contoh ini menggunakan OpenTelemetry Collector sebagai file bantuan untuk menerima dan memperkaya telemetri aplikasi, yang kemudian dikirim ke projectGoogle Cloud Anda menggunakan pengeksporGoogle Cloud . Exporter mengonversi telemetri ke dalam format yang kompatibel dengan Cloud Trace API, Cloud Monitoring API, atau Cloud Logging API. Selanjutnya, mereka mengirimkan data yang telah diubah ke project Google Cloud Anda dengan mengeluarkan perintah API.

Contoh menunjukkan cara melakukan hal berikut:

1. Konfigurasi OpenTelemetry untuk mengumpulkan metrik dan trace menggunakan OpenTelemetry Collector.

   Jika meninjau sampel, Anda akan melihat bahwa kompleksitas langkah ini bergantung pada bahasa. Misalnya, untuk Go, langkah ini mengonfigurasi fungsi main untuk memanggil fungsi yang mengonfigurasi pengumpulan metrik dan rekaman aktivitas. Untuk Go, server dan klien HTTP juga diperbarui.

2. Konfigurasi framework logging untuk menulis log terstruktur.

   Sebaiknya aplikasi Anda menulis log terstruktur, yang akan menghasilkan payload log yang diformat sebagai objek JSON. Untuk log ini, Anda dapat membuat kueri yang menelusuri jalur JSON tertentu dan mengindeks kolom tertentu dalam payload log.

   Beberapa layanan, seperti Google Kubernetes Engine, memiliki agen bawaan yang meng-scrape log terstruktur dan mengirimkan log tersebut ke project Anda. Google Cloud Layanan lainnya, seperti Compute Engine, mengharuskan Anda menginstal agen, yang meng-scrape dan mengirim log Anda. Jika Anda ingin mempelajari agen yang Anda instal, lihat Ringkasan Agen Operasional.

   Anda tidak perlu menginstal agen apa pun untuk menggunakan contoh ini.

3. Konfigurasi file Docker. Semua sampel berisi file yaml berikut:

   • docker-compose.yaml: Mengonfigurasi layanan untuk aplikasi, OpenTelemetry Collector, dan generator beban. Misalnya, layanan untuk OpenTelemetry Collector, otelcol, menentukan image, volume, dan variabel lingkungan. Endpoint untuk pengumpul OpenTelemetry ditetapkan oleh variabel lingkungan OTEL_EXPORTER_OTLP_ENDPOINT, yang ditentukan dalam layanan app.

   • otel-collector-config.yaml: Mengonfigurasi pengumpul OpenTelemetry. Pengumpul ini menentukan penerima, pengekspor, pemroses, dan pipeline.

     Layanan telemetry menentukan pipeline untuk data log, metrik, dan rekaman aktivitas. Setiap entri pipeline menentukan penerima, pemroses, dan pengekspor. Penerima yang sama, otlp, digunakan untuk metrik dan rekaman aktivitas.

     Bagian exporters menjelaskan cara data yang dikumpulkan diekspor ke project Google Cloud . Untuk data log dan metrik, eksportirGoogle Cloud digunakan. Exporter ini mengonversi telemetri ke dalam format yang kompatibel dengan API terkait lalu mengirimkan data yang telah diubah ke project Google Cloud Anda dengan mengeluarkan perintah API. Sebaliknya, data rekaman aktivitas dikirim ke project Anda menggunakan Telemetry API, yang mendukung OTLP.

   • docker-compose.creds.yaml: File ini secara opsional memasang file kredensialGoogle Cloud di penampung otelcol. File ini diperlukan saat sampel dijalankan di komputer lokal tempat Kredensial Default Aplikasi (ADC) hanya tersedia sebagai file.

Izin yang diperlukan

• Untuk mendapatkan izin yang Anda perlukan agar aplikasi contoh dapat menulis data log, metrik, dan rekaman aktivitas, minta administrator untuk memberi Anda peran IAM berikut di project Anda:

  • Logs Writer (roles/logging.logWriter)
  • Monitoring Metric Writer (roles/monitoring.metricWriter)
  • Cloud Telemetry Traces Writer (roles/telemetry.tracesWriter)

  Jika Anda menjalankan contoh di Cloud Shell, di resource, atau di lingkungan pengembangan lokal, izin sebelumnya sudah cukup untuk menulis data log, metrik, dan rekaman aktivitas. Google Cloud Untuk aplikasi produksi, akun layanan biasanya memberikan kredensial yang diperlukan.

• Untuk mendapatkan izin yang Anda perlukan untuk melihat data log, metrik, dan rekaman aktivitas, minta administrator untuk memberi Anda peran IAM berikut di project Anda:

  • Logs Viewer (roles/logging.viewer)
  • Monitoring Viewer (roles/monitoring.viewer)
  • Cloud Trace User (roles/cloudtrace.user)

  Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

  Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

API yang diperlukan

Enable the Cloud Logging, Cloud Monitoring, Cloud Trace, and Telemetry APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com telemetry.googleapis.com

Langkah berikutnya

Untuk mempelajari lebih lanjut pengumpul, lihat Pengumpul OpenTelemetry Buatan Google.

Pelajari contoh yang menggunakan ekspor berbasis pengumpul.

• Contoh Go.
• Contoh Java.
• Contoh Node.js.
• Contoh Python.