API で構築する

このドキュメントでは、SLO API でサービスと SLO を表すために使用される構文、およびサービスモニタリングのコンセプトに記載されるコンセプト全般に関連付けて説明します。

SLO API は、サービスの状態のモニタリングに使用できるサービスレベル目標（SLO）を設定するために使用されます。

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

API の呼び出しについては、API の操作をご覧ください。

サービス

サービスは、Service オブジェクトで表示されます。このオブジェクトには次のフィールドが含まれます。

名前: サービスの完全修飾リソース名。
表示名: コンソールコンポーネントで使用するラベル
BasicService タイプの 1 つの構造。
システム提供のテレメトリー構成オブジェクト

基本サービスを定義するには、サービスのタイプを指定し、サービスを記述するサービス固有のラベルを指定します。

{
   "serviceType": string,
   "serviceLabels": {
      string: string,
      ...
   }
}

以降のセクションでは、サービスのタイプ別に例を示します。

基本的なサービスタイプ

このセクションでは、BasicService タイプに基づいて構築されたサービス定義の例を示します。serviceType フィールドの値は次のいずれかです。

APP_ENGINE
CLOUD_ENDPOINTS
CLUSTER_ISTIO
ISTIO_CANONICAL_SERVICE
CLOUD_RUN

これらのサービスタイプはそれぞれ、BasicSli サービスレベル指標を使用します。

App Engine

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "APP_ENGINE",
          "serviceLabels": {
            "module_id": "MODULE_ID"
          },
      },
    }

Cloud Endpoints

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "CLOUD_ENDPOINTS",
          "serviceLabels": {
            "service": "SERVICE"
          },
      },
    }

クラスタ Istio

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "CLUSTER_ISTIO",
          "serviceLabels": {
            "location": "LOCATION",
            "cluster_name": "CLUSTER_NAME",
            "service_namespace": "SERVICE_NAMESPACE",
            "service_name": "SERVICE_NAME"
          },
      },
    }

Istio 正規サービス

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "ISTIO_CANONICAL_SERVICE",
          "serviceLabels": {
            "mesh_uid": "MESH_UID",
            "canonical_service_namespace": "CANONICAL_SERVICE_NAMESPACE",
            "canonical_service": "CANONICAL_SERVICE"
          },
      },
    }

Cloud Run

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "CLOUD_RUN",
          "serviceLabels": {
            "service_name": "SERVICE_NAME",
            "location": "LOCATION"
          },
      },
    }

基本的な GKE サービスタイプ

このセクションでは、BasicService タイプに基づいて構築された GKE サービス定義の例を示します。serviceType フィールドの値は次のいずれかです。

GKE_NAMESPACE
GKE_WORKLOAD
GKE_SERVICE

これらのサービスタイプの SLI を定義する必要があります。BasicSli サービスレベル指標は使用できません。詳細については、サービスレベル指標をご覧ください。

GKE Namespace

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "GKE_NAMESPACE",
          "serviceLabels": {
            "project_id": "PROJECT_ID",
            "location": "LOCATION",
            "cluster_name": "CLUSTER_NAME",
            "namespace_name": "NAMESPACE_NAME"
          }
      },
    }

GKE ワークロード

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "GKE_WORKLOAD",
          "serviceLabels": {
            "project_id": "PROJECT_ID",
            "location": "LOCATION",
            "cluster_name": "CLUSTER_NAME",
            "namespace_name": "NAMESPACE_NAME",
            "top_level_controller_type": "TOPLEVEL_CONTROLLER_TYPE",
            "top_level_controller_name": "TOPLEVEL_CONTROLLER_NAME",
          }
      },
    }

GKE サービス

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "GKE_SERVICE",
          "serviceLabels": {
            "project_id": "PROJECT_ID",
            "location": "LOCATION",
            "cluster_name": "CLUSTER_NAME",
            "namespace_name": "NAMESPACE_NAME",
            "service_name": "SERVICE_NAME"
          }
      },
    }

カスタムサービス

どの基本サービスタイプも適していない場合、カスタムサービスを作成できます。カスタムサービスは次のようになります。

    {
      "displayName": "DISPLAY_NAME",
      "custom": {}
    }

サービスレベル指標

サービスレベル指標（SLI）は、サービスのパフォーマンスの指標を提供します。SLI は、サービスによって取得された指標に基づいています。SLI の定義は、インジケーター指標として使用する指標の種類によって異なりますが、一般的には、良い結果と結果総数の比率が使用されます。

SLI は、ServiceLevelIndicator オブジェクトで表現されます。このオブジェクトでは、サポートされている次の 3 種類の SLI がまとめて参照されます。

基本的な SLI。BasicService サービスタイプのインスタンスに対して自動的に作成されます。このタイプの SLI については、サービスレベル目標をご覧ください。BasicSli オブジェクトで表現され、可用性やレイテンシを測定できます。
リクエストベースの SLI。イベントの回数によって受け入れ可能なサービスを表現する際に使用できます。このタイプの SLI の使用については、リクエストベースの SLO をご覧ください。RequestBasedSli オブジェクトで表現されます。
ウィンドウベースの SLI。「良好さ」の基準を満たす測定間隔をカウントするために使用できます。このタイプの SLI の使用については、ウィンドウベースの SLO をご覧ください。WindowsBasedSli オブジェクトで表現されます。

たとえば、基本的な可用性 SLI には次のものがあります。

