API の操作

このドキュメントでは、Cloud Monitoring API を使用してサービスとサービスレベル目標（SLO）を管理する方法について説明します。

Service Monitoring は、Monitoring API に次のリソースを追加します。

このドキュメントでは、このような追加機能を総称して SLO API と呼び、主な用途について説明します。SLO API の構造の概要については、API による構築をご覧ください。包括的な参考資料は Cloud Monitoring API v3 の下にあります。

SLO API を使用すると、次のことができます。

サービスを作成および管理する。
任意のサービスのカスタムまたは事前定義のサービスレベル指標（SLI）に基づいて、サービスレベル目標（SLO）を作成する。

有効な ID

SLO API の複数のメソッドは、異なる要素の ID、特にプロジェクトとサービスの ID を使用します。これらの ID は次のルールに準拠します。

長さ: 1～63 文字
文字: 小文字、数字、ハイフンのみ
最初の文字: 小文字
最後の文字: 小文字または数字のいずれか（ハイフンは不可）

これらのルールの正規表現は次のとおりです。[a-z](?:[-a-z0-9]{0,61}[a-z0-9])?

`curl` の使用例

このセクションでは、curl ツールを使用して SLO API を呼び出すための規則と設定について説明します。クライアントライブラリからこの API を使用している場合は、このセクションをスキップできます。

このページの例では、curl ツールを使用して SLO API にアクセスし、HTTP リクエストを REST エンドポイントに送信します。認証と curl の呼び出しに関する次の情報を使用して、呼び出しで使用される変数を設定します。

認証

指標スコープのスコーププロジェクトの ID を保持する環境変数を作成します。次の例では PROJECT_ID を使用します。
```
PROJECT_ID=my-test-service
```
Google Cloud CLI に対して認証を行います。
```
gcloud auth login
```
各コマンドでのプロジェクト ID の指定を不要にするには、gcloud CLI を使用してプロジェクト ID をデフォルトとして設定します。
```
gcloud config set project ${PROJECT_ID}
```
認証トークンを作成し、環境変数にキャプチャします。次の例では変数 ACCESS_TOKEN を呼び出しています。
```
ACCESS_TOKEN=`gcloud auth print-access-token`
```
アクセストークンは定期的に更新する必要があります。動作していたコマンドに急に未認証と報告された場合は、このコマンドを再発行します。
アクセストークンがあることを確認するには、ACCESS_TOKEN 変数をエコーします。
```
echo ${ACCESS_TOKEN}
ya29.GluiBj8o....
```

`curl` の呼び出し

各 curl 呼び出しには、一連の引数が含まれ、SLO API リソースの URL がそれに続きます。一般的な引数には、PROJECT_ID および ACCESS_TOKEN 環境変数で指定された値があります。HTTP リクエストのタイプ（たとえば、-X DELETE）を指定する場合など、他の引数を指定する必要がある場合もあります。デフォルトのリクエストは GET であるため、例では指定していません。

各 curl 呼び出しは、次の一般的な構造をしています。

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

たとえば、プロジェクト内のすべてのサービスを一覧表示するには、次の GET リクエストを発行します。

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

このリクエストでは、次のようなサービスの説明の配列が返されます。サービス ID が「my-test-service」の GKE ワークロードサービスが表示されます。

{
  "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"
      }
    },
   ...
  ]
}

このサービスの作成に使用される構成を確認するには、サービスの作成をご覧ください。このリスティングの gkeWorkload 構造は、サービスの作成に使用される basicService 構造から派生しています。サービスの構造についての詳細は、Service をご覧ください。

サービスの管理

Service リソースは、サービスを編成するためのルート要素として機能します。たとえば、SLO などの特定のサービスのアスペクトは、サービスの名前ごとに編成されます。次のサービスタイプがサポートされています。

App Engine サービス: APP_ENGINE
Cloud Endpoints サービス: CLOUD_ENDPOINTS
Istio Canonical サービス: ISTIO_CANONICAL_SERVICE
クラスタ Istio サービス: CLUSTER_ISTIO
Cloud Run サービス: CLOUD_RUN
Google Kubernetes Engine ベースの一連のサービス:
- GKE サービス: GKE_SERVICE
- GKE Namespace: GKE_NAMESPACE
- GKE ワークロード: GKE_WORKLOAD
カスタムサービス: CUSTOM

詳細については、基本的なサービスタイプまたは基本的な GKE サービスタイプをご覧ください。

