Mengonfigurasi metrik distribusi

Halaman ini menjelaskan cara membuat metrik berbasis log jenis distribusi menggunakan konsolGoogle 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 memiliki 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 secara terpisah, tetapi distribusinya di seluruh bucket yang dikonfigurasi dicatat, bersama dengan jumlah, rata-rata, dan jumlah deviasi kuadrat dari nilai. Anda dapat menggunakan tata letak default bucket histogram dalam distribusi atau menyesuaikan batas bucket untuk memperkirakan nilai yang akan diambil.

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

Sebelum memulai

  1. Untuk menggunakan metrik berbasis log, Anda harus memiliki Google Cloud project dengan penagihan 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.

    6. Pastikan peran Identity and Access Management Anda mencakup izin yang diperlukan untuk membuat dan melihat metrik berbasis log, serta untuk membuat kebijakan pemberitahuan. Untuk mengetahui detailnya, lihat Izin untuk metrik berbasis log.

      7. 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 memasukkan informasi sensitif dalam filter. Filter diperlakukan sebagai data layanan.

      Konsol

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

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

        Buka Log-based Metrics

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

      2. Klik Buat Metrik. Panel Buat metrik log 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 batasan penamaan berlaku; lihat Pemecahan masalah untuk mengetahui detailnya.
        • Deskripsi: Masukkan deskripsi untuk metrik.
        • Unit: (Opsional) Untuk metrik distribusi, Anda dapat secara opsional memasukkan unit, seperti s dan ms. Untuk mengetahui informasi selengkapnya, lihat kolom unit di MetricDescriptor.

      5. Tentukan filter metrik Anda di bagian Filter selection.

        1. Gunakan menu Pilih project atau bucket log untuk memilih apakah metrik menghitung entri log di project Anda atau hanya entri log tersebut di bucket log tertentu. Google Cloud

        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 Anda mengetik. Misalnya:

          protoPayload.latency

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

          ([0-9.]+)

          Tanda kurung, yang dikenal sebagai grup tangkapan regexp, mengidentifikasi bagian kecocokan 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 mengetahui informasi selengkapnya, lihat Bucket histogram di halaman ini.
        1. Untuk melihat entri log mana yang cocok dengan filter Anda, klik Pratinjau log.

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

      7. 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 Logging API. Jika Anda menggunakan panel APIs Explorer di halaman referensi, siapkan argumen sebagai berikut:

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

        • Untuk metrik berbasis log yang tercakup dalam 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 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 berupa DELTA. valueType harus berupa DISTRIBUTION.

      Bucket histogram

      Metrik distribusi mencakup histogram yang menghitung jumlah nilai yang berada dalam rentang (bucket) tertentu. 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 termasuk dalam lebih dari satu bucket, bucket mencakup batas bawahnya; batas atasnya termasuk dalam 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 yang lebih kecil dari batas pertama. Bucket terakhir adalah bucket luapan, 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. Dengan mengecualikan bucket underflow dan overflow, ada n-1 bucket berhingga.

      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. 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_factori, untuk i=0,1,2,...,N. Untuk mengetahui informasi selengkapnya tentang bucket eksponensial, lihat referensi API.

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

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

        Untuk mengetahui informasi selengkapnya tentang bucket eksplisit, lihat referensi API.

      Cara menentukan bucket histogram dijelaskan di bagian berikut:

      Konsol

      Submenu Bucket histogram terbuka saat Anda membuat metrik distribusi dan mengklik Lainnya di formulir Editor metrik. 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 terbatas 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 hingga yang dipisahkan koma. Hal ini juga menentukan jumlah bucket dan lebarnya.

      Misalnya, jika daftar batasnya 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)

      Kelompok eksponensial: Isi formulir kelompok 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. Nilainya harus lebih besar dari 1.

      Misalnya, jika N=4, a=3, dan b=2, maka 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 diberikan ke projects.metrics.create. Untuk objek LogMetric lengkap, lihat Membuat metrik distribusi di halaman ini. Penambahan untuk tata letak bucket adalah sebagai berikut:

      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 skala * 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 segera muncul dalam daftar metrik dan di menu Pemantauan yang relevan. Namun, mungkin diperlukan 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 Google Cloud project Anda atau untuk memeriksa metrik tertentu di Google Cloud project Anda, lakukan langkah berikut:

      Konsol

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

        Buka Log-based Metrics

        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 saat ini: Google Cloud

      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 Google Cloud project 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 dalam Google Cloud project, gunakan metode API projects.metrics.list. Isi parameter ke metode sebagai berikut:

      • parent: Nama resource Google Cloud project: projects/PROJECT_ID.
      • pageSize: Jumlah hasil maksimum.
      • pageToken: Mendapatkan halaman hasil berikutnya. Untuk mengetahui informasi tentang 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 Anda dapat 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 hal berikut:

      Konsol

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

        Buka Log-based Metrics

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

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

      3. Ubah item yang diizinkan dalam metrik.

      4. Klik Perbarui metrik.

      gcloud

      Gunakan Google Cloud CLI untuk mengubah deskripsi, kueri filter, dan bucket metrik penghitung. Anda dapat memperbarui 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 Anda dalam format JSON atau YAML. Kemudian, perbarui metrik dengan memanggil perintah update dengan kolom --config-from-file, mengganti FILENAME dengan nama file JSON atau YAML Anda:

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

      Untuk mengetahui 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 lengkap resource metrik:

        projects/PROJECT_ID/metrics/METRIC_ID

        Contoh:

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

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

      Menghapus metrik distribusi

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

      Konsol

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

        Buka Log-based Metrics

        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 mengetahui 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 di konsol Google Cloud , panel Metrik yang ditentukan pengguna pada antarmuka metrik berbasis log menyediakan lebih banyak fitur untuk membantu Anda mengelola metrik yang ditentukan pengguna di projectGoogle Cloud . Lihat Metrik yang ditentukan pengguna untuk mengetahui detailnya.