Menggunakan API

Dokumen ini menjelaskan cara mengelola layanan dan tujuan tingkat layanan (SLO) menggunakan Cloud Monitoring API.

Pemantauan Layanan menambahkan resource berikut ke Monitoring API:

Dokumen ini merujuk pada penambahan ini secara kolektif sebagai SLO API dan mengilustrasikan penggunaan utamanya. Untuk ringkasan umum struktur di SLO API, lihat Konstruksi di API. Materi referensi yang komprehensif muncul di bagian Cloud Monitoring API v3.

Anda dapat menggunakan SLO API untuk melakukan hal berikut:

  • Membuat dan mengelola layanan.

  • Buat tujuan tingkat layanan (SLO) berdasarkan indikator tingkat layanan (SLI) kustom atau standar untuk layanan Anda.

ID yang valid

Beberapa metode di SLO API menggunakan ID untuk berbagai elemen, terutama ID untuk project dan layanan. ID ini mematuhi aturan berikut:

  • Panjang: 1–63 karakter
  • Karakter: hanya huruf kecil, angka, dan tanda hubung
  • Karakter awal: huruf kecil
  • Karakter terminal: huruf kecil atau angka, tetapi bukan tanda hubung

Ekspresi reguler untuk aturan ini adalah sebagai berikut: [a-z](?:[-a-z0-9]{0,61}[a-z0-9])?

Contoh penggunaan curl

Bagian ini menjelaskan konvensi dan penyiapan yang digunakan untuk memanggil SLO API menggunakan alat curl. Jika menggunakan API ini melalui library klien, Anda dapat melewati bagian ini.

Contoh di halaman ini mengakses SLO API menggunakan alat curl untuk mengirim permintaan HTTP ke endpoint REST. Gunakan informasi berikut tentang autentikasi dan tentang pemanggilan curl untuk menetapkan variabel yang digunakan dalam pemanggilan.

Autentikasi

  1. Buat variabel lingkungan untuk menyimpan ID project cakupan metrik Anda: Contoh ini menggunakan PROJECT_ID:

    PROJECT_ID=my-test-service

  2. Lakukan autentikasi ke Google Cloud CLI:

    gcloud auth login

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

    gcloud config set project ${PROJECT_ID}

  4. Buat token otorisasi dan tangkap dalam variabel lingkungan. Contoh ini memanggil variabel ACCESS_TOKEN:

    ACCESS_TOKEN=`gcloud auth print-access-token`

    Anda harus memperbarui token akses secara berkala. Jika perintah yang berfungsi tiba-tiba melaporkan bahwa Anda tidak diautentikasi, terbitkan kembali perintah ini.

  5. Untuk memverifikasi bahwa Anda mendapatkan token akses, tampilkan variabel ACCESS_TOKEN:

    echo ${ACCESS_TOKEN}
ya29.GluiBj8o....

Memanggil curl

Setiap pemanggilan curl menyertakan kumpulan argumen, diikuti dengan URL resource SLO API. Argumen umum mencakup nilai yang ditentukan oleh variabel lingkungan PROJECT_ID dan ACCESS_TOKEN. Anda mungkin juga harus menentukan argumen lain, misalnya, untuk menentukan jenis permintaan HTTP (misalnya, -X DELETE). Permintaan default adalah GET, sehingga contoh tidak menentukannya.

Setiap pemanggilan curl memiliki struktur umum ini:

curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" <other_args> https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/<request>

Misalnya, untuk mencantumkan semua layanan dalam project Anda, berikan permintaan GET berikut:

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services

Permintaan ini menampilkan array deskripsi layanan, dengan entri seperti berikut, layanan beban kerja GKE dengan ID layanan “my-test-service”:

{
  "services": [
    {
      "name": "projects/PROJECT_NUMBER/services/my-test-service",
      "displayName": "My Test GKE Workload Service",
      "basicService": {
        "serviceType": "GKE_WORKLOAD",
        "serviceLabels": {
          "cluster_name": "workload-test",
          "location": "us-central1-c",
          "namespace_name": "kube-system",
          "project_id": "lesser-weevil",
          "top_level_controller_name": "gke-metrics-controller",
          "top_level_controller_type": "DaemonSet"
        }
      },
      "gkeWorkload": {
        "projectId": "lesser-weevil",
        "location": "us-central1-c",
        "clusterName": "workload-test",
        "namespaceName": "kube-system",
        "topLevelControllerType": "DaemonSet",
        "topLevelControllerName": "gke-metrics-controller"
      },
      "source": "USER",
      "telemetry": {
        "resourceName": "//container.googleapis.com/projects/PROJECT_ID/zones/us-central1-c/clusters/workload-test/k8s/namespaces/kube-system/apps/daemonsets/gke-metrics-controller"
      }
    },
   ...
  ]
}

