Mengonfigurasi cakupan metrik menggunakan API

Dokumen ini menjelaskan cara menggunakan Google Cloud CLI atau Cloud Monitoring API untuk mengonfigurasi cakupan metrik project Google Cloud. Halaman ini ditujukan untuk developer dan administrator sistem.

Perintah di halaman ini merujuk pada "container resource". Meskipun container resource dapat berupa organisasi, folder, atau project, perintah yang dijelaskan di halaman ini hanya mendukung project Google Cloud.

Sebelum memulai

  • Jika Anda belum memahami istilah cakupan metrik dan project pencakupan, lihat Cakupan metrik.

  • Pastikan peran Identity and Access Management (IAM) Anda di project cakupan dan pada setiap project yang ingin Anda tambahkan sebagai project yang dipantau menyertakan semua izin dalam peran Monitoring Admin (roles/monitoring.admin). Untuk informasi selengkapnya, lihat Konfigurasi cakupan metrik.

  • Metode cakupan metrik Cloud Monitoring API yang mengambil informasi bersifat sinkron; tetapi, API yang mengubah status tersebut bersifat asinkron. Perintah Google Cloud CLI akan melakukan pemblokiran hingga operasi asinkron selesai. Untuk mengetahui informasi tentang cara menentukan kapan metode API asinkron selesai dan cara menentukan statusnya, lihat Metode API asinkron.

  • Jika Anda berencana memanggil Cloud Monitoring API menggunakan curl atau jika Anda ingin menggunakan contoh di halaman ini, selesaikan langkah-langkah penyiapan perintah curl.

Mencantumkan semua cakupan metrik yang menyertakan project

gcloud

Untuk mendapatkan daftar cakupan metrik yang dapat melihat metrik untuk container resource, seperti project Google Cloud, jalankan perintah gcloud beta monitoring metrics-scopes list:

gcloud beta monitoring metrics-scopes list MONITORED_RESOURCE_CONTAINER_NAME

Sebelum menjalankan perintah, masukkan ID container resource ke dalam variabel MONITORED_RESOURCE_CONTAINER_NAME. Jika penampung resource adalah project Google Cloud, masukkan projects/PROJECT_ID_OR_NUMBER.

Misalnya, untuk menampilkan daftar cakupan metrik yang menyertakan project my-project, jalankan perintah berikut:

gcloud beta monitoring metrics-scopes list projects/my-project

Respons berikut menunjukkan bahwa project my-project disertakan dalam dua cakupan metrik:

metricsScopes:
- createTime: '2018-08-06T17:13:42Z'
  name: locations/global/metricsScopes/012345012345
  updateTime: '2018-08-18T16:20:37.032928Z'
- createTime: '2021-04-13T15:37:26.869Z'
  name: locations/global/metricsScopes/9876543210
  updateTime: '2021-04-13T15:37:27.284239Z'

Untuk mendapatkan informasi mendetail tentang cakupan metrik, jalankan perintah gcloud beta monitoring metrics-scopes describe.

curl

Untuk mendapatkan daftar cakupan metrik yang dapat melihat metrik untuk sebuah project, kirim permintaan GET ke endpoint locations.global.metricsScopes.listMetricsScopesByMonitoredProject dan sertakan parameter kueri yang menentukan project.

curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes:listMetricsScopesByMonitoredProject?monitored_resource_container=projects/${PROJECT_ID_OR_NUMBER}

Jika berhasil, responsnya adalah array objek MetricsScope.

Metode ini tidak menyebabkan entri ditulis ke log audit project pencakupan. Agar tindakan ini dicatat di log audit, aktifkan Pembacaan Data untuk Cloud Resource Manager API. Untuk informasi selengkapnya, lihat Mengonfigurasi log audit Akses Data.

Mendapatkan detail tentang cakupan metrik

gcloud

Untuk mendapatkan informasi mendetail tentang cakupan metrik, jalankan perintah gcloud beta monitoring metrics-scopes describe:

gcloud beta monitoring metrics-scopes describe METRICS_SCOPE_ID

Sebelum menjalankan perintah, masukkan nama cakupan metrik yang sepenuhnya memenuhi syarat ke dalam variabel METRICS_SCOPE_ID. Berikut adalah contoh nama yang sepenuhnya memenuhi syarat:

locations/global/metricsScopes/012345012345

Berikut adalah contoh respons. Dalam contoh ini, cakupan metrik berisi satu project, dan ID cakupan metrik dan project adalah sama:

createTime: '2018-08-06T17:13:42Z'
monitoredProjects:
- createTime: '2018-08-06T17:13:42Z'
  name: locations/global/metricsScopes/012345012345/projects/012345012345
name: locations/global/metricsScopes/012345012345
updateTime: '2018-08-18T16:20:37.032928Z'

Untuk mengidentifikasi project Google Cloud dari ID-nya, jalankan perintah gcloud projects list dan filter menurut project ID. Misalnya, untuk mendapatkan nama project 012345012345, jalankan perintah berikut:

gcloud projects list --filter="012345012345" -format="value(NAME)"