{
  "basicSli": {
    "availability": {},
    "location": [
      "us-central1-c"
    ]
  }
}

リクエストベースの SLI の構成

リクエストベースの SLI は、サービスの基本単位をカウントして、特定の結果と合計の結果の比率として表す指標に基づいています。たとえば、リクエストをカウントする指標を使用する場合、成功したリクエストの数とリクエストの総数の比率を算出できます。

リクエストベースの SLI を作成するには、次の 2 つの方法があります。

TimeSeriesRatio として作成する。サービス総数に対する良好なサービスの比率が、指標の値が DELTA または CUMULATIVE となる 2 つの時系列から計算されます。
DistributionCut として作成する。値の型が DISTRIBUTION で、指標の値の種類が DELTA または CUMULATIVE となる時系列の場合に使用します。good-service の値は指定された範囲内のヒストグラムバケットに含まれるアイテムの数、total の値は分布内のすべての値の総数です。

以下に、時系列の比率を使用する SLI の JSON 表現を示します。

{
  "requestBased": {
    "goodTotalRatio": {
      "totalServiceFilter": "resource.type=https_lb_rule metric.type="loadbalancing.googleapis.com/https/request_count"",
      "goodServiceFilter": "resource.type=https_lb_rule metric.type="loadbalancing.googleapis.com/https/request_count" metric.label.response_code_class=200",
    }
  }
}

この比率の時系列は、モニタリング対象リソースのタイプと指標タイプのペアで識別されます。

リソース: https_lb_rule
指標タイプ: loadbalancing.googleapis.com/https/request_count

totalServiceFilter の値は、指標とリソースのタイプのペアで表されます。goodServiceFilter の値は同じペアで表されますが、ラベルに特定の値を持つものもあります。この場合は、response_code_class ラベルの値は 200 になります。

フィルタ間の比率は、リクエストの合計数に対して 2xx HTTP ステータスコードを返すリクエストの数を測定します。

以下は、分布カットを使用する SLI の JSON 表現を示しています。

{
  "requestBased": {
    "distribution_cut": {
      "distribution_filter": "resource.type=https_lb_rule  metric.type="loadbalancing.googleapis.com/https/backend_latencies" metric.label.response_code_class=200",
      "range": {
        "min": "-Infinity",
        "max": 500.0
      }
    }
  }
}

時系列は、モニタリング対象リソースのタイプ、指標タイプ、指標ラベルの値で識別されます。

リソース: https_lb_rule
指標タイプ: loadbalancing.googleapis.com/https/backend_latencies
ラベルと値のペア: response_code_class = 200

良好とみなされるレイテンシの範囲は、range フィールドで指定します。この SLI は、200 番台のレスポンスの総レイテンシに対する、500 番未満の 2xx クラスレスポンスのレイテンシの比率を計算します。

ウィンドウベースの SLI の構成

ウィンドウベースの SLI は、提供されたサービスが良好とみなされる時間ウィンドウをカウントします。サービスの良好さの度合いを判断するための条件は、SLI の中で定義されます。

ウィンドウベースの SLI には必ず 60～86,400 秒（1 日）の範囲内のウィンドウ期間が含まれます。

ウィンドウベースの SLI に良好なサービスの基準を指定する方法には、次の 2 つがあります。

モニタリングフィルタで説明している、ブール値を持つ時系列を返すフィルタ文字列を作成します。ウィンドウの値が true の場合、そのウィンドウは良好です。このフィルタは goodBadMetricFilter と呼ばれます。
パフォーマンスの許容範囲のしきい値を表す PerformanceThreshold オブジェクトを作成します。このオブジェクトは、goodTotalRatioThreshold の値として指定します。

PerformanceThreshold オブジェクトは、しきい値とパフォーマンス SLI を指定します。パフォーマンス SLI の値がしきい値以上になる場合、その時間ウィンドウは良好と判定されます。

パフォーマンス SLI を指定する方法には、次の 2 つの方法があります。
- basicPerformanceSli フィールドに、BasicSli オブジェクトとして指定する。
- performance フィールドに、RequestBasedSli オブジェクトとして指定する。

基本的な可用性 SLI のパフォーマンスしきい値に基づいて作成された、ウィンドウベース SLI の JSON 表現の例を次に示します。

{
  "windowsBased": {
     "goodTotalRatioThreshold": {
       "threshold": 0.9,
       "basicSliPerformance": {
         "availability": {},
         "location": [
           "us-central1-c"
         ]
       }
     },
     "windowPeriod": "300s"
   }
}

この SLI は、可用性が 90% 以上になる 5 分間のウィンドウを良好なパフォーマンスとして指定しています。基本的な SLI の構造については、サービスレベル指標をご覧ください。

リクエストベースの SLI をウィンドウベースの SLI に埋め込むこともできます。埋め込み構造の詳細については、リクエストベースの SLI の構成をご覧ください。

サービスレベル目標

サービスレベル目標（SLO）は、ServiceLevelObjective オブジェクトで表現します。このオブジェクトには次のフィールドが含まれます。

名前
表示名
ターゲット SLI。埋め込み ServiceLevelIndicator オブジェクトです。
SLI のパフォーマンス目標
SLI のコンプライアンス期間

次の例は、serviceLevelIndicator フィールドの値として基本的な可用性 SLI が指定された SLO の JSON 表現を示しています。

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

この SLO では、パフォーマンス目標は「1 週間の可用性が 98%」と設定されています。