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 OpenTelemetry SDK dan OpenTelemetry Collector.

Instrumentasi dalam contoh ini, yang mencakup penggunaan OpenTelemetry SDK dan eksportir OTLP dalam proses SDK, bersifat netral vendor. Eksportir dalam proses mengirim telemetri ke OpenTelemetry Collector, yang menerima data tersebut, lalu mengirimkannya ke your Google Cloud project. Collector berisi binding ke Google Cloud. Contoh ini menggunakan Google Cloud eksportir untuk mengirim data log dan metrik ke project Anda. Namun, contoh ini mengirim data trace ke project Anda menggunakan Telemetry API.

Anda mungkin tertarik dengan contoh lain yang menggambarkan konfigurasi yang berbeda:

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

  Sebaiknya gunakan OpenTelemetry Collector untuk mengekspor data telemetri Anda jika lingkungan Anda mendukung penggunaan collector. Jika Anda tidak dapat menggunakan collector, Anda harus menggunakan eksportir dalam proses yang mengirim data langsung ke Google Cloud project.

• Mengorelasikan metrik dan trace 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 trace dan metrik.

• 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 tertentu dari aplikasi yang berfungsi. Misalnya, contoh tidak menampilkan daftar paket yang diimpor. Namun, aplikasi lengkap tersedia di GitHub. Dari cuplikan kode, Anda dapat membuka GitHub menggunakan opsi Lainnya.

Cara kerja contoh

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 OpenTelemetry Collector dikonfigurasi untuk membaca dari aliran stdout aplikasi. Untuk rekomendasi framework, lihat Memilih pendekatan instrumentasi.

Aplikasi dibuat dan di-deploy menggunakan Docker. Anda tidak harus menggunakan Docker saat menginstrumentasi aplikasi dengan OpenTelemetry.

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

Pembahasan mendalam

Contoh menggunakan OpenTelemetry Collector sebagai sidecar untuk menerima dan memperkaya telemetri aplikasi, yang kemudian dikirim ke Google Cloud project Anda menggunakan Google Cloud eksportir. Eksportir mengonversi telemetri ke dalam format yang kompatibel dengan Cloud Trace API, Cloud Monitoring API, atau Cloud Logging API. Selanjutnya, eksportir akan mengirim data yang diubah ke Google Cloud project Anda dengan mengeluarkan perintah API.

Contoh menunjukkan cara melakukan hal berikut:

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

   Jika meninjau contoh, 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 trace. Untuk Go, server dan klien HTTP juga diperbarui.

2. Mengonfigurasi 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 dapat mengindeks kolom tertentu dalam payload log.

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

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

3. Mengonfigurasi file Docker. Semua contoh 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 OpenTelemetry Collector ditetapkan oleh variabel lingkungan OTEL_EXPORTER_OTLP_ENDPOINT, yang ditentukan dalam layanan app.

   • otel-collector-config.yaml: Mengonfigurasi OpenTelemetry Collector. Collector ini menentukan penerima, eksportir, pemroses, dan pipeline.

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

     Bagian exporters menjelaskan cara mengekspor data yang dikumpulkan ke a Google Cloud project. Untuk data log dan metrik, Google Cloud eksportir digunakan. Eksportir ini mengonversi telemetri ke dalam format yang kompatibel dengan API yang sesuai , lalu mengirim data yang diubah ke Google Cloud project Anda dengan mengeluarkan perintah API. Sebaliknya, data trace dikirim ke project Anda menggunakan Telemetry API, yang mendukung OTLP.

   • docker-compose.creds.yaml: File ini secara opsional memasang file Google Cloud kredensial di container otelcol. File ini diperlukan saat contoh dijalankan di mesin 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 trace, minta administrator Anda 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 Google Cloud resource, atau di lingkungan pengembangan lokal, izin sebelumnya sudah cukup untuk menulis data log, metrik, dan trace. Untuk aplikasi produksi, akun layanan biasanya memberikan kredensial yang diperlukan.

• Untuk mendapatkan izin yang Anda perlukan untuk melihat data log, metrik, dan trace, minta administrator Anda 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

Aktifkan Cloud Logging, Cloud Monitoring, Cloud Trace, dan Telemetry API:

Peran yang diperlukan untuk mengaktifkan API

Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.

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

Langkah berikutnya

Untuk mempelajari collector lebih lanjut, lihat OpenTelemetry Collector Buatan Google.

Pelajari contoh yang menggunakan ekspor berbasis collector.

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