Menggunakan API

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

Service Monitoring menambahkan resource berikut ke Monitoring API:

Dokumen ini mengacu pada penambahan ini secara kolektif sebagai SLO API dan menggambarkan penggunaan utama. Untuk ringkasan umum tentang struktur di SLO API, lihat Membuat di API. Materi referensi yang komprehensif ada 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 yang telah ditetapkan untuk setiap layanan Anda.

ID yang valid

Beberapa metode di SLO API menggunakan ID untuk elemen yang berbeda, 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 yang menggunakan `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 dengan menggunakan alat curl untuk mengirim permintaan HTTP ke endpoint REST. Gunakan informasi berikut tentang autentikasi dan cara memanggil curl untuk menetapkan variabel yang digunakan dalam pemanggilan.

Authentication

Buat variabel lingkungan untuk menyimpan ID project cakupan Anda dari cakupan metrik: Contoh ini menggunakan PROJECT_ID:
```
PROJECT_ID=my-test-service
```
Lakukan autentikasi ke Google Cloud CLI:
```
gcloud auth login
```
Agar tidak perlu menentukan project ID dengan setiap perintah, tetapkan project ID sebagai default menggunakan gcloud CLI:
```
gcloud config set project ${PROJECT_ID}
```
Buat token otorisasi dan simpan 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, keluarkan kembali perintah ini.
Untuk memverifikasi bahwa Anda mendapatkan token akses, lakukan echo variabel ACCESS_TOKEN:
```
echo ${ACCESS_TOKEN}
ya29.GluiBj8o....
```

Memanggil `curl`

Setiap pemanggilan curl menyertakan sekumpulan 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 defaultnya adalah GET, jadi contoh tidak menentukannya.

Setiap panggilan curl memiliki struktur umum berikut:

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 workload 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 khusus: CUSTOM

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

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

ID Layanan

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

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

Yang 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.

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

Layanan listingan

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:

Protocol

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 tersimpan 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, tentukan representasi jenis layanan, lalu kirimkan ke metode services.create. Anda dapat mempelajari 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 berisi representasi layanan.

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

Protocol

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

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.

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
)

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.

Protocol

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 layanannya. Untuk informasi tentang 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:

Protocol

Untuk mencantumkan informasi tentang layanan menggunakan curl, panggil metode services.serviceLevelObjectives.list atau services.serviceLevelObjectives.get dengan mengirim 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, yang menetapkan sasaran performa target sebesar 98 persen, dan mengukur kepatuhan selama satu minggu kalender. Untuk mengetahui informasi selengkapnya tentang SLI ketersediaan, lihat Indikator tingkat layanan.

Lihat ServiceLevelObjective untuk mengetahui informasi selengkapnya mengenai struktur SLO.

Mengambil SLO tertentu

Setiap SLO memiliki ID unik dalam layanan, yang terdiri dari string mengikuti 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 khusus ini, minta SLO berdasarkan ID.

Protocol

Untuk mendapatkan SLO tertentu menggunakan curl, panggil metode services.serviceLevelObjectives.get dengan mengirimkan 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.

SLI sudah ditetapkan untuk layanan Anthos Service Mesh, Istio di Google Kubernetes Engine, dan App Engine. Anda dapat menggunakan konsol Anthos Service Mesh untuk membuat SLO; yang harus Anda lakukan adalah menentukan sasaran performa dan periode kepatuhan.
Untuk layanan lainnya, Anda harus menentukan SLO dengan menggunakan SLO API. Untuk menentukan SLO, Anda juga harus membuat nilai untuk kolom serviceLevelIndicator. Lihat Membuat indikator tingkat layanan untuk beberapa teknik, dan Membuat SLI dari metrik untuk sekumpulan contoh berdasarkan berbagai sumber.

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

Kerangka SLO

Kerangka dasar untuk membangun 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 berikut:
Sasaran performa (persentase)
Periode kepatuhan, yang mana salah satu dari dua jenis berikut:
- Periode bergulir 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 Anthos Service Mesh, Istio di Google Kubernetes Engine, dan App Engine, jenis SLI-nya adalah SLI dasar.

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

Contoh

Setelah memiliki SLI, Anda dapat mem-build SLO. Contoh berikut menentukan SLO untuk layanan yang menggunakan SLI dasar. Anda mungkin memiliki beberapa SLO pada satu SLI, misalnya satu SLO untuk ketersediaan 95% dan satu lagi 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 yang berkelanjutan:

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

Protocol

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

Buat variabel untuk ID layanan:
```
SERVICE_ID=custom:my-test-service
```

Buat variabel untuk menyimpan isi permintaan, yaitu 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
)

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 dari 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:

Protocol

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 lainnya, pemilih deret waktu, ke metode timeSeries.list di parameter filter. Lihat Mengambil data SLO untuk mengetahui informasi tentang cara menggunakan pemilih ini.

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

Menggunakan API

ID yang valid

Contoh yang menggunakan curl

Authentication

Memanggil curl

Mengelola layanan

ID Layanan

Layanan listingan

Protocol

Membuat service

Protocol

Menghapus layanan

Protocol

Mengelola SLO

Mencantumkan SLO

Protocol

Mengambil SLO tertentu

Protocol

Membuat SLO

Kerangka SLO

Contoh

Protocol

Menghapus SLO

Protocol

Mengakses deret waktu SLO

Contoh yang menggunakan `curl`

Memanggil `curl`