Untuk melihat konfigurasi yang digunakan untuk membuat layanan ini, lihat Membuat layanan. Perhatikan bahwa struktur gkeWorkload dalam listingan ini berasal dari struktur basicService yang digunakan untuk membuat layanan. Lihat Service untuk mengetahui informasi selengkapnya tentang struktur layanan.

Mengelola layanan

Resource Service bertindak sebagai elemen root untuk mengatur layanan Anda. Aspek layanan tertentu, seperti SLO-nya, diatur berdasarkan nama layanan. Jenis layanan berikut didukung:

  • Layanan App Engine: APP_ENGINE
  • Layanan Cloud Endpoints: CLOUD_ENDPOINTS
  • Layanan Istio kanonis: ISTIO_CANONICAL_SERVICE
  • Layanan Istio cluster: CLUSTER_ISTIO
  • Layanan Cloud Run: CLOUD_RUN
  • Kumpulan layanan berbasis Google Kubernetes Engine:
    • Layanan GKE: GKE_SERVICE
    • Namespace GKE: GKE_NAMESPACE
    • Beban kerja GKE: GKE_WORKLOAD
  • Layanan kustom: CUSTOM

Untuk informasi selengkapnya, lihat Jenis layanan dasar atau Jenis layanan GKE dasar.

Anda dapat menambahkan SLO ke layanan apa pun di project menggunakan API. Mengelola SLO membahas perintah untuk memanipulasi SLO.

ID Layanan

Setiap layanan memiliki ID yang sepenuhnya memenuhi syarat yang disebut nama resource. ID ini disimpan di kolom name deskripsi layanan, misalnya:

"name": "projects/PROJECT_NUMBER/services/PROJECT_ID-zone-us-central1-a-cloudrun-istio-system-cluster-local-gateway",

Tersemat dalam nama resource adalah ID yang lebih pendek untuk layanan, bagian dari nama resource setelah substring projects/PROJECT_NUMBER/services/

Jika Anda membuat layanan sendiri dengan nama resource projects/PROJECT_NUMBER/services/my-test-service, ID layanannya adalah my-test-service.

Untuk singkat dan akurat, banyak contoh curl mengasumsikan bahwa ID layanan disimpan di variabel lingkungan SERVICE_ID sehingga Anda dapat merujuknya berulang kali.

Mencantumkan layanan

Untuk mengambil informasi tentang semua layanan dalam project Anda, panggil metode services.list. Untuk mengambil informasi tentang layanan tertentu berdasarkan ID layanan, gunakan metode services.get:

Protokol

Untuk mencantumkan informasi tentang layanan menggunakan curl, panggil metode services.list atau services.get dengan mengirimkan permintaan GET ke:

  • https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services untuk mencantumkan semua layanan
  • https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID untuk mendapatkan layanan tertentu

Misalnya, permintaan berikut mengambil informasi tentang layanan yang diidentifikasi oleh nilai yang disimpan dalam variabel lingkungan SERVICE_ID:

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}

Membuat service

Untuk membuat layanan, Anda menentukan representasi jenis layanan dan mengirimkannya ke metode services.create. Anda dapat menggunakan struktur jenis layanan yang dijelaskan dalam Jenis layanan dasar dan Jenis layanan GKE dasar.

Strukturnya bervariasi, tetapi proses untuk memanggil API sama. Anda harus menentukan nama tampilan untuk layanan dan kolom basicService yang menyimpan representasi layanan.

Secara opsional, Anda dapat menentukan ID layanan yang Anda inginkan untuk layanan tersebut. Contoh berikut menunjukkan pembuatan layanan beban kerja {[gke_name_short}}:

Protokol

Untuk membuat layanan menggunakan curl, kirim pesan POST ke endpoint https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services:

  1. Jika Anda ingin memberikan ID untuk layanan, buat variabel untuk ID layanan:

    SERVICE_ID=my-test-service

    Nilai ini diberikan dalam parameter kueri URL service_id.

  2. Buat variabel untuk menyimpan isi permintaan yang mendeskripsikan layanan:

    CREATE_SERVICE_POST_BODY=$(cat <<EOF
{
  "displayName": "My Test GKE Workload Service",
  "basicService": {
    "serviceType": "GKE_WORKLOAD",
    "serviceLabels": {
      "cluster_name": "workload-test",
      "location": "us-central1-c",
      "namespace_name": "kube-system",
      "project_id": "PROJECT_ID",
      "top_level_controller_name": "gke-metrics-controller",
      "top_level_controller_type": "DaemonSet"
    }
  }
}
EOF
)

  3. Posting isi permintaan ke endpoint, dan tentukan ID layanan sebagai nilai parameter kueri service_id:

    curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" --header "Content-Type: application/json" -X POST -d "${CREATE_SERVICE_POST_BODY}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services?service_id=${SERVICE_ID}

