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 keseluruhan metrik berbasis log, 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 adalah jenis yang sama dengan yang digunakan untuk label yang ditentukan pengguna.

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

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

Sebelum memulai

  1. Untuk menggunakan metrik berbasis log, Anda harus memiliki project Google Cloud dengan penagihan yang diaktifkan:

    1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

    2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

      Go to project selector

    3. Make sure that billing is enabled for your Google Cloud project.

    4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

      Go to project selector

    5. Make sure that billing is enabled for your Google Cloud project.

  2. Pastikan peran Identity and Access Management Anda menyertakan izin yang diperlukan untuk membuat dan melihat metrik berbasis log, serta 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 melebihi 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:

  1. Di konsol Google Cloud, buka halaman Log-based Metrics:

    Buka Metrik Berbasis Log

    Jika Anda menggunakan kotak penelusuran untuk menemukan halaman ini, pilih hasil yang subjudulnya adalah Logging.

  2. Klik Buat Metrik. Panel Create logs metric akan muncul.

  3. Tetapkan Jenis metrik: Pilih Distribusi.

  4. Tetapkan kolom berikut di bagian Detail:

    • Nama metrik log: Pilih nama yang unik di antara metrik berbasis log di project Google Cloud Anda. Beberapa pembatasan penamaan berlaku; lihat Pemecahan masalah untuk mengetahui detailnya.
    • Deskripsi: Masukkan deskripsi untuk metrik.
    • Unit: (Opsional) Untuk metrik distribusi, Anda dapat memasukkan unit secara opsional, seperti s dan ms. Untuk mengetahui informasi selengkapnya, lihat kolom unit dari MetricDescriptor.

  5. Tentukan filter metrik di bagian Filter selection.

    1. Gunakan menu Select project or log bucket untuk memilih apakah metrik menghitung entri log di project Google Cloud Anda atau hanya entri log tersebut di bucket log 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 akan ditawari pilihan saat mengetik. Misalnya:

      protoPayload.latency

    4. Ekspresi reguler: (Opsional) Jika Nama kolom selalu berisi nilai numerik yang dapat dikonversi ke jenis double, Anda dapat membiarkan kolom ini kosong. 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. Regexp berikut memilih angka tanpa akhiran satuan:

      ([0-9.]+)

      Tanda kurung, yang dikenal sebagai grup tangkapan regexp, mengidentifikasi bagian pencocokan teks yang akan diekstrak. Lihat menggunakan ekspresi reguler untuk mengetahui detailnya.

    • Lanjutan (Bucket histogram): (Opsional) Mengklik Lanjutan 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 informasi selengkapnya, lihat Bucket histogram di halaman ini.
    1. Untuk melihat entri log yang cocok dengan filter Anda, klik Pratinjau log.

  6. (Opsional) Tambahkan label di bagian Labels. Untuk petunjuk mengenai cara membuat label, lihat Membuat label.

  7. Klik Create metric untuk membuat metrik.

gcloud

Untuk membuat metrik berbasis log jenis distribusi, buat file yang berisi representasi definisi LogMetric Anda 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 informasi tentang cara mendeskripsikan bucket histogram untuk distribusi, lihat Bucket histogram.

API

Untuk membuat metrik distribusi, gunakan metode projects.metrics.create Logging API. Jika Anda menggunakan panel API Explorer di halaman referensi, siapkan argumen sebagai berikut:

  1. Tetapkan kolom parent ke project atau bucket tempat metrik akan dibuat:

    • Untuk metrik berbasis log cakupan project, tentukan project:
    projects/PROJECT_ID
    • Untuk metrik berbasis log dengan cakupan bucket, tentukan bucket:
    projects/PROJECT_ID/locations/LOCATION/bucket/BUCKET_ID

  2. Tetapkan isi permintaan ke objek LogMetric. Berikut adalah objek contoh 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 berupa DELTA. valueType harus berupa DISTRIBUTION.

Bucket histogram

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

Setiap bucket memiliki dua nilai batas, L dan H, yang menentukan nilai terendah dan tertinggi yang tercakup oleh bucket. Lebar bucket adalah H - L. Karena tidak boleh ada celah di antara bucket, batas bawah satu bucket sama dengan batas atas bucket sebelumnya, dan seterusnya. Agar batas tidak masuk ke lebih dari satu bucket, bucket menyertakan batas bawahnya; batas yang lebih tinggi adalah milik bucket berikutnya.

Semua tata letak bucket dapat ditentukan dengan mencantumkan, dalam urutan menaik, 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 lainnya menghitung nilai yang lebih besar dari atau sama dengan batas bawahnya dan kurang dari batas atasnya. Jika ada n nilai batas, maka ada n+1 bucket. Tidak termasuk bucket underflow dan overflow, ada bucket terbatas n-1.