API を使用して、プロジェクトの任意のサービスに SLO を追加できます。SLO の管理では、SLO を操作するコマンドについて説明します。

サービス ID

各サービスには、リソース名という完全修飾された ID があります。この ID は次の例のように、サービスの説明の name フィールドに格納されています。

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

リソース名に埋め込まれているのは、短縮されたサービス ID で、部分文字列 projects/PROJECT_NUMBER/services/ の後のリソース名の一部がそのサービス ID にあたります。

リソース名 projects/PROJECT_NUMBER/services/my-test-service の独自のサービスを作成した場合、サービス ID は my-test-service です。

簡潔さおよび正確性を目的として、多くの curl の例ではサービス ID が環境変数 SERVICE_ID に保持されていることを前提としているため、繰り返し参照できます。

サービスの一覧表示

プロジェクト内のすべてのサービスに関する情報を取得するには、services.list メソッドを呼び出します。特定のサービスに関する情報をサービス ID 別に取得するには、services.get メソッドを使用します。

プロトコル

curl を使用してサービスに関する情報を一覧取得するには、GET リクエストを送り、services.list または services.get メソッドを呼び出します。

https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services はすべてのサービスを一覧表示する
https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID は特定のサービスを取得する

たとえば、次のリクエストは、環境変数 SERVICE_ID に格納されている値によって特定されるサービスに関する情報を取得します。

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

サービスの作成

サービスを作成するには、サービスタイプの表現を指定して、services.create メソッドに送信します。基本的なサービスタイプと基本的な GKE サービスタイプで説明されているサービスタイプの構造を使用できます。

構造はさまざまですが、API を呼び出すプロセスは変わりません。サービスの表示名とサービス表現を保持する basicService フィールドを指定する必要があります。

任意でサービス ID の指定もできます。次の例は、{[gke_name_short}} ワークロードサービスの作成を示しています。

プロトコル

curl を使用してサービスを作成するには、POST メッセージを https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services エンドポイントに送信します。

サービスの ID を指定する場合は、サービス ID の変数を作成します。
```
SERVICE_ID=my-test-service
```
この値は、URL クエリパラメータ service_id で指定します。

サービスを記述するリクエストの本文を保持する変数を作成します。

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
)

リクエストの本文をエンドポイントに送信し、サービス ID を 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}

他のサービスに関連する構造の例については、基本的なサービスタイプまたは基本的な GKE サービスタイプをご覧ください。

サービスの削除

作成したサービスを削除するには、services.delete メソッドを呼び出してサービス ID を指定します。

プロトコル

curl を使用してサービスを削除するには、DELETE リクエストを 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}

SLO の管理

SLO API を使用して SLO を作成、削除、取得できます。サービスごとに最大 500 個の SLO を設定できます。

サービスの SLO を管理するには、サービス ID が必要です。SLO の名前は、属するサービスに基づきます。サービス ID の特定については、サービス ID をご覧ください。

SLO の一覧表示

サービスに関連付けられたすべての SLO に関する情報を取得するには、services.serviceLevelObjectives.list メソッドを呼び出します。特定の SLO に関する情報を名前別に取得するには、services.serviceLevelObjectives.get メソッドを使用します。

プロトコル

curl を使用してサービスに関する情報を一覧取得するには、GET リクエストを送り、services.serviceLevelObjectives.list または services.serviceLevelObjectives.get メソッドを呼び出します。

https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/[SERVICE_ID]/serviceLevelObjectives は、すべての SLO を一覧表示します。
https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/[SERVICE_ID]/serviceLevelObjectives/SLO_ID は、特定の SLO を取得します。

たとえば、次のリクエストは、環境変数 SERVICE_ID に格納されているサービス ID に関連付けられたすべての SLO を一覧表示します。

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

「currencyservice」サービスから取得される可用性の SLO は次のとおりです。

{
  "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 は可用性の SLI を基盤とし、パフォーマンス目標を 98 パーセントに設定して、1 週間の遵守状況を測定します。可用性の SLI についての詳細は、サービスレベル指標をご覧ください。

SLO の構造についての詳細は、ServiceLevelObjective をご覧ください。

特定の SLO の取得

各 SLO にはサービス内に固有識別子があり、SLO の name フィールドの serviceLevelObjectives に続く文字列で構成されます。下記の例で、

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

SLO ID は文字列 3kavNVTtTMuzL7KcXAxqCQ です。

この特定の SLO に関する情報を取得するには、ID 別に SLO をリクエストします。

プロトコル

curl を使用して特定の SLO を取得するには、GET リクエストを https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives/SLO_ID に送り、services.serviceLevelObjectives.get メソッドを呼び出します。

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}