Untuk contoh struktur yang terkait dengan layanan lain, lihat Jenis layanan dasar atau Jenis layanan GKE dasar.

Menghapus layanan

Untuk menghapus layanan yang Anda buat, panggil metode services.delete dan tentukan ID layanan.

Protokol

Untuk menghapus layanan menggunakan curl, kirim permintaan DELETE ke endpoint https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID:

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" -X DELETE https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}

Mengelola SLO

Anda dapat membuat, menghapus, dan mengambil SLO menggunakan SLO API. Anda dapat memiliki hingga 500 SLO untuk setiap layanan.

Untuk mengelola SLO untuk layanan, Anda harus memiliki ID layanan. SLO diberi nama berdasarkan layanan yang terkait. Untuk informasi tentang cara mengidentifikasi ID layanan, lihat ID Layanan.

Mencantumkan SLO

Untuk mengambil informasi tentang semua SLO yang terkait dengan layanan, panggil metode services.serviceLevelObjectives.list. Untuk mengambil informasi tentang SLO tertentu berdasarkan nama, gunakan metode services.serviceLevelObjectives.get:

Protokol

Untuk mencantumkan informasi tentang layanan menggunakan curl, panggil metode services.serviceLevelObjectives.list atau services.serviceLevelObjectives.get dengan mengirimkan permintaan GET ke:

  • https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/[SERVICE_ID]/serviceLevelObjectives untuk mencantumkan semua SLO
  • https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/[SERVICE_ID]/serviceLevelObjectives/SLO_ID untuk mendapatkan SLO tertentu

Misalnya, permintaan berikut mencantumkan semua SLO yang terkait dengan ID layanan yang disimpan di variabel lingkungan SERVICE_ID:

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives

Berikut adalah SLO ketersediaan yang diambil dari layanan “currencyservice”: 

{
  "name": "projects/PROJECT_NUMBER/services/PROJECT_ID-zone-us-central1-c-csm-main-default-currencyservice/serviceLevelObjectives/3kavNVTtTMuzL7KcXAxqCQ",
  "displayName": "98% Availability in Calendar Week"
  "serviceLevelIndicator": {
    "basicSli": {
      "availability": {},
      "location": [
        "us-central1-c"
      ]
    }
  },
  "goal": 0.98,
  "calendarPeriod": "WEEK",
},

SLO ini dibuat berdasarkan SLI ketersediaan, menetapkan target performa sebesar 98 persen, dan mengukur kepatuhan selama satu minggu kalender. Untuk informasi selengkapnya tentang SLI ketersediaan, lihat Indikator tingkat layanan.

Lihat ServiceLevelObjective untuk mengetahui informasi selengkapnya tentang struktur SLO.

Mengambil SLO tertentu

Setiap SLO memiliki ID unik dalam layanan, yang terdiri dari string setelah serviceLevelObjectives di kolom name SLO. Dalam contoh berikut:

"name": "projects/PROJECT_NUMBER/services/PROJECT_ID-zone-us-central1-c-csm-main-default-currencyservice/serviceLevelObjectives/3kavNVTtTMuzL7KcXAxqCQ",

ID SLO adalah string 3kavNVTtTMuzL7KcXAxqCQ.

Untuk mengambil informasi tentang SLO tertentu ini, minta SLO berdasarkan ID.

Protokol

Untuk mendapatkan SLO tertentu menggunakan curl, panggil metode services.serviceLevelObjectives.get dengan mengirim permintaan GET ke https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives/SLO_ID:

SLO_ID=dhefHDM4TwSRZEKIV4ZYEg

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives/${SLO_ID}

Membuat SLO

Untuk membuat SLO menggunakan SLO API, Anda harus membuat objek ServiceLevelObjective dan meneruskannya ke metode serviceLevelObjectives.create.

Struktur SLO memiliki banyak struktur tersemat, termasuk satu untuk nilai kolom serviceLevelIndicator.

  • Untuk layanan Cloud Service Mesh, Istio di Google Kubernetes Engine, dan App Engine, SLI telah ditentukan sebelumnya. Anda dapat menggunakan konsol Cloud Service Mesh untuk membuat SLO; yang harus Anda lakukan hanyalah menentukan sasaran performa dan periode kepatuhan.

  • Untuk layanan lain, Anda harus menentukan SLO menggunakan SLO API. Untuk menentukan SLO, Anda juga harus membuat nilai untuk kolom serviceLevelIndicator. Lihat Membuat indikator tingkat layanan untuk mengetahui beberapa teknik, dan Membuat SLI dari metrik untuk mengetahui kumpulan contoh berdasarkan berbagai sumber.

Anda juga dapat membuat SLI menggunakan konsol Google Cloud. Untuk mengetahui informasi selengkapnya, lihat Membuat SLO.

