Mengonfigurasi metrik distribusi

Halaman ini menjelaskan cara membuat metrik berbasis log jenis distribusi menggunakan Konsol Google Cloud, Logging API, dan Google Cloud CLI. Untuk melihat tampilan metrik berbasis log secara keseluruhan, buka Ringkasan metrik berbasis log.

Ringkasan

Metrik distribusi memerlukan filter untuk memilih entri log yang relevan dan ekstraktor nilai untuk mengambil nilai numerik untuk distribusi. Ekstraktor nilai sama dengan jenis yang digunakan untuk label yang ditentukan pengguna.

Metrik distribusi mencatat distribusi statistik dari nilai yang diekstrak dalam bucket histogram. Nilai yang diekstrak tidak dicatat secara terpisah, tetapi distribusinya di seluruh bucket yang dikonfigurasi dicatat, bersama dengan jumlah, rata-rata, dan jumlah deviasi kuadrat dari nilai tersebut. Anda dapat menggunakan tata letak default bucket histogram dalam distribusi Anda atau Anda dapat menyesuaikan batas bucket untuk memperkirakan nilai.

Untuk informasi selengkapnya tentang cara melihat dan menafsirkan metrik distribusi, lihat Metrik distribusi.

Sebelum memulai

Untuk menggunakan metrik berbasis log, Anda harus memiliki project Google Cloud dengan penagihan yang diaktifkan:
Pastikan peran Identity and Access Management Anda menyertakan izin yang diperlukan untuk membuat dan melihat metrik berbasis log, dan untuk membuat kebijakan pemberitahuan. Untuk mengetahui detailnya, lihat Izin untuk metrik berbasis log.

Membuat metrik distribusi

Metrik ini menghitung entri log yang diidentifikasi oleh filter yang Anda berikan. Anda dapat menggunakan ekspresi reguler dalam filter, dan sebaiknya sertakan jenis resource. Panjang filter tidak boleh lebih dari 20.000 karakter.

Jangan masukkan informasi sensitif dalam filter. Filter diperlakukan sebagai data layanan.

Konsol

Ikuti langkah-langkah berikut untuk membuat metrik penghitung berbasis log di Konsol Google Cloud di project Google Cloud Anda:

Pada panel navigasi Google Cloud Console, pilih Logging, lalu pilih Log-based Metrics:
Buka Metrik Berbasis Log
Klik Create Metric. Panel Buat metrik log akan muncul.
Tetapkan Jenis metrik: Pilih Distribusi.
Tetapkan kolom berikut di bagian Detail:
- Log metric name: Pilih nama yang unik di antara metrik berbasis log di project Google Cloud Anda. Beberapa pembatasan penamaan berlaku; lihat Pemecahan masalah untuk detailnya.
- Deskripsi: Masukkan deskripsi untuk metrik.
- Unit: (Opsional) Untuk metrik distribusi, Anda dapat secara opsional memasukkan unit, seperti s, ms, dll. Untuk informasi selengkapnya, lihat kolom unit di MetricDescriptor.
Tentukan filter metrik di bagian Pilihan filter.
1. Gunakan Pilih cakupan log untuk memilih apakah filter Anda menargetkan semua log project Google Cloud atau hanya log dari bucket tertentu.
2. Buat filter yang hanya mengumpulkan entri log yang ingin Anda hitung dalam metrik menggunakan bahasa kueri logging. Anda juga dapat menggunakan ekspresi reguler untuk membuat filter metrik.
3. Nama kolom: Masukkan kolom entri log yang berisi nilai distribusi. Anda ditawari pilihan saat mengetik. Contoh:
```
 protoPayload.latency
```
4. Ekspresi reguler: (Opsional) Jika Nama kolom selalu berisi nilai numerik yang dapat dikonversi ke jenis double, Anda dapat mengosongkan kolom ini. Jika tidak, tentukan ekspresi reguler yang mengekstrak nilai distribusi numerik dari nilai kolom.
  
  Contoh. Misalkan kolom entri log latency Anda berisi angka yang diikuti dengan ms untuk milidetik. Ekspresi reguler berikut memilih angka tanpa akhiran unit:
```
([0-9.]+)
```
  Tanda kurung, yang dikenal sebagai grup tangkapan ekspresi reguler, mengidentifikasi bagian pencocokan teks yang akan diekstrak. Baca cara menggunakan ekspresi reguler untuk mengetahui detailnya.
- Advanced (Bucket histogram): (Opsional) Mengklik Advanced akan membuka bagian formulir yang dapat Anda gunakan untuk menentukan tata letak bucket kustom. Jika Anda tidak menentukan tata letak bucket, tata letak bucket default akan disediakan. Untuk mengetahui informasi selengkapnya, lihat Bucket histogram di halaman ini.
1. Untuk melihat entri log yang cocok dengan filter Anda, klik Pratinjau log.
(Opsional) Tambahkan label di bagian Label. Untuk petunjuk mengenai cara membuat label, lihat Membuat label.
Klik Buat metrik untuk membuat metrik.

gcloud

Untuk membuat metrik berbasis log jenis distribusi, buat file yang berisi representasi definisi LogMetric dalam format JSON atau YAML. Kemudian, gunakan perintah berikut untuk membaca konfigurasi dari file Anda:

gcloud logging metrics create METRIC_NAME --config-from-file FILENAME

Untuk mengetahui informasi tentang cara mendeskripsikan bucket histogram untuk distribusi, lihat Bucket histogram.

API

Untuk membuat metrik distribusi, gunakan metode projects.metrics.create dari Logging API. Anda dapat mencoba metode ini di APIs Explorer. Siapkan argumen ke metode sebagai berikut:

Tetapkan kolom parent ke project atau bucket tempat metrik akan dibuat:
- Untuk metrik berbasis log dengan cakupan project, tentukan project:
```
projects/PROJECT_ID
```
- Untuk metrik berbasis log dengan cakupan bucket, tentukan bucket:
```
projects/PROJECT_ID/locations/LOCATION/bucket/BUCKET_ID
```

Tetapkan isi permintaan ke objek LogMetric. Berikut ini adalah contoh objek untuk metrik distribusi.

{
  name:        "my-metric"
  description: "Description of my-metric."
  filter:      "resource.type=gce_instance AND log_id(\"syslog\")",
  valueExtractor: "REGEXP_EXTRACT(jsonPayload.latencyField, \"([0-9.]+)ms\")",

  labelExtractors: {
    "my-label-1":
      "REGEXP_EXTRACT(jsonPayload.someField, \"before ([[:word:]]+) after\")",
    "my-label-2":
      "EXTRACT(jsonPayload.anotherField, \"before ([0-9]+) after\")",
  },
  bucketOptions: { [SEE_BELOW] },

  metricDescriptor: {
      metricKind: DELTA,
      valueType: DISTRIBUTION,
      unit: "ms",

      labels: [
        {
          key: "my-label-1",
          valueType: STRING,
          description: "Description of string my-label-1.",
        },
        {
          key: "my-label-2",
          valueType: INT64,
          description: "Description of integer my-label-2.",
        }
      ]
  },
}

Catatan:

Beberapa batasan penamaan berlaku; lihat Pemecahan masalah untuk mengetahui detailnya.
metricDescriptor: objek MetricDescriptor. metricKind harus DELTA. valueType harus DISTRIBUTION.

Bucket histogram

Metrik distribusi mencakup histogram yang menghitung jumlah nilai yang berada di rentang tertentu (bucket). Anda dapat memiliki hingga 200 bucket dalam satu metrik distribusi.

Setiap bucket memiliki dua nilai batas, L dan H, yang menentukan nilai terendah dan tertinggi yang tercakup dalam bucket. Lebar bucket adalah H - L. Karena tidak ada celah antar-bucket, batas bawah satu bucket sama dengan batas yang lebih tinggi dari bucket sebelumnya, dan seterusnya. Agar batas tidak jatuh ke lebih dari satu bucket, bucket menyertakan batas bawahnya; batas yang lebih tinggi berada di bucket berikutnya.

Semua tata letak bucket dapat ditentukan dengan mencantumkan, yang meningkatkan urutan nilai batas antara setiap bucket. Bucket pertama adalah bucket underflow, yang menghitung nilai kurang dari batas pertama. Bucket terakhir adalah bucket overflow, yang menghitung nilai yang lebih besar dari atau sama dengan batas terakhir. Bucket lain menghitung nilai yang lebih besar dari atau sama dengan batas bawahnya dan kurang dari batas atasnya. Jika ada n nilai batas, berarti ada n+1 bucket. Tidak termasuk bucket underflow dan overflow, ada n-1 bucket terbatas.

Ada tiga cara berbeda dalam menentukan batas antara bucket histogram untuk metrik distribusi. Anda dapat menentukan formula untuk nilai batas, atau mencantumkan nilai batas:

Linear(offset, width, i): Setiap bucket memiliki lebar yang sama. Batasnya adalah offset + width * i, untuk i=0,1,2,...,N. Untuk informasi selengkapnya tentang bucket linear, lihat referensi API.
Eksponensial(scale, growth_factor, i): Lebar bucket meningkat untuk nilai yang lebih tinggi. Batasnya adalah scale * growth_factorⁱ, untuk i=0,1,2,...,N. Untuk informasi selengkapnya tentang bucket eksponensial, lihat referensi API.
Eksplisit: Anda mencantumkan semua batas untuk bucket di array bounds. Bucket i memiliki batas berikut:

Batas atas: batas[i] untuk (0 <= i < N-1)
Batas bawah: batas[i - 1] untuk (1 <= i < N)

Untuk informasi selengkapnya tentang bucket eksplisit, lihat referensi API.

Cara Anda menentukan bucket histogram dijelaskan di bagian berikut:

Konsol

Submenu Bucket Histogram akan terbuka saat Anda membuat metrik distribusi dan mengklik More di formulir Metric editor. Subformulir ditampilkan di bawah ini untuk tata letak bucket Linear:

Bucket histogram

Bucket linear: Isi bentuk bucket histogram seperti berikut.

Jenis: Linear
Nilai awal (a): Batas bawah bucket terbatas pertama. Nilai ini disebut offset di API.
Jumlah bucket (N): Jumlah bucket terbatas. Nilai harus lebih besar atau sama dengan 0.
Lebar bucket (b): Perbedaan antara batas atas dan batas bawah di setiap bucket terbatas. Nilai harus lebih besar dari 0.

Misalnya, jika nilai awal adalah 5, jumlah bucket adalah 4, dan lebar bucket adalah 15, rentang bucket adalah sebagai berikut:

(-INF, 5), [5, 20), [20, 35), [35, 50), [50, 65), [65, +INF)

Bucket eksplisit: Isi bentuk bucket histogram seperti berikut:

Jenis: Eksplisit
Batas (b): Daftar yang dipisahkan koma untuk nilai batas bucket terbatas. Hal ini juga menentukan jumlah bucket dan lebarnya.

Misalnya, jika daftar batas:

0, 1, 2, 5, 10, 20

maka ada lima bucket terbatas dengan rentang berikut:

(-INF, 0), [0, 1), [1, 2), [2,5), [5, 10), [10, 20), [20, +INF)

Bucket eksponensial: Isi bentuk bucket histogram seperti berikut:

Jenis: Eksponensial
Jumlah bucket (N): Total jumlah bucket terbatas. Nilai harus lebih besar dari 0.
Skala linear (a): Skala linear untuk bucket. Nilai harus lebih besar dari 0.
Faktor pertumbuhan eksponensial (b): Faktor pertumbuhan eksponensial untuk bucket. Nilai harus lebih besar dari 1.

Misalnya, jika N=4, a=3, dan b=2, rentang bucket adalah sebagai berikut:

(-INF, 3), [3, 6), [6, 12), [12, 24), [24, 48), [48, +INF)

Untuk mengetahui informasi selengkapnya tentang bucket, lihat BucketOptions di Cloud Monitoring API.

API

