Ringkasan v1.metrics

Dokumen ini menjelaskan cara data metrik yang dikirimkan your Google Cloud project menggunakan Telemetry (OTLP) API dipetakan ke struktur Cloud Monitoring. 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 Clouddengan Google Cloud teknisi yang ditugaskan untuk memastikan dukungan dalam menyerap dan memvisualisasikan telemetri Anda.

Praktik terbaik

Saat menginstrumentasikan aplikasi untuk mengirim data pelacakan ke Google Cloud project Anda, sebaiknya gunakan pengekspor yang menulis data berformat OTLP ke Collector, yang kemudian mengirim data pelacakan ke Telemetry API. Di pengumpul, 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 pelacakan atau metrik 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 pengekspor OTLP dalam proses untuk mengirim telemetri ke Telemetry API. Untuk mempelajari cara mengekspor data pelacakan secara langsung, lihat Pengekspor Cloud Trace ke endpoint OTLP.

Autentikasi

Anda harus mengonfigurasi pengekspor dengan kredensial yang diperlukan untuk mengirim data ke your Google Cloud project. Misalnya, saat menggunakan pengumpul, biasanya Anda menggunakan ekstensi googleclientauth untuk melakukan autentikasi dengan kredensial Google.

Untuk contoh autentikasi saat menggunakan ekspor data pelacakan langsung, lihat Mengonfigurasi autentikasi. Contoh ini mengilustrasikan cara mengonfigurasi pengekspor dengan Google Cloud Kredensial Default Aplikasi (ADC) dan menambahkan Library Google Auth khusus bahasa ke aplikasi Anda.

Untuk mengirim data telemetri ke your Google Cloud project menggunakan Telemetry API, Anda juga harus melakukan hal berikut:

• Mengonfigurasi project kuota. Untuk mempelajari lebih lanjut, lihat Menetapkan project kuota.
• Memberikan peran Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) kepada pengguna atau akun layanan yang digunakan aplikasi di project kuota tersebut.

• Memberikan 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 diserap ke Cloud Monitoring menggunakan OpenTelemetry Collector dan pengekspor otlphttp atau dikirim langsung menggunakan OpenTelemetry SDK, metrik OTLP akan dipetakan ke struktur metrik Cloud Monitoring. Bagian ini menjelaskan hal berikut:

• Pemetaan antara resource OTLP dan resource yang dimonitor 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, menggunakan pemetaan Prometheus.

Pemetaan Prometheus

Metrik Prometheus memerlukan penggunaan jenis resource yang dimonitor prometheus_target.

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

Sebaiknya Anda menentukan nilai untuk label ini secara eksplisit, meskipun kami telah menerapkan logika penggantian untuk digunakan jika tidak ada nilai eksplisit.

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

Label prometheus-target	Nilai yang digunakan (dalam urutan prioritas)
location (wajib)	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 __vae__, jika atribut cloud.platform adalah gcp.agent_engine String kosong
namespace	Atribut namespace Atribut k8s.namespace.name Atribut service.namespace String kosong
job	Atribut job "service.namespace" + "/" + service.namespace atribut 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 (wajib)	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 dalam format deret waktu Prometheus. Nama metrik harus tidak memiliki domain atau memiliki domain prometheus.googleapis.com. Setelah konversi, nama metrik akan menyertakan awalan prometheus.googleapis.com dan akhiran 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 akan 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 dukungan nilai INT64 adalah Anda akan mengalami konflik yang hanya dapat diselesaikan dengan menghapus metrik.

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

Pemetaan metrik Prometheus

Jenis metrik dipetakan sebagai berikut:

• Gauge OTLP dipetakan ke gauge Cloud Monitoring.
• Sum OTLP dipetakan sebagai berikut:
  • Ke Cloud Monitoring gauge saat is_monotonic ditetapkan ke false.
  • Ke kumulatif Cloud Monitoring kumulatif saat aggregation_temporality ditetapkan ke AGGREGATION_TEMPORALITY_CUMULATIVE.
  • Ke delta Cloud Monitoring saat aggregation_temporality ditetapkan 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 hitungan dan jumlah diberi akhiran _count atau _sum masing-masing, dan ditulis sebagai metrik kumulatif Cloud Monitoring berjenis DOUBLE.
  • Setiap kuantil menjadi deret waktu gauge sendiri berjenis DOUBLE, dengan label quantile.

Tabel berikut merangkum pemetaan metrik:

Jenis titik OTLP	Jenis metrik Monitoring	Jenis nilai Monitoring	Akhiran	Catatan
GAUGE	GAUGE	DOUBLE	/gauge
GAUGE (metric.metadata["prometheus.type"]="unknown")	GAUGE	DOUBLE	/unknown	Prometheus Unknowns dibagi menjadi penghitung dan gauge oleh OpenTelemetry Collector.
SUM (monotonik, CUMULATIVE)	CUMULATIVE	DOUBLE	/counter
SUM (monotonik, CUMULATIVE, metric.metadata["prometheus.type"]="unknown")	CUMULATIVE	DOUBLE	/unknown:counter	Prometheus Unknowns dibagi menjadi penghitung dan gauge oleh OpenTelemetry Collector.
SUM (monotonik, DELTA)	DELTA	DOUBLE	/delta
SUM (non-monotonik, CUMULATIVE)	GAUGE	DOUBLE	/gauge
SUM (non-monotonik, DELTA)	Tidak didukung			UpDownCounter dengan temporalitas delta tidak didukung.
HISTOGRAM (CUMULATIVE)	CUMULATIVE	DISTRIBUTION dengan bucket eksplisit	/histogram
EXPONENTIAL HISTOGRAM (CUMULATIVE)	CUMULATIVE	DISTRIBUTION dengan bucket eksponensial	/histogram
HISTOGRAM (DELTA)	DELTA	DISTRIBUTION dengan bucket eksplisit	/histogram:delta
EXPONENTIAL HISTOGRAM (DELTA)	DELTA	DISTRIBUTION dengan bucket eksponensial	/histogram:delta
SUMMARY (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 hitungan, jumlah, dan setiap kuantil yang dihitung. Metrik kuantil juga dihasilkan dengan label quantile.

Perbedaan antara pengekspor 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. Pengekspor googlemanagedprometheus mengonversi semua instance karakter ini menjadi karakter garis bawah (_). Misalnya, metrik OTLP yang disebut prometheus.googleapis.com/foo.bar/gauge diekspor secara verbatim oleh pengekspor OTLP, tetapi diekspor sebagai prometheus.googleapis.com/foo_bar/gauge oleh pengekspor googlemanagedprometheus.

  Saat metrik diserap, Cloud Monitoring akan membuat deskriptor metrik berdasarkan nama. Perbedaan dalam cara karakter titik (.) dan garis miring (/) ditangani oleh jalur penyerapan berarti deskriptor metrik yang dihasilkan berbeda antara metrik yang diserap menggunakan pengekspor googlemanagedprometheus dan metrik yang diserap menggunakan pengekspor otlphttp. Jika menggunakan kedua jalur penyerapan, Anda akan memiliki dua kumpulan 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 akhiran _total dan _ratio.

• API mensintesis nilai sum_of_squared_deviation untuk nilai distribusi yang berasal dari histogram eksponensial. Pengekspor 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 diserap melalui Telemetry API dapat dilihat menggunakan halaman Metrics Explorer. Untuk mengetahui informasi tentang cara melihat dan membuat diagram data metrik, lihat Membuat diagram dengan Metrics Explorer.