API の操作

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

このページでは、新しい API リソースの主な用途について説明します。 ここで使用される構造の概要については、API による構築をご覧ください。包括的な参考資料は Cloud Monitoring API v3 の下にあります。

このドキュメントでは、これらの追加リソースをまとめて Service Monitoring API と総称します。

API を使用するケース

Service Monitoring API は、サービスとサービスレベル目標(SLO)の管理に使用できます。このページでは、カスタム サービスとサービスレベル指標(SLI)について説明します。App Engine、Istio on Google Kubernetes Engine、Cloud Endpoints で実行されるサービスは自動的に検出され、SLI は事前定義されています。SLO を定義するには、Anthos Service Mesh コンソールか Service Monitoring API のいずれかを使用できます。Anthos Service Mesh ダッシュボードを使用した SLO の作成について詳しくは、Anthos Service Mesh のドキュメント: SLO の作成をご覧ください。

独自のサービスとその SLO を定義することもできますが、Service Monitoring API を使用する必要があります。Google Cloud Console のサポートはありません。

このページの例では、主にカスタム サービスと SLI を中心に取り上げます。

有効な ID

Service Monitoring API のいくつかのメソッドでは、さまざまな要素の識別子を使用します。特にプロジェクトやサービスの識別子が使用されます。これらの ID は次のルールに準拠します。

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

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

curl の使用例

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

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

認証

  1. Cloud Monitoring ワークスペースの 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 呼び出しには、一連の引数が含まれ、Service Monitoring 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 などの特定のサービスのアスペクトは、サービスの名前ごとに編成されます。

App Engine、Istio on Google Kubernetes Engine、Cloud Endpoints のサービスは自動的に作成されます。Anthos Service Mesh コンソールや Service Monitoring API を使用して、これらのサービスに SLO の追加することなどが可能です。

手動で作成したサービスはカスタム サービスと呼ばれます。 カスタム サービスの作成、削除、取得、更新ができるのは、Service Monitoring 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}
    

サービスの作成

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

手動でサービスを作成する場合は、作成した後に Service Monitoring 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 は、App Engine の Anthos Service Mesh コンソール、Istio on Google Kubernetes Engine、Cloud Endpoints を使用して作成できます。あるいは、Service Monitoring API での作成も可能です。カスタム サービス用の SLO を作成するには、Service Monitoring API を使用する必要があります。

また、Service Monitoring API を使用して、サービスに関連付けられた SLO を取得でき、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 の作成

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

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

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

    Service Monitoring API を使用しても、SLO を定義できます。

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

App Engine、Istio on Google Kubernetes Engine、Cloud Endpoints サービスについては、SLI タイプは基本的な SLI です。

カスタム サービスでは、リクエスト ベースの SLI かウィンドウ ベースの 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 データの取得をご覧ください。

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