curl

Untuk mendapatkan informasi tentang cakupan metrik, kirim permintaan GET ke endpoint locations.global.metricsScopes.get:

curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}

Jika berhasil, responsnya adalah objek MetricsScope.

Metode ini tidak menyebabkan entri ditulis ke log audit project pencakupan. Agar tindakan ini dicatat di log audit, aktifkan Pembacaan Data untuk Cloud Resource Manager API. Untuk informasi selengkapnya, lihat Mengonfigurasi log audit Akses Data.

Menambahkan project ke cakupan metrik

gcloud

Untuk menambahkan container resource, seperti project Google Cloud, ke cakupan metrik, jalankan perintah gcloud beta monitoring metrics-scopes create:

gcloud beta monitoring metrics-scopes create MONITORED_RESOURCE_CONTAINER_NAME --project=SCOPING_PROJECT_ID_OR_NUMBER

Sebelum Anda menjalankan perintah sebelumnya, lakukan hal berikut:

  • Masukkan nama atau ID project Google Cloud yang cakupan metriknya akan diubah menjadi variabel SCOPING_PROJECT_ID_OR_NUMBER.

  • Masukkan ID penampung resource Anda ke dalam variabel MONITORED_RESOURCE_CONTAINER_NAME. Jika container resource adalah project Google Cloud, masukkan projects/PROJECT_ID_OR_NUMBER.

Misalnya, perintah berikut akan menambahkan project my-monitored-project ke cakupan metrik project bernama my-staging-projects:

gcloud beta monitoring metrics-scopes create projects/my-monitored-project --project=my-staging-projects

Respons terhadap perintah sebelumnya memberikan konfirmasi bahwa perintah berhasil diselesaikan:

Created monitored project [locations/global/metricsScopes/my-staging-projects/projects/my-monitored-project].

curl

Untuk menambahkan project Google Cloud ke cakupan metrik, kirim permintaan POST ke endpoint locations.global.metricsScopes.projects.create. Pada contoh berikut, project yang diidentifikasi oleh variabel lingkungan MONITORED_PROJECT_ID_OR_NUMBER ditambahkan sebagai project yang dipantau:

curl -H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" -X POST \
-d "{'name': 'locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects/${MONITORED_PROJECT_ID_OR_NUMBER}'}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects

Respons metode asinkron ini adalah objek Operation.

Aplikasi yang memanggil metode ini harus melakukan polling endpoint operation.get hingga nilai kolom Operation.done adalah true. Jika kolom Operation.done ditetapkan ke false, berarti operasi sedang berlangsung. Untuk mengetahui informasi selengkapnya, lihat Perintah API asinkron.

Berikut adalah contoh respons ketika berhasil menambahkan project yang dipantau:

{
  "name": "operations/6915efde-1915-400a-ad49-7b62041d9bd2",
  "metadata": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.OperationMetadata",
    "state": "DONE",
    ...
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.MonitoredProject",
    "name": "locations/global/metricsScopes/012012012012/projects/678678678678",
    "provider": "G​C​P",
    "providerAccountId": "...",
    ...
  }
}

Pada respons sebelumnya, kolom Operation.done disetel ke true. Nilai ini menunjukkan bahwa perintah selesai. Karena perintah berhasil diselesaikan, kolom Operation.response ditetapkan dan nilainya adalah objek MonitoredProject. Kolom response.name berisi ID project pencakupan dan project yang dipantau. Kolom providerAccountId mencantumkan nama project yang dipantau.

Pemanggilan metode ini akan menghasilkan entri dalam log audit project pencakupan. Konsol Google Cloud tidak memanggil metode API ini. Oleh karena itu, perubahan yang dibuat pada cakupan metrik saat menggunakan Konsol Google Cloud tidak dicatat dalam log audit.

Menghapus project dari cakupan metrik

gcloud

Untuk menghapus container resource, seperti project Google Cloud, dari cakupan metrik, jalankan perintah gcloud beta monitoring metrics-scopes delete:

gcloud beta monitoring metrics-scopes delete MONITORED_RESOURCE_CONTAINER_NAME --project=SCOPING_PROJECT_ID_OR_NUMBER

Sebelum Anda menjalankan perintah sebelumnya, lakukan hal berikut:

  • Masukkan nama atau ID project Google Cloud yang cakupan metriknya akan diubah menjadi variabel SCOPING_PROJECT_ID_OR_NUMBER.

  • Masukkan ID penampung resource Anda ke dalam variabel MONITORED_RESOURCE_CONTAINER_NAME. Jika container resource adalah project Google Cloud, masukkan projects/PROJECT_ID_OR_NUMBER.

Misalnya, perintah berikut akan menghapus project my-monitored-project dari cakupan metrik project bernama my-staging-projects:

gcloud beta monitoring metrics-scopes delete projects/my-monitored-project --project=my-staging-projects

Respons terhadap perintah sebelumnya memberikan konfirmasi bahwa perintah berhasil diselesaikan:

Deleted monitored project [locations/global/metricsScopes/my-staging-projects/projects/my-monitored-project].

