Ringkasan v1.metrics

Dokumen ini menjelaskan cara data metrik yang dikirim ke your Google Cloud project menggunakan Telemetry (OTLP) API dipetakan ke struktur Cloud Monitoring. API ini mengimplementasikan OpenTelemetry 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 trace ke Google Cloud project Anda, sebaiknya gunakan pengekspor yang menulis data berformat OTLP ke Collector, yang kemudian mengirim data trace ke Telemetry API. Di collector, 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 trace atau metrik ke Telemetry API, lihat dokumen berikut:

Jika tidak dapat menggunakan collector, Anda dapat menggunakan library OpenTelemetry yang berisi pengekspor OTLP dalam proses untuk mengirim telemetri ke Telemetry API. Untuk mempelajari cara mengekspor data trace 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 collector, biasanya Anda menggunakan ekstensi googleclientauth untuk melakukan autentikasi dengan kredensial Google.

Untuk contoh autentikasi saat menggunakan ekspor data trace langsung, lihat Mengonfigurasi autentikasi. Contoh ini mengilustrasikan cara mengonfigurasi pengekspor dengan Google Cloud Kredensial Default Aplikasi (ADC) dan menambahkan Google Auth Library 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 Identity and Access Management (IAM) berikut kepada pengguna atau akun layanan yang digunakan aplikasi:

    • Peran Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) di project kuota.
    • Peran Cloud Telemetry Writer (roles/telemetry.writer) di project. Peran ini memungkinkan aplikasi Anda menulis data log, metrik, dan trace.

Metrik OTLP di Cloud Monitoring

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 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 tentukan 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, sesuai urutan prioritas:

Label prometheus-target Nilai yang digunakan (sesuai 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 container
  • 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 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 collector 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.

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 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 dibuat 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 kemunculan 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 saat unit ada, 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.

Kuota

Untuk mengetahui informasi tentang kuota yang terkait dengan Telemetry API, lihat Batas Telemetry API.