Ringkasan v1.metrics

Dokumen ini menjelaskan cara data metrik yang dikirim ke project Anda menggunakan Telemetry (OTLP) API dipetakan ke struktur Cloud Monitoring. Google Cloud API ini mengimplementasikan OpenTelemetry Line Protocol. Anda dapat mengirim data ke API ini saat menginstrumentasikan aplikasi dengan pengekspor otlphttp dan OpenTelemetry Collector, atau saat menggunakan OpenTelemetry SDK.

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

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:

• Ringkasan contoh instrumentasi berbasis pengumpul.
• Ringkasan penyerapan metrik OTLP.

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)

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 dimonitor

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 Tolak titik jika kosong
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 (diperlukan)	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 Tolak titik jika kosong

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.
• Peta Sum OTLP sebagai berikut:
  • Untuk pengukur Cloud Monitoring saat is_monotonic disetel ke false.
  • Ke kumulatif Cloud Monitoring 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 berjenis DOUBLE.
  • Setiap kuantil menjadi deret waktu pengukur sendiri berjenis DOUBLE, dengan label quantile.

Tabel berikut merangkum pemetaan metrik:

Jenis titik OTLP	Memantau jenis metrik	Memantau 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 (monoton, DELTA)	DELTA	DOUBLE	/delta
SUM (non-monotonic, CUMULATIVE)	GAUGE	DOUBLE	/gauge
SUM (non-monotonik, DELTA)	Tidak didukung			UpDownCounter dengan temporaritas delta tidak didukung.
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 dibuat 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. Ekspor 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 pengekspor googlemanagedprometheus dan yang diserap menggunakan pengekspor 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 eksportir googlemanagedprometheus. Perbedaan ini juga berlaku untuk akhiran _total dan _ratio.

• API mensintesis nilai sum_of_squared_deviation untuk nilai distribusi yang berasal dari histogram eksponensial. Eksporter 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.

Cloud Monitoring dan residensi data

Untuk mempelajari cara data metrik Anda disimpan, lihat Regionalitas data untuk Cloud Monitoring.

Tempat melihat data yang diserap

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.