Kerangka SLO

Kerangka dasar untuk membuat SLO adalah sebagai berikut:

{
  "displayName": string,
  "serviceLevelIndicator": {
    object (ServiceLevelIndicator)
  },
  "goal": number,

  // Union field period can be only one of the following:
  "rollingPeriod": string,
  "calendarPeriod": enum (CalendarPeriod)
  // End of list of possible types for union field period.
}

Anda harus menentukan hal berikut:

  • Nama tampilan: deskripsi SLO
  • Indikator tingkat layanan, yang merupakan salah satu dari tiga jenis:
  • Sasaran performa (persentase)
  • Periode kepatuhan, yang terdiri dari dua jenis:
    • Periode rolling dengan durasi tertentu (dalam detik)
    • Periode kalender

Untuk mengetahui informasi selengkapnya tentang SLI, sasaran performa, dan periode kepatuhan, lihat Konsep dalam pemantauan layanan.

Untuk layanan Cloud Service Mesh, Istio di Google Kubernetes Engine, dan App Engine, jenis SLI adalah SLI dasar.

Untuk layanan lainnya, Anda harus membuat SLI berbasis permintaan atau SLI berbasis jendela. Lihat Membuat indikator tingkat layanan untuk mengetahui beberapa teknik.

Contoh

Setelah memiliki SLI, Anda dapat membuat SLO. Contoh berikut menentukan SLO untuk layanan yang menggunakan SLI dasar. Anda mungkin memiliki beberapa SLO pada satu SLI, misalnya, satu untuk ketersediaan 95% dan satu untuk ketersediaan 99%. Contoh berikut adalah SLO untuk ketersediaan 95% selama satu minggu kalender: 

{
  "serviceLevelIndicator": {
    "basicSli": {
      "availability": {},
      "location": [
        "us-central1-c"
      ]
    }
  },
  "goal": 0.95,
  "calendarPeriod": "WEEK",
  "displayName": "95% Availability in Calendar Week"
}

Contoh ini menentukan SLO untuk ketersediaan 75% selama periode 3 hari bergulir: 

{
  "serviceLevelIndicator": {
    "basicSli": {
      "availability": {},
      "location": [
        "us-central1-c"
      ]
    }
  },
  "goal": 0.75,
  "rollingPeriod": "259200s",
  "displayName": "75% Availability in Rolling 3 Days"
}

Protokol

Untuk membuat SLO menggunakan curl, kirim pesan POST ke endpoint https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives:

  1. Buat variabel untuk ID layanan:

    SERVICE_ID=custom:my-test-service

  2. Buat variabel untuk menyimpan isi permintaan, instance objek ServiceLevelObjective. Contoh ini menggunakan salah satu SLO yang dijelaskan sebelumnya:

    CREATE_SLO_POST_BODY=$(cat <<EOF
{
  "serviceLevelIndicator": {
    "basicSli": {
      "availability": {},
      "location": [
        "us-central1-c"
      ]
    }
  },
  "goal": 0.75,
  "rollingPeriod": "259200s",
  "displayName": "75% Availability in Rolling 3 Days"
}
EOF
)

  3. Posting isi permintaan ke endpoint:

    curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" --header "Content-Type: application/json" -X POST -d "${CREATE_SLO_POST_BODY}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives

    Secara opsional, Anda juga dapat menentukan ID yang diinginkan untuk SLO sebagai nilai parameter kueri service_level_objective_id:

    SLO_ID=test-slo-id

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" --header "Content-Type: application/json" -X POST -d "${CREATE_SLO_POST_BODY}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives?service_level_objective_id=${SLO_ID}

Menghapus SLO

Untuk menghapus SLO, panggil metode services.serviceLevelObjectives.delete dan tentukan ID SLO di project Anda:

Protokol

Untuk menghapus SLO menggunakan curl, kirim permintaan DELETE ke endpoint https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives/SLO_ID:

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" -X DELETE https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives/${SLO_ID}

Mengakses deret waktu SLO

Data SLO disimpan dalam deret waktu, sehingga Anda dapat menggunakan metode timeSeries.list untuk mengambilnya. Namun, data ini tidak disimpan dalam jenis metrik standar, sehingga Anda tidak dapat menggunakan mekanisme standar untuk menentukan filter jenis metrik ke metode timeSeries.list.

Sebagai gantinya, deret waktu SLO diambil dengan menentukan jenis filter lain, yaitu pemilih deret waktu, ke metode timeSeries.list dalam parameter filter. Lihat Mengambil data SLO untuk mengetahui informasi tentang penggunaan pemilih ini.

Anda juga menggunakan pemilih deret waktu untuk menyiapkan kebijakan pemberitahuan secara terprogram. Lihat Memberi pemberitahuan tentang laju pengeluaran untuk mengetahui informasi selengkapnya.