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 penampung resource dapat berupa organisasi, folder, atau project, perintah yang dijelaskan di halaman ini hanya mendukung project Google Cloud.

Sebelum memulai

  • Jika Anda belum terbiasa dengan istilah cakupan metrik dan project cakupan, baca Cakupan metrik.

  • Pastikan peran Identity and Access Management (IAM) Anda di project pencakupan 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 pada Cloud Monitoring API yang mengambil informasi bersifat sinkron; namun, API yang mengubah status bersifat asinkron. Perintah Google Cloud CLI melakukan pemblokiran hingga operasi asinkron selesai. Untuk 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 ingin menggunakan contoh di halaman ini, selesaikan langkah-langkah penyiapan perintah curl.

Mencantumkan semua cakupan metrik yang mencakup project

gcloud

Untuk mendapatkan daftar cakupan metrik yang dapat melihat metrik untuk penampung 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 mencantumkan cakupan metrik yang mencakup 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 yang ditulis ke log audit project pencakupan. Agar tindakan ini dicatat dalam log audit, aktifkan Pembacaan Data untuk Cloud Resource Manager API. Untuk mengetahui 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 yang sepenuhnya memenuhi syarat dari cakupan metrik ke dalam variabel METRICS_SCOPE_ID. Berikut contoh nama yang sepenuhnya memenuhi syarat:

locations/global/metricsScopes/012345012345

Berikut adalah contoh respons. Dalam contoh ini, cakupan metrik berisi satu project, sedangkan 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 yang ditulis ke log audit project pencakupan. Agar tindakan ini dicatat dalam log audit, aktifkan Pembacaan Data untuk Cloud Resource Manager API. Untuk mengetahui 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 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 penampung 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 atas 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. Dalam 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 saat menambahkan project yang dipantau berhasil:

{
  "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 ditetapkan 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.

Memanggil metode ini akan menghasilkan entri dalam log audit project pencakupan. Konsol Google Cloud tidak memanggil metode API ini. Oleh karena itu, perubahan yang dilakukan 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 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 penampung 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 atas 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 ditetapkan ke true. Nilai ini menunjukkan bahwa perintah selesai. Karena perintah berhasil diselesaikan, kolom Operation.response ditetapkan dan berisi kolom @type.

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

Metode API asinkron

Semua metode cakupan metrik pada Cloud Monitoring API yang mengubah status sistem, misalnya, perintah untuk menambahkan cakupan metrik pada project yang dipantau, 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 memuat ulang informasi status, kirim permintaan GET ke endpoint operation.get:

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

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

  • Jika done adalah true, operasi akan 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>

Tetapkan variabel lingkungan berikut 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, konfigurasi 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 sebagai default dengan menggunakan gcloud CLI:

    gcloud config set project ${SCOPING_PROJECT_ID_OR_NUMBER}
    
  5. Buat token otorisasi dan simpan dalam variabel lingkungan:

    TOKEN=`gcloud auth print-access-token`
    

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

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

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

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

Langkah selanjutnya

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