Tata letak bucket opsional ditentukan oleh kolom bucketOptions dalam objek LogMetric yang disediakan untuk projects.metrics.create. Untuk objek LogMetric lengkap, lihat Membuat metrik distribusi di halaman ini. Penambahan untuk tata letak bucket ditampilkan di bawah ini:

Bucket linear:

{ # LogMetric object
  ...
  bucketOptions: {
    linearBuckets: {
      numFiniteBuckets: 4,
      width: 15,
      offset: 5
    }
  },

Contoh sebelumnya akan membuat bucket berikut:

(-INF, 5), [5, 20), [20, 35), [35, 50), [50, 65), [65, +INF)

Bucket eksplisit: Batas dicantumkan satu per satu.

{ # LogMetric object
  ...
  bucketOptions: {
    explicitBuckets: {
      bounds: [0, 1, 2, 5, 10, 20 ]
    }
  },

Contoh sebelumnya akan membuat bucket berikut:

(-INF, 0), [0, 1), [1, 2), [2, 5), [5, 10), [10, 20), [20, +INF)

Bucket eksponensial: Batasan berupa scale * growthFactor ^ i, untuk i=0,1,2, ..., numFiniteBuckets

{ # LogMetric object
  ...
  bucketOptions: {
    exponentialBuckets: {
      numFiniteBuckets: 4,
      growthFactor: 2,
      scale: 3
    }
  },
  ...
}

Contoh sebelumnya akan membuat bucket berikut:

(-INF, 3), [3, 6), [6, 12), [12, 24), [24, 48), [48, +INF)

Latensi metrik baru

Metrik baru Anda akan segera muncul dalam daftar metrik dan di menu Monitoring yang relevan. Namun, mungkin perlu waktu hingga satu menit agar metrik mulai mengumpulkan data untuk entri log yang cocok.

Memeriksa metrik distribusi

Untuk menampilkan daftar metrik berbasis log yang ditentukan pengguna dalam project Google Cloud Anda atau untuk memeriksa metrik tertentu dalam project Google Cloud Anda, lakukan hal berikut:

Konsol

Pada panel navigasi Google Cloud Console, pilih Logging, lalu pilih Log-based Metrics:
Buka Metrik Berbasis Log
Di panel Metrik yang ditentukan pengguna, Anda akan melihat metrik berbasis log yang ditetapkan pengguna dalam project Google Cloud saat ini:
Untuk melihat data dalam metrik berbasis log, klik Menu pada baris metrik, lalu pilih View in Metrics Explorer.

gcloud

Untuk menampilkan daftar metrik berbasis log yang ditentukan pengguna dalam project Google Cloud Anda, gunakan perintah berikut:

gcloud logging metrics list

Untuk menampilkan metrik berbasis log yang ditentukan pengguna dalam project Google Cloud Anda, gunakan perintah berikut:

gcloud logging metrics describe METRIC_NAME

Untuk mendapatkan bantuan, gunakan perintah berikut:

gcloud logging metrics --help

Anda tidak dapat membaca data deret waktu metrik dari Google Cloud CLI.

API

Mencantumkan metrik

Untuk menampilkan daftar metrik berbasis log yang ditetapkan pengguna dalam project Google Cloud, gunakan metode API projects.metrics.list. Isi parameter ke metode sebagai berikut:

parent: Nama resource project Google Cloud: projects/PROJECT_ID.
pageSize: Jumlah hasil maksimum.
pageToken: Mendapatkan halaman hasil berikutnya. Untuk informasi tentang penggunaan token halaman, lihat projects.metrics.list.

Mengambil definisi metrik

Untuk mengambil satu metrik berbasis log yang ditentukan pengguna, gunakan metode API projects.metrics.get. Isi parameter ke metode tersebut sebagai berikut:

metricName: Nama resource metrik:
```
projects/PROJECT_ID/metrics/METRIC_ID
```

Membaca data metrik

Untuk membaca data deret waktu dalam metrik berbasis log, gunakan projects.timeseries.list di Cloud Monitoring API. Untuk mengetahui detail tentang data deret waktu, lihat Membaca deret waktu.

Untuk membaca satu metrik berbasis log yang ditentukan pengguna, isi parameter metode dengan jenis dan ID metrik ini:

logging.googleapis.com/user/METRIC_ID

Memperbarui metrik distribusi

Anda dapat mengedit metrik berbasis log yang ditentukan pengguna untuk mengubah deskripsi, filter, dan nama kolom yang dirujuk dalam metrik tersebut. Anda dapat menambahkan label baru ke metrik dan mengubah ekspresi reguler yang digunakan untuk mengekstrak nilai metrik dan labelnya. Jika menggunakan metrik cakupan bucket, Anda juga dapat memperbarui bucket metrik.

Anda tidak dapat mengubah nama atau jenis metrik berbasis log yang ditentukan pengguna atau labelnya, dan Anda tidak dapat menghapus label yang ada dalam metrik berbasis log.

Untuk mengedit metrik berbasis log, lakukan hal berikut:

Konsol

Pada panel navigasi Google Cloud Console, pilih Logging, lalu pilih Log-based Metrics:
Buka Metrik Berbasis Log
Klik Edit metric di Menu untuk metrik berbasis log yang ingin Anda ubah.
Ubah item yang diizinkan dalam metrik.
Klik Perbarui metrik.

gcloud

Gunakan Google Cloud CLI untuk mengubah deskripsi, kueri filter, dan bucket metrik penghitung. Anda dapat memperbarui salah satu atau semua kolom sekaligus.

gcloud logging update METRIC_NAME \
  --description="METRIC_DESCRIPTION" \
  --log-filter="FILTER" \
  --bucket-name=BUCKET_NAME

Jika Anda mengubah bucket yang terkait dengan metrik cakupan bucket, data metrik yang dikumpulkan sebelum perubahan tidak lagi mencerminkan konfigurasi saat ini. Data metrik yang dikumpulkan untuk bucket sebelumnya tidak dihapus.

Untuk memperbarui metrik distribusi atau kolom metrik penghitung lainnya, kecuali METRIC_NAME, buat file yang berisi revisi spesifikasi LogMetric dalam format JSON atau YAML. Kemudian, perbarui metrik dengan memanggil perintah update dengan kolom --config-from-file, dengan mengganti FILENAME dengan nama file JSON atau YAML Anda:

gcloud logging update METRIC_NAME --config-from-file FILENAME

Untuk detail selengkapnya, gunakan perintah berikut:

gcloud logging metrics update --help

API

Untuk mengedit metrik berbasis log, gunakan metode projects.metrics.update di API. Tetapkan kolom sebagai berikut:

metricName: Nama resource lengkap metrik:

projects/PROJECT_ID/metrics/METRIC_ID

Contoh:

projects/my-gcp-project/metrics/my-error-metric

Dalam isi permintaan, sertakan objek LogMetric yang sama persis dengan metrik yang ada, kecuali untuk perubahan dan penambahan yang ingin Anda buat.

Hapus metrik distribusi

Untuk menghapus metrik berbasis log yang ditentukan pengguna, lakukan tindakan berikut:

Konsol

Pada panel navigasi Google Cloud Console, pilih Logging, lalu pilih Log-based Metrics:
Buka Metrik Berbasis Log
Pilih metrik yang ingin Anda hapus, lalu klik Hapus.

Atau, klik Delete metric di menu pada metrik berbasis log yang ingin Anda hapus.

gcloud

Gunakan perintah berikut untuk menghapus metrik berbasis log yang ditentukan pengguna dalam project Google Cloud saat ini:

gcloud logging metrics delete METRIC_NAME

For more details, use the following command:

gcloud logging metrics delete --help

API

Untuk menghapus metrik berbasis log yang ditetapkan pengguna, gunakan metode projects.metrics.delete di API.

Selain itu, di halaman Log-based metric di Konsol Google Cloud, panel User-defined metrics pada antarmuka metrik berbasis log menyediakan lebih banyak fitur untuk membantu Anda mengelola metrik yang ditentukan pengguna di project Google Cloud Anda. Lihat Panel metrik buatan pengguna untuk mengetahui detailnya.