Ada tiga cara berbeda untuk 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. Batas adalah offset + width * i, untuk i=0,1,2,...,N. Untuk mengetahui informasi selengkapnya tentang bucket linear, lihat referensi API.

  • Eksponensial(scale, growth_factor, i): Lebar bucket meningkat untuk nilai yang lebih tinggi. Batas adalah scale * growth_factori, untuk i=0,1,2,...,N. Untuk informasi selengkapnya tentang bucket eksponensial, lihat referensi API.

  • Ekspresi: Anda mencantumkan semua batas untuk bucket dalam array batas. Bucket i memiliki batas berikut:

    Upper bound: bounds[*i*] for (0 <= *i* < *N*-1)
Lower bound: bounds[*i* - 1] for (1 <= *i* < *N*)

    Untuk informasi selengkapnya tentang bucket vulgar, lihat referensi API.

Cara menentukan bucket histogram dijelaskan di bagian berikut:

Konsol

Submenu Histogram buckets akan terbuka saat Anda membuat metrik distribusi dan mengklik More di formulir Metric editor. Subformulir berikut adalah untuk tata letak bucket Linear:

Bucket histogram

Bucket linear: Isi formulir bucket histogram sebagai berikut.

  • Jenis: Linear
  • Nilai awal (a): Batas bawah bucket berhingga pertama. Nilai ini disebut offset di API.
  • Jumlah bucket (N): Jumlah bucket terbatas. Nilai harus lebih besar dari 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 formulir bucket histogram sebagai berikut:

  • Type: Explicit
  • Batas (b): Daftar nilai batas bucket berhingga yang dipisahkan koma. Hal ini juga menentukan jumlah bucket dan lebarnya.

Misalnya, jika daftar batas adalah:

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 formulir bucket histogram sebagai berikut:

  • Type: Exponential

  • Jumlah bucket (N): Jumlah total 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 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 adalah seperti yang ditunjukkan:

Bucket linear:

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

Contoh sebelumnya 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 membuat bucket berikut:

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

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

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

Contoh sebelumnya membuat bucket berikut:

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

Latensi metrik baru

Metrik baru Anda akan langsung muncul di 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 mencantumkan metrik berbasis log yang ditentukan pengguna di project Google Cloud atau untuk memeriksa metrik tertentu di project Google Cloud, lakukan hal berikut:

Konsol

  1. Di konsol Google Cloud, buka halaman Log-based Metrics:

    Buka Metrik Berbasis Log

    Jika Anda menggunakan kotak penelusuran untuk menemukan halaman ini, pilih hasil yang subjudulnya adalah Logging.

  2. Di panel Metrik yang ditentukan pengguna, Anda akan melihat metrik berbasis log yang ditentukan pengguna di project Google Cloud saat ini:

  3. Untuk melihat data dalam metrik berbasis log, klik Menu di baris metrik, lalu pilih Lihat di Metrics Explorer.

gcloud

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

gcloud logging metrics list

Untuk menampilkan metrik berbasis log yang ditentukan pengguna di 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 mencantumkan metrik berbasis log yang ditentukan pengguna di 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 cara menggunakan 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 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. Anda dapat menambahkan label baru ke metrik dan mengubah ekspresi reguler yang digunakan untuk mengekstrak nilai untuk 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 tindakan berikut:

Konsol

  1. Di konsol Google Cloud, buka halaman Log-based Metrics:

    Buka Metrik Berbasis Log

    Jika Anda menggunakan kotak penelusuran untuk menemukan halaman ini, pilih hasil yang subjudulnya adalah Logging.

  2. Klik Edit metric di Menu untuk metrik berbasis log yang ingin Anda ubah.

  3. Mengubah item yang diizinkan dalam metrik.

  4. Klik Perbarui metrik.

gcloud

Gunakan Google Cloud CLI untuk mengubah deskripsi metrik penghitung, kueri filter, dan bucket. 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 apa pun yang dikumpulkan sebelum perubahan tidak lagi mencerminkan konfigurasi saat ini. Data metrik yang dikumpulkan untuk bucket sebelumnya tidak akan dihapus.

Untuk memperbarui metrik distribusi atau kolom metrik penghitung lainnya, kecuali METRIC_NAME, buat file yang berisi spesifikasi revisi LogMetric dalam format JSON atau YAML. Kemudian, perbarui metrik dengan memanggil perintah update dengan kolom --config-from-file, yang 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.

Menghapus metrik distribusi

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

Konsol

  1. Di konsol Google Cloud, buka halaman Log-based Metrics:

    Buka Metrik Berbasis Log

    Jika Anda menggunakan kotak penelusuran untuk menemukan halaman ini, pilih hasil yang subjudulnya adalah Logging.

  2. Pilih metrik yang ingin dihapus, lalu klik Hapus.

    Atau, klik Hapus metrik di menu metrik berbasis log yang ingin Anda hapus.

gcloud

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

gcloud logging metrics delete METRIC_NAME

Untuk detail selengkapnya, gunakan perintah berikut:

gcloud logging metrics delete --help

API

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

Selain itu, di halaman Metrik berbasis log konsol Google Cloud, panel Metrik yang ditentukan pengguna di antarmuka metrik berbasis log menyediakan lebih banyak fitur untuk membantu Anda mengelola metrik yang ditentukan pengguna di project Google Cloud. Lihat Metrik yang ditentukan pengguna untuk mengetahui detailnya.