Error berikut dilaporkan saat project pencakupan tidak memantau project yang ditentukan oleh variabel MONITORED_RESOURCE_CONTAINER_NAME:

NOT_FOUND: Requested entity was not found.

curl

Untuk menghapus project Google Cloud dari cakupan metrik, kirim permintaan DELETE ke endpoint locations.global.metricsScopes.projects.delete:

curl -H "Authorization: Bearer ${TOKEN}" -X DELETE \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects/${MONITORED_PROJECT_ID_OR_NUMBER}

Respons terhadap metode asinkron ini adalah objek Operation.

Aplikasi yang memanggil metode ini harus melakukan polling endpoint operation.get hingga nilai kolom Operation.done adalah true. Jika kolom Operation.done ditetapkan ke false, berarti operasi sedang berlangsung. Untuk mengetahui informasi selengkapnya, lihat Perintah API asinkron.

Berikut adalah contoh respons saat penghapusan project yang dipantau berhasil:

{
  "name": "operations/4367ff34-0ff0-4767-b8d3-0638e30f077c",
  "metadata": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.OperationMetadata",
    "state": "DONE",
    ...
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

Pada respons sebelumnya, kolom Operation.done disetel ke true. Nilai ini menunjukkan bahwa perintah selesai. Karena perintah berhasil diselesaikan, kolom Operation.response akan ditetapkan dan berisi kolom @type.

Pemanggilan metode ini akan menghasilkan entri dalam log audit project pencakupan. Konsol Google Cloud tidak memanggil metode API ini. Oleh karena itu, perubahan yang dibuat pada cakupan metrik saat menggunakan Konsol Google Cloud tidak dicatat dalam log audit.

Metode API asinkron

Semua metode cakupan metrik Cloud Monitoring API yang mengubah status sistem, misalnya, perintah untuk menambahkan project yang dipantau dengan cakupan metrik, bersifat asinkron. Untuk perintah ini, respons perintahnya adalah objek Operation.

Aplikasi yang memanggil metode API asinkron harus melakukan polling endpoint operation.get hingga nilai kolom Operation.done adalah true:

  • Ketika done adalah false, operasi sedang berlangsung.

    Untuk memperbarui informasi status, kirim permintaan GET ke endpoint operation.get:

    curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/${OPERATION_NAME}

    Di perintah sebelumnya, OPERATION_NAME adalah variabel lingkungan yang menyimpan nilai kolom Operation.name.

  • Jika done adalah true, berarti operasinya sudah selesai dan kolom error atau response ditetapkan:

    • error: Jika ditetapkan, operasi asinkron akan gagal. Nilai kolom ini adalah objek Status yang berisi kode error gRPC dan pesan error.
    • response: Jika ditetapkan, operasi asinkron berhasil diselesaikan, dan nilai mencerminkan hasilnya.

Penyiapan perintah curl

Bagian ini menjelaskan penyiapan yang digunakan untuk membuat perintah curl dalam dokumen ini. Setiap perintah curl di halaman ini menyertakan sekumpulan argumen yang diikuti dengan URL resource API:

curl -H "Authorization: Bearer ${TOKEN}" <other_args> \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/<resource>

Setel variabel lingkungan ini untuk menyederhanakan pembuatan perintah curl:

  1. Buat variabel lingkungan untuk menyimpan ID atau nomor project pencakupan:

    SCOPING_PROJECT_ID_OR_NUMBER=SCOPING_PROJECT_ID_OR_NUMBER

  2. Opsional. Jika Anda berencana untuk menambahkan atau menghapus project yang dipantau, konfigurasikan variabel lingkungan dengan ID atau nomor project yang dipantau:

    MONITORED_PROJECT_ID_OR_NUMBER=MONITORED_PROJECT_ID_OR_NUMBER

  3. Lakukan autentikasi ke Google Cloud CLI:

    gcloud auth login

  4. Opsional. Agar tidak perlu menentukan project ID dengan setiap perintah gcloud, tetapkan project ID Anda sebagai default menggunakan gcloud CLI:

    gcloud config set project ${SCOPING_PROJECT_ID_OR_NUMBER}

  5. Buat token otorisasi dan rekam dalam variabel lingkungan:

    TOKEN=`gcloud auth print-access-token`

    Token berlaku dalam waktu yang terbatas. Jika perintah yang berfungsi tiba-tiba melaporkan bahwa Anda tidak diautentikasi, kirimkan ulang perintah ini.

  6. Untuk memverifikasi bahwa Anda mendapatkan token akses, echo variabel TOKEN:

    echo ${TOKEN}
ya29.GluiBj8o....

Anda mungkin juga harus menentukan argumen lain, misalnya, untuk menentukan jenis permintaan HTTP (misalnya, -X DELETE). Permintaan default-nya adalah GET, sehingga contoh-contoh tersebut tidak menentukannya.

Langkah selanjutnya

Untuk mendapatkan informasi tentang cara menggunakan Google Cloud dengan Terraform, lihat referensi berikut: