Ringkasan Telemetry (OTLP) API

Dokumen ini menjelaskan Telemetry (OTLP) API, yang mengimplementasikan OpenTelemetry OTLP Protocol. API ini dirancang untuk digunakan dengan aplikasi yang diinstrumentasi menggunakan salah satu SDK OpenTelemetry atau yang menggunakan OpenTelemetry Collector.

OpenTelemetry adalah project open source yang didukung Google Cloud-dengan staf engineer yang memastikan dukungan untuk penyerapan dan visualisasi telemetri Anda. Google Cloud

Data rekaman aktivitas dan Telemetry API

Bagian ini memberikan informasi tentang Telemetry API dan rekaman aktivitas.

Alasan Anda harus menggunakan Telemetry API

Saat Anda menggunakan Telemetry API, data Anda disimpan dalam format yang umumnya konsisten dengan file proto yang ditentukan oleh OpenTelemetry OTLP Protocol. Namun, kolom dapat dikonversi dari jenis data khusus OpenTelemetry menjadi jenis data JSON sebelum penyimpanan. Selain itu, batas untuk Telemetry API berlaku. Batas ini sering kali lebih besar daripada batas untuk Cloud Trace API. Terakhir, instrumentasi Anda tidak bergantung pada eksportir khusus Google Cloud.

Untuk mempelajari format penyimpanan lebih lanjut, lihat Skema untuk data rekaman aktivitas.

Kapan harus menggunakan Telemetry API

Sebaiknya kirimkan data rekaman aktivitas ke Google Cloud project Anda menggunakan Telemetry API. API ini memberikan kompatibilitas dengan ekosistem OpenTelemetry open source dan batasnya sering kali lebih besar daripada batas Cloud Trace API, yang merupakan APIGoogle Cloud berpemilik. Beberapa fitur, seperti Pemantauan Aplikasi, mengandalkan informasi yang hanya tersedia saat data rekaman aktivitas dikirim ke Telemetry API.

Saat menginstrumentasi aplikasi untuk mengirim data rekaman aktivitas ke projectGoogle Cloud , sebaiknya lakukan salah satu hal berikut:

• Gunakan eksportir yang menulis OTLP ke Collector, yang kemudian mengirim data rekaman aktivitas Anda ke Telemetry API.
• Gunakan eksportir OTLP dalam proses yang didukung oleh library OpenTelemetry yang mengirimkan telemetri ke Telemetry API. Tidak ada pengumpul dengan konfigurasi ini.

Untuk mengetahui informasi tentang cara menggunakan Telemetry API, lihat Bermigrasi dari eksportir Cloud Trace ke endpoint OTLP.

Autentikasi

Pengekspor harus diberi otorisasi untuk mengirim data ke project Google Cloud Anda. Misalnya, Anda dapat mengonfigurasi eksportir dengan Google Cloud Kredensial Default Aplikasi (ADC) dengan menambahkan Google Auth Library khusus bahasa ke aplikasi Anda. Untuk mengetahui informasi dan contoh kode selengkapnya, lihat Mengonfigurasi autentikasi.

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.

Data metrik dan Telemetry API

Bagian ini menjelaskan cara Cloud Monitoring menangani metrik yang di-ingest dengan menggunakan eksportir otlphttp dan OpenTelemetry Collector atau oleh aplikasi yang diinstrumentasi menggunakan salah satu SDK OpenTelemetry.

Metrik OTLP di Cloud Monitoring

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Saat metrik dimasukkan ke Cloud Monitoring menggunakan pengekspor otlphttp dan OpenTelemetry Collector atau dikirim langsung menggunakan OpenTelemetry SDK, metrik OTLP dipetakan ke struktur metrik Cloud Monitoring. Bagian ini menjelaskan hal berikut:

• Pemetaan antara resource OTLP dan resource yang dipantau Cloud Monitoring.
• Pemetaan antara metrik OTLP dan metrik Cloud Monitoring.

Pemetaan resource yang dipantau

Semua titik metrik ditulis sebagaimana adanya untuk Google Cloud Managed Service for Prometheus, dengan menggunakan pemetaan Prometheus.

Pemetaan Prometheus

Metrik Prometheus memerlukan penggunaan jenis resource yang dipantau prometheus_target.

Label berikut pada jenis resource prometheus_target digunakan untuk membuat skema dan menyimpan data secara efisien dalam Monarch. Makin presisi Anda menentukan nilai untuk atribut ini, makin baik kemampuan kueri dan skalabilitas Anda.

Sebaiknya tulis sejelas mungkin saat menetapkan nilai untuk label ini, meskipun kami telah menerapkan logika penggantian untuk digunakan jika tidak ada nilai eksplisit.

Tabel berikut menunjukkan sumber nilai untuk label, berdasarkan urutan prioritas:

Label prometheus-target	Nilai yang digunakan (dalam urutan prioritas)
location (diperlukan)	Atribut location Atribut cloud.availability_zone Atribut cloud.region
cluster	Atribut cluster Atribut k8s.cluster.name __gce__, jika atribut cloud.platform adalah gcp_compute_engine __run__, jika atribut cloud.platform adalah gcp_cloud_run String kosong
namespace	Atribut namespace Atribut k8s.namespace.name Atribut service.namespace String kosong
job	Atribut job "service.namespace" + "/" + atribut service.namespace Atribut service.name Atribut service.name, jika bukan unknown_service:foo Atribut faas.name Atribut k8s.deployment.name Atribut k8s.statefulset.name Atribut k8s.job.name Atribut k8s.cronjob.name Atribut service.name, jika unknown_service:foo String kosong
instance Tolak titik jika kosong	Atribut instance Atribut service.instance.id Atribut faas.instance Atribut k8s.pod.name:k8s.container.name Atribut k8s.pod.name, jika tidak ada nama penampung Atribut host.id

Pemetaan metrik

Metrik dikonversi ke format deret waktu Prometheus. Nama metrik tidak boleh memiliki domain atau harus memiliki domain prometheus.googleapis.com. Setelah konversi, nama metrik akan menyertakan awalan prometheus.googleapis.com dan sufiks tambahan, berdasarkan jenis titik OTLP. Metrik Cloud Monitoring yang dihasilkan memiliki struktur berikut:

prometheus.googleapis.com/{metric_name}/{suffix}

Selain itu, untuk setiap resource OpenTelemetry yang unik, konversi menambahkan metrik target_info yang berisi semua atribut resource kecuali service.name, service.instance.id, dan service.namespace.

Semua metrik OTLP INT64 diterjemahkan ke jenis nilai DOUBLE di Cloud Monitoring, meskipun pengumpul menentukan jenis nilai sebagai INT64. Perubahan ini dilakukan karena setelah deret waktu berada di Monarch, Anda tidak dapat mengubah jenis nilai. Konsekuensi paling umum dari mendukung nilai INT64 adalah Anda akan mengalami konflik yang hanya dapat diselesaikan dengan menghapus metrik.

Catatan: Kami memperkirakan akan ada kemungkinan bentrokan jenis nilai, khususnya jika Anda sebelumnya telah mengirimkan metrik INT64 target_info. Jika Anda mengalami konflik, solusi jangka panjang terbaik untuk masalah ini adalah menghapus deskriptor metrik untuk metrik INT64 target_info. Untuk menghapus deskriptor ini dari cakupan metrik Anda, gunakan skrip Golang ini.

Pemetaan metrik Prometheus

Jenis metrik dipetakan sebagai berikut:

• Pengukur OTLP dipetakan ke pengukur Cloud Monitoring.
• OTLP Sum dipetakan sebagai berikut:
  • Untuk pengukur Cloud Monitoring saat is_monotonic disetel ke false.
  • Ke Cloud Monitoring kumulatif saat aggregation_temporality disetel ke AGGREGATION_TEMPORALITY_CUMULATIVE.
  • Untuk delta Cloud Monitoring saat aggregation_temporality disetel ke AGGREGATION_TEMPORALITY_DELTA.
• Histogram OTLP dipetakan ke distribusi Cloud Monitoring dengan jenis metrik kumulatif atau delta, bergantung pada nilai aggregation_temporality.
• Metrik Ringkasan OTLP diperluas menjadi deret waktu individual untuk setiap komponen: count, sum, dan setiap quantile.
  • Nama untuk metrik jumlah dan jumlah total diberi akhiran _count atau _sum, dan ditulis sebagai metrik kumulatif Cloud Monitoring dengan jenis DOUBLE.
  • Setiap kuantil menjadi deret waktu pengukur sendiri dari jenis DOUBLE, dengan label quantile.

Tabel berikut merangkum pemetaan metrik:

Jenis titik OTLP	Memantau jenis metrik	Pemantauan jenis nilai	Akhiran	Catatan
GAUGE	GAUGE	DOUBLE	/gauge
GAUGE (metric.metadata["prometheus.type"]="unknown")	GAUGE	DOUBLE	/unknown	Prometheus Unknowns dibagi menjadi penghitung dan pengukur oleh OpenTelemetry Collector.
SUM (monoton, CUMULATIVE)	KUMULATIF	DOUBLE	/counter
SUM (monotonic, CUMULATIVE, metric.metadata["prometheus.type"]="unknown")	KUMULATIF	DOUBLE	/unknown:counter	Prometheus Unknowns dibagi menjadi penghitung dan pengukur oleh OpenTelemetry Collector.
SUM (monotonik, DELTA)	DELTA	DOUBLE	/delta
SUM (non-monotonik, KUMULATIF)	GAUGE	DOUBLE	/gauge
HISTOGRAM (KUMULATIF)	KUMULATIF	DISTRIBUSI dengan bucket eksplisit	/histogram
HISTOGRAM EKSPONENSIAL (KUMULATIF)	KUMULATIF	DISTRIBUSI dengan bucket eksponensial	/histogram
HISTOGRAM (DELTA)	DELTA	DISTRIBUSI dengan bucket eksplisit	/histogram:delta
HISTOGRAM EKSPONENSIAL (DELTA)	DELTA	DISTRIBUSI dengan bucket eksponensial	/histogram:delta
RINGKASAN (sum, count, quantile)	CUMULATIVE CUMULATIVE GAUGE	DOUBLE DOUBLE DOUBLE	_sum/summary:counter _count/summary /summary	Titik data ringkasan ditulis sebagai beberapa deret waktu, satu untuk jumlah, jumlah, dan setiap kuantil yang dihitung. Metrik kuantil juga dihasilkan dengan label quantile.

Perbedaan antara eksportir googlemanagedprometheus dan Telemetry API

Telemetry API (telemetry.googleapis.com) menangani metrik secara berbeda dari pengekspor googlemanagedprometheus:

• Telemetry API mengizinkan karakter titik (.) dan garis miring (/) dalam nama metrik. Eksporter googlemanagedprometheus mengonversi semua kemunculan karakter ini menjadi karakter garis bawah (_). Misalnya, metrik OTLP yang disebut prometheus.googleapis.com/foo.bar/gauge diekspor secara verbatim oleh eksportir OTLP, tetapi diekspor sebagai prometheus.googleapis.com/foo_bar/gauge oleh eksportir googlemanagedprometheus.

  Saat metrik di-ingest, Cloud Monitoring membuat deskriptor metrik berdasarkan nama. Perbedaan cara penanganan karakter titik (.) dan garis miring (/) oleh jalur penyerapan berarti deskriptor metrik yang dihasilkan berbeda antara metrik yang diserap menggunakan eksportir googlemanagedprometheus dan yang diserap menggunakan eksportir otlphttp. Jika menggunakan kedua jalur penyerapan, Anda akan memiliki dua set metrik; untuk mendapatkan hasil lengkap saat membuat kueri, Anda harus menggabungkan hasil secara manual dari metrik versi Prometheus dan OTLP.

• Telemetry API tidak menambahkan unit ke nama metrik jika ada unit, dan tidak menambahkan akhiran _total ke penghitung. Jadi, metrik yang diekspor sebagai prometheus.googleapis.com/foo/counter saat menggunakan Telemetry API diekspor sebagai prometheus.googleapis.com/foo_seconds_total/counter oleh pengekspor googlemanagedprometheus. Perbedaan ini juga berlaku untuk sufiks _total dan _ratio.

• API mensintesis nilai sum_of_squared_deviation untuk nilai distribusi yang berasal dari histogram eksponensial. Ekspor googlemanagedprometheus tidak menetapkan kolom ini untuk histogram eksponensial.

• API mengonversi semua nilai titik bilangan bulat menjadi nilai ganda untuk metrik Prometheus.

• API tidak menetapkan label scope_version atau scope_name jika label tersebut memiliki nilai kosong.

Tempat melihat data yang diserap

Data rekaman aktivitas yang dimasukkan melalui Telemetry API dapat dilihat menggunakan halaman Trace Explorer. Untuk mengetahui informasi tentang cara melihat data rekaman aktivitas, lihat topik berikut:

• Menemukan dan menjelajahi rekaman aktivitas.
• Membuat kueri dan menganalisis rekaman aktivitas.

Data metrik yang dimasukkan melalui Telemetry API dapat dilihat menggunakan halaman Metrics Explorer. Untuk informasi tentang cara melihat dan membuat diagram data metrik, lihat Membuat diagram dengan Metrics Explorer.

Dukungan Kontrol Layanan VPC

Layanan Telemetry API, yang nama layanannya adalah telemetry.googleapis.com, merupakan layanan yang didukung Kontrol Layanan VPC. Setiap batasan Kontrol Layanan VPC yang Anda buat untuk layanan Telemetry API hanya berlaku untuk layanan tersebut. Batasan tersebut tidak berlaku untuk layanan lain, termasuk layanan cloudtrace.googleapis.com, yang juga dapat menyerap data rekaman aktivitas.

Untuk informasi selengkapnya, lihat referensi berikut:

• Dokumentasi Kontrol Layanan VPC.
• Produk yang didukung dan batasan.