API の操作

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

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

SLO API を使用して、サービスとサービスレベル目標(SLO)を管理できます。このページでは、カスタム サービスとサービスレベル指標(SLI)について説明します。Anthos Service Mesh、Google Kubernetes Engine 上の Istio、App Engine で実行されるサービスが自動的に検出され、これらサービスの SLI は事前定義されています。

Google Cloud Console を使用して 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 の呼び出しに関する次の情報を使用して、呼び出しで使用される変数を設定します。

認証

  1. 指標スコープ(またはワークスペースのホスト プロジェクト)のスコープ プロジェクトの ID を保持する環境変数を作成します。次の例では PROJECT_ID を使用しています。

    PROJECT_ID=my-test-service
    
  2. Cloud SDK に対して認証を行います。

    gcloud auth login
    
  3. 各コマンドでのプロジェクト ID の指定を不要にするには、Cloud SDK を使用してプロジェクト ID をデフォルトとして設定します。

    gcloud config set project ${PROJECT_ID}
    
  4. 認証トークンを作成し、環境変数にキャプチャします。次の例では変数 ACCESS_TOKEN を呼び出しています。

    ACCESS_TOKEN=`gcloud auth print-access-token`
    

    アクセス トークンは定期的に更新する必要があります。動作していたコマンドに急に未認証と報告された場合は、このコマンドを再発行します。

  5. アクセス トークンがあることを確認するには、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

このリクエストは、「currencyservice」という Istio サービス、といったエントリを含むサービスの説明の配列を返します。

{
  "services": [
    {
      "name": "projects/[PROJECT_NUMBER]/services/[PROJECT_ID]-zone-us-central1-c-csm-main-default-currencyservice",
      "displayName": "[PROJECT_ID]/us-central1-c/csm-main/default/currencyservice",
      "clusterIstio": {
        "location": "us-central1-c",
        "clusterName": "csm-main",
        "serviceNamespace": "default",
        "serviceName": "currencyservice"
      },
      "telemetry": {
        "resourceName": "//container.googleapis.com/projects/[PROJECT_ID]/zones/us-central1-c/clusters/csm-main/k8s/namespaces/default/services/currencyservice"
      }
    },
   ...
  ]
}

サービスの構造についての詳細は、Service をご覧ください。

サービスの管理

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

Anthos Service Mesh、Google Kubernetes Engine 上の Istio、App Engine のサービスは自動的に作成されます。たとえば、Anthos Service Mesh コンソールまたは SLO API を使用して、これらのサービスに SLO を追加することもできます。

手動で作成したサービスはカスタム サービスと呼ばれます。カスタム サービスは、SLO 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}

サービスの作成

サービスが自動的に作成される環境(つまり Anthos Service Mesh、Google Kubernetes Engine 上の Istio、App Engine)を使用していない場合は、services.create メソッドを使用してサービスを作成できます。

サービスを手動で作成する場合は、作成した後に SLO API を使用して、サービス構造に SLO やその他のサービス モニタリング アーティファクトを手動で追加する必要があります。これらの構造の概要については、API で構築するをご覧ください。

サービスを作成するには、サービスの表示名と、オブジェクトが空の custom というフィールドを指定する必要があります。任意でサービス ID の指定もできます。

プロトコル

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

  1. サービスの ID を指定する場合は、サービス ID の変数を作成します。

    SERVICE_ID=my-test-service
    

    この値は、URL クエリ パラメータ service_id で指定します。

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

    CREATE_SERVICE_POST_BODY=$(cat <<EOF
    {
        "displayName": "My Test Service",
        "custom": {}
    }
    EOF
    )
    
  3. リクエストの本文をエンドポイントに送信し、サービス 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}
    

サービスの削除

カスタム サービスを削除するには、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 はサービスに関連付けられます。SLO を作成するには、Anthos Service Mesh の Anthos Service Mesh コンソール、Google Kubernetes Engine 上の Istio、App Engine を使用するか、SLO API を使用します。カスタム サービス用の SLO を作成するには、SLO API を使用する必要があります。

また、SLO API を使用すると、サービスに関連付けられた SLO を取得でき、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 にはサービス内で一意の ID があり、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 フィールドの値など、多数の埋め込み構造があります。

  • Anthos Service Mesh、Google Kubernetes Engine 上の Istio、App Engine サービスの場合、SLI は事前定義されています。Anthos Service Mesh コンソールを使用して SLO を作成できます。パフォーマンス目標と遵守期間を指定するだけです。

    SLO API を使用して SLO を定義することもできます。

  • カスタム サービスでは、SLO API を使用して SLO を定義する必要があります。SLO を指定するには、serviceLevelIndicator フィールドの値も作成する必要があります。方法については、サービスレベル指標の作成をご覧ください。

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

Anthos 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 エンドポイントに送信します。

  1. サービス ID の変数を作成します。

    SERVICE_ID=custom:my-test-service
    
  2. 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
    )
    
  3. リクエストの本文をエンドポイントに送信します。

    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 データの取得をご覧ください。

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