SLO の作成

SLO API を使用して SLO を作成するには、ServiceLevelObjective オブジェクトを作成して、serviceLevelObjectives.create メソッドに渡す必要があります。

SLO の構造には、serviceLevelIndicator フィールドの値など、多数の埋め込み構造があります。

Cloud Service Mesh、Google Kubernetes Engine 上の Istio、App Engine サービスの場合、SLI は事前定義されています。Cloud Service Mesh コンソールを使用して SLO を作成できます。その際に行う必要があるのは、パフォーマンス目標と遵守期間を指定することのみです。
他のサービスでは、SLO API を使用して SLO を定義する必要があります。SLO を指定するには、serviceLevelIndicator フィールドの値も作成する必要があります。一部の方法については、サービスレベル指標の作成をご覧ください。また、さまざまなソースに基づく例については、指標から SLI を作成するをご覧ください。

Google Cloud コンソールを使用して SLI を作成することもできます。詳細については、SLO の作成をご覧ください。

SLO のスケルトン

SLO を構築するための基本的なスケルトンは次のとおりです。

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

次の項目を指定する必要があります。

表示名: SLO の説明
サービスレベル指標（次の 3 つのうち 1 つ）:
パフォーマンス目標（パーセンテージ）
準拠期間（次の 2 つのうち 1 つ）:
- まとまった長さの連続期間（秒単位）
- カレンダー期間

SLI、パフォーマンス目標、コンプライアンス期間の詳細については、サービスモニタリングのコンセプトをご覧ください。

Cloud Service Mesh、Google Kubernetes Engine 上の Istio、App Engine サービスの場合、SLI タイプは基本 SLI です。

他のサービスでは、リクエストベースの SLI か Windows ベースの SLI を作成する必要があります。方法については、サービスレベル指標の作成をご覧ください。

例

SLI を作成すると、SLO を作成できるようになります。次の例では、基本 SLI を使用するサービスの SLO を定義します。1 つの SLI に対して、たとえば、95% の可用性と 99% の可用性という複数の SLO がある場合もあります。次の例は、1 週間に 95% の可用性を実現する SLO です。

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

この例では、3 日間の連続期間に 75% の可用性を実現する SLO を指定します。

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

プロトコル

curl を使用して SLO を作成するには、POST メッセージを https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives エンドポイントに送信します。

サービス ID の変数を作成します。
```
SERVICE_ID=custom:my-test-service
```

ServiceLevelObjective オブジェクトのインスタンスである、リクエストの本文を保持する変数を作成します。この例では、前記のいずれかの SLO を使用します。

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
)

リクエストの本文をエンドポイントに送信します。

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

任意で、SLO に必要な ID を 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}

SLO の削除

SLO を削除するには、services.serviceLevelObjectives.delete メソッドを呼び出して、プロジェクト内の SLO ID を指定します。

プロトコル

curl を使用して SLO を削除するには、DELETE リクエストを 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}

SLO の時系列へのアクセス

SLO データは時系列で保存されるため、timeSeries.list メソッドを使用して取得できます。ただし、このデータは標準の指標タイプには格納されないため、指標タイプフィルタを指定する標準のメカニズムを timeSeries.list メソッドに使用できません。

代わりに、別のタイプのフィルタである時系列セレクタを filter パラメータの timeSeries.list メソッドに指定して、SLO の時系列を取得します。これらのセレクタの使用方法については、SLO データの取得をご覧ください。

また、プログラムでのアラートポリシー設定にも、時系列セレクタを使用します。詳しくは、バーンレートに関する警告をご覧ください。

API の操作

有効な ID

curl の使用例

認証

curl の呼び出し

サービスの管理

サービス ID

サービスの一覧表示

プロトコル

サービスの作成

プロトコル

サービスの削除

プロトコル

SLO の管理

SLO の一覧表示

プロトコル

特定の SLO の取得

プロトコル

SLO の作成

SLO のスケルトン

例

プロトコル

SLO の削除

プロトコル

SLO の時系列へのアクセス

`curl` の使用例

`curl` の呼び出し