指標のクエリと表示

Google Distributed Cloud（GDC）エアギャップにデプロイされたワークロードから指標を収集したら、分析を開始できます。指標を分析するには、有益な Grafana ダッシュボードで指標を可視化してフィルタリングするか、curl ツールを使用して Cortex から直接アクセスし、柔軟なスクリプト作成と自動化を行います。

このページでは、Grafana ユーザー インターフェースと Cortex エンドポイントの curl ツールを使用して指標をクエリして可視化し、ワークロードのパフォーマンスに関する分析情報を取得する方法について詳しく説明します。

指標には、次の 2 つの方法のいずれかでアクセスできます。

• Grafana ダッシュボード: CPU 使用率、ストレージ消費量、ネットワーク アクティビティなどの主要な指標を直感的に可視化して、傾向を把握し、異常を特定します。Grafana は、ダッシュボードでワークロード データをフィルタして分析するための使いやすいインターフェースを提供します。
• Cortex エンドポイント: より高度なユースケースでは、コマンドラインで curl ツールを使用して、プロジェクトの Cortex インスタンスを直接クエリします。Cortex は、プロジェクトの Prometheus 指標を保存し、プログラムによるアクセス用の HTTP エンドポイントを提供します。このアクセス権により、データのエクスポート、タスクの自動化、カスタム統合の構築が可能になります。

始める前に

Grafana ダッシュボードで指標をクエリして可視化するために必要な権限を取得するには、組織の IAM 管理者またはプロジェクトの IAM 管理者に、事前定義された組織の Grafana 閲覧者ロールまたはプロジェクトの Grafana 閲覧者ロールのいずれかを付与するよう依頼します。必要なアクセスレベルと権限に応じて、組織またはプロジェクトで Grafana ロールを取得できます。

または、Cortex エンドポイントから指標をクエリするために必要な権限を取得するには、プロジェクトの IAM 管理者に、プロジェクトの Namespace で Project Cortex Prometheus 閲覧者のロールを付与するよう依頼します。

次の表に、PA persona の Role 要件をまとめます。

ペルソナ	オブジェクト	クラスタ	ロール	名前空間	グループ / ユーザー	構成
PA	grafana	org-admin	project-grafana-viewer	platform-obs	グループ	1
PA	cortex	org-admin	project-cortex-prometheus-viewer	platform-obs	グループ	2
PA	grafana	org-admin	project-grafana-viewer	platform-obs	ユーザー	3
PA	cortex	org-admin	project-cortex-prometheus-viewer	platform-obs	ユーザー	4

次の変数を適切に置き換えます。

変数	説明
KUBECONFIG	この RoleBinding が適用される NAMESPACE を含む特定のクラスタの kubeconfig が必要になります。
RULE_NAME	Namespace 内のこの RoleBinding リソースの一意の名前。例: io-root-cortex-prometheus-viewer
NAMESPACE	この RoleBinding が作成され、適用される Kubernetes Namespace。前の表で Namespace 列を探します。
EMAIL_ADDRESS	ロールが付与されるユーザーの識別子。多くの場合、メールアドレスです。例: [e-mail]
ROLE	ユーザーに付与する権限を含む Role の名前。前の表に記載されているロールを探します。
GROUP_NAME	ユーザーに付与する権限を含む Role の名前。例: io-group
ZONE	ゾーンの名前

重要: 構成を commit する前に、kustomization.yaml ファイルが yaml ファイルを作成するフォルダに存在することを確認してください。

構成 1

この構成は PA ペルソナ用で、org-admin クラスタの grafana オブジェクトをターゲットにしています。platform-obs Namespace 内の project-grafana-viewer ロールを Group に付与します。

• kubectl コマンド

  一般的なコマンド形式は次のとおりです。

  kubectl --kubeconfig `KUBECONFIG` create rolebinding `RULE_NAME` -n platform-obs --group=`GROUP_NAME` --role=project-grafana-viewer
  

  例:

  kubectl --kubeconfig <path-to-kubeconfig> create rolebinding project-grafana-viewers-binding --role=project-grafana-viewer --group=my-team --namespace=platform-obs
  

• IAC ファイルパス

  /infrastructure/zonal/zones/`ZONE`/org-admin/rolebindings/`GROUP_NAME`/<YAML_FILE>
  

• Yaml ファイル

  apiVersion: rbac.authorization.k8s.io/v1
  kind: RoleBinding
  metadata:
    name: RULE_NAME
    namespace: platform-obs
  subjects:
  - kind: Group
    name: GROUP_NAME
    apiGroup: rbac.authorization.k8s.io
  roleRef:
    kind: Role
    name: project-grafana-viewer
    apiGroup: rbac.authorization.k8s.io
  

構成 2

この構成は PA ペルソナ用で、org-admin クラスタの cortex オブジェクトをターゲットにしています。platform-obs Namespace 内の project-cortex-prometheus-viewer ロールを Group に付与します。

• kubectl コマンド

  一般的なコマンド形式は次のとおりです。

  kubectl --kubeconfig `KUBECONFIG` create rolebinding `RULE_NAME` -n platform-obs --group=`GROUP_NAME` --role=project-cortex-prometheus-viewer
  

  例:

  kubectl --kubeconfig <path-to-kubeconfig> create rolebinding project-cortex-prometheus-viewer-binding --role=project-cortex-prometheus-viewer --group=my-team --namespace=platform-obs
  

• IAC ファイルパス

  /infrastructure/zonal/zones/`ZONE`/org-admin/rolebindings/`GROUP_NAME`/<YAML_FILE>
  

• Yaml ファイル

  apiVersion: rbac.authorization.k8s.io/v1
  kind: RoleBinding
  metadata:
    name: RULE_NAME
    namespace: platform-obs
  subjects:
  - kind: Group
    name: GROUP_NAME
    apiGroup: rbac.authorization.k8s.io
  roleRef:
    kind: Role
    name: project-cortex-prometheus-viewer
    apiGroup: rbac.authorization.k8s.io
  

構成 3

この構成は PA ペルソナ用で、org-admin クラスタの grafana オブジェクトをターゲットにしています。platform-obs Namespace 内の project-grafana-viewer ロールを User に付与します。

• kubectl コマンド

  一般的なコマンド形式は次のとおりです。

  kubectl --kubeconfig `KUBECONFIG` create rolebinding `RULE_NAME` -n platform-obs --user=`EMAIL_ADDRESS` --role=project-grafana-viewer
  

  例:

  kubectl --kubeconfig <path-to-kubeconfig> create rolebinding project-grafana-viewers-binding --role=project-grafana-viewer --user=[e-mail] --namespace=platform-obs
  

• IAC ファイルパス

  /infrastructure/zonal/zones/`ZONE`/org-admin/rolebindings/`EMAIL_ADDRESS`/<YAML_FILE>
  

• Yaml ファイル

  apiVersion: rbac.authorization.k8s.io/v1
  kind: RoleBinding
  metadata:
    name: RULE_NAME
    namespace: platform-obs
  subjects:
  - kind: User
    name: EMAIL_ADDRESS
    apiGroup: rbac.authorization.k8s.io
  roleRef:
    kind: Role
    name: project-grafana-viewer
    apiGroup: rbac.authorization.k8s.io
  

構成 4

この構成は PA ペルソナ用で、org-admin クラスタの cortex オブジェクトをターゲットにしています。platform-obs Namespace 内の project-cortex-prometheus-viewer ロールを User に付与します。

• kubectl コマンド

  一般的なコマンド形式は次のとおりです。

  kubectl --kubeconfig `KUBECONFIG` create rolebinding `RULE_NAME` -n platform-obs --user=`EMAIL_ADDRESS` --role=project-cortex-prometheus-viewer
  

  例:

  kubectl --kubeconfig <path-to-kubeconfig> create rolebinding project-cortex-prometheus-viewer-binding --role=project-cortex-prometheus-viewer --user=[e-mail] --namespace=platform-obs
  

• IAC ファイルパス

  /infrastructure/zonal/zones/`ZONE`/org-admin/rolebindings/`EMAIL_ADDRESS`/<YAML_FILE>
  

• Yaml ファイル

  apiVersion: rbac.authorization.k8s.io/v1
  kind: RoleBinding
  metadata:
    name: RULE_NAME
    namespace: platform-obs
  subjects:
  - kind: User
    name: EMAIL_ADDRESS
    apiGroup: rbac.authorization.k8s.io
  roleRef:
    kind: Role
    name: project-cortex-prometheus-viewer
    apiGroup: rbac.authorization.k8s.io
  

これらのロールの詳細については、IAM 権限を準備するをご覧ください。

指標を取得してフィルタリングする

次のいずれかの方法を選択して、クエリを作成し、傾向を可視化して、プロジェクト ワークロードの指標をフィルタします。

Grafana ダッシュボード

このセクションでは、Grafana ダッシュボードを使用して指標にアクセスする方法について説明します。

Grafana エンドポイントを特定する

次の URL は、プロジェクトの Grafana インスタンスのエンドポイントです。

  https://GDC_URL/PROJECT_NAMESPACE/grafana

次のように置き換えます。

• GDC_URL: GDC 内の組織の URL。

• PROJECT_NAMESPACE: プロジェクトの Namespace。

  たとえば、org-1 組織の platform-obs プロジェクトの Grafana エンドポイントは https://org-1/platform-obs/grafana です。

Grafana ユーザー インターフェースで指標を表示する

Grafana ユーザー インターフェースで指標を取得します。

1. GDC コンソールで、プロジェクトを選択します。
2. ナビゲーション メニューで、[オペレーション] > [モニタリング] を選択します。

3. [Grafana で全て表示] をクリックします。

   新しいページが開き、Grafana エンドポイントとユーザー インターフェースが表示されます。

4. ユーザー インターフェースで、ナビゲーション メニューの [Explore] Explore をクリックして、[Explore] ページを開きます。

5. [Explore] バーのメニューから、ユニバースのタイプに応じて指標を取得するデータソースを選択します。

   • シングルゾーン ユニバース: [prometheus] を選択して、ユニバースのシングルゾーンの指標を表示します。

   • マルチゾーン ユニバース: Grafana はさまざまなゾーンに接続し、ゾーン間のデータを表示できます。指標 ZONE_NAME を選択すると、ログインしているゾーンに関係なく、ユニバースの任意のゾーンの指標が表示されます。

     また、単一のダッシュボードでゾーン間のデータ可視化を行い、クエリに複数のゾーンを追加するには、データソースとして [混合] を選択します。

6. PromQL（Prometheus Query Language）式を使用して指標を検索するクエリを入力します。この手順は、次のいずれかの方法で行います。

   • [指標] メニューと [ラベルフィルタ] メニューから、クエリの指標とラベルを選択します。[追加] 追加 をクリックして、クエリにラベルを追加します。[クエリを実行] をクリックします。
   • [指標] テキスト フィールドにクエリを直接入力し、Shift+Enter キーを押してクエリを実行します。

   このページには、クエリに一致する指標が表示されます。

   

   図 1. Grafana ユーザー インターフェースから指標をクエリするメニュー オプション。

   図 1 の prometheus オプションには、Grafana からクエリを作成して指標を取得できるインターフェースが表示されます。

   指標のクエリに使用できるラベルの値の例については、サンプルクエリとラベルをご覧ください。

Cortex エンドポイント

このセクションでは、Cortex を使用して指標にアクセスする方法について説明します。

Cortex エンドポイントを特定する

次の URL は、プロジェクトの Cortex インスタンスのエンドポイントです。

  https://GDC_URL/PROJECT_NAMESPACE/cortex/prometheus/

次のように置き換えます。

• GDC_URL: GDC 内の組織の URL。

• PROJECT_NAMESPACE: プロジェクトの Namespace。

  たとえば、org-1 組織の platform-obs プロジェクトの Cortex エンドポイントは https://org-1/platform-obs/cortex/prometheus/ です。

  注: ウェブブラウザで URL を直接開いて、指標をクエリできます。次のセクションの手順では、curl コマンドを使用してエンドポイントを呼び出しますが、これはウェブブラウザにも当てはまります。

curl リクエストを認証する

1. gdcloud CLI をダウンロードしてインストールします。

2. gdcloud core/organization_console_url プロパティを設定します。

   gdcloud config set core/organization_console_url
   https://GDC_URL
   

3. 構成済みの ID プロバイダでログインする:

   gdcloud auth login
   

4. ユーザー名とパスワードを使用して認証し、ログインします。

   ログインに成功すると、gdcloud auth print-identity-token コマンドを使用して curl リクエストで認証ヘッダーを使用できます。詳細については、gdcloud auth をご覧ください。

Cortex エンドポイントを呼び出す

curl ツールを使用して Cortex エンドポイントにアクセスする手順は次のとおりです。

1. curl リクエストを認証します。

2. curl を使用して Cortex エンドポイントを呼び出し、HTTP API 形式のクエリを使用して URL を拡張し、指標をクエリします。

   curl リクエストの例を次に示します。

   curl https://GDC_URL/PROJECT_NAME/cortex/prometheus/api/v1/query?query=my_metric{cluster="my-cluster"}&time=2015-07-01T20:10:51.781Z \
   -H "Authorization: Bearer $(gdcloud auth print-identity-token \
   --audiences=https://GDC_URL)"
   

   コマンドの後に次の出力が表示されます。API レスポンスは JSON 形式です。

   注: URL から指標をクエリするには、api/v1/query エンドポイントを追加します。URL の末尾にある疑問符（?）の後に、API 呼び出しの省略可能なパラメータを含めることができます。これらのパラメータは、前の手順の curl リクエストの例のように、アンパサンド（&）記号で区切ります。

サンプルクエリとラベル

指標名とラベルの Key-Value ペアを使用して指標をクエリできます。PromQL クエリの構文は次のとおりです。

metric_name{label_one="value", label_two="value"}

ラベルを使用すると、指標の特性を区別できます。このようにして、コンテナ作成者はワークロードで指標を生成し、それらの指標をフィルタするタグを追加します。

たとえば、受信した HTTP リクエストの数をカウントする api_http_requests_total 指標を設定できます。次に、この指標に request_method ラベルを追加できます。このラベルは POST、GET、PUT の値を取ります。したがって、受信する可能性のあるリクエスト タイプごとに 3 つの指標ストリームを作成します。この場合、HTTP GET リクエストの数を確認するには、次のクエリを実行します。

api_http_requests_total{request_method="GET"}

指標とラベルの詳細については、指標とラベルの命名をご覧ください。

MonitoringTarget カスタム リソースが追加するデフォルトのラベルの一部を以下に示します。これらのデフォルトのラベルを使用して、指標をクエリできます。

• _gdch_service: サービスの短い名前。
• cluster: クラスタの名前。
• container_name: Pod 内のコンテナの名前。
• namespace_name: プロジェクトの Namespace。
• pod_name: Pod 名の接頭辞。

次の表に、Prometheus が自動的に追加するラベルを示します。

デフォルトのラベル

指標ラベル	説明
job	指標の収集に使用されるスクレイピング ジョブの内部名。MonitoringTarget カスタム リソースによって作成されたジョブには、次のパターンで名前が付けられます。 obs-system/OBS_SHADOW_PROJECT_NAME/MONITORINGTARGET_NAME.MONITORINGTARGET_NAMESPACE/I/J I と J は、名前の競合を避けるために内部で決定される一意の番号です。
instance	スクラップされたサービスの $IP:$PORT。ワークロード リソースに複数のレプリカがある場合は、このフィールドを使用して区別します。

次のコードサンプルは、ラベルの Key-Value ペアを使用してさまざまな指標をクエリする方法を示しています。

• プロジェクトで処理されたオペレーションのすべての指標ストリームを表示します。

  processed_ops_total
  

• Kubernetes クラスタで収集された処理済みオペレーションを表示します。

  processed_ops_total{cluster="CLUSTER_NAME"}
  

• Kubernetes クラスタで収集された CPU 使用率を表示します。

  cpu_usage{cluster="CLUSTER_NAME"}
  

指標の再ラベル付けツールを使用して、スクレイピングされたコンテナによって最初に公開されなかったラベルを追加し、生成された指標の名前を変更します。収集する指標にラベルを追加するように MonitoringTarget カスタム リソースを構成する必要があります。これらのラベルは、カスタム リソースの metricsRelabelings フィールドで指定します。詳細については、ラベル指標をご覧ください。

HTTP API のクエリ

フォーマットの概要

API レスポンスは常に JSON 形式でフォーマットされます。リクエストが成功すると、常に 2xx ステータス コードが返されます。

無効なリクエストの場合、API ハンドラは次のいずれかの HTTP ステータス コードとともに JSON エラー オブジェクトを返します。

• 400 Bad Request: 必須パラメータがないか、正しく指定されていない場合。
• 503 Service Unavailable: クエリがタイムアウトになった場合、またはクエリが中止された場合。

正常に収集されたデータは、レスポンスの「data」フィールドに含まれます。

JSON レスポンス エンベロープの形式は次のとおりです。

{
  "status": "success" | "error",
  "data": <data>,

  // Only set if status is "error". The data field may still hold
  // additional data.
  "errorType": "<string>",
  "error": "<string>",

  // Only set if there were warnings while executing the request.
  // There will still be data in the data field.
  "warnings": ["<string>"],
  // Only set if there were info-level annotations while executing the request.
  "infos": ["<string>"]
}

インスタント クエリ

次のエンドポイントは、特定の時点のインスタント クエリを評価します。

GET /api/v1/query
POST /api/v1/query

Prometheus 式クエリでは、次の URL クエリ パラメータを使用できます。

• query=<string>: Prometheus 式のクエリ文字列。
• time=<rfc3339 | unix_timestamp>: 省略可能な評価タイムスタンプ。RFC 3339 文字列または Unix タイムスタンプとして指定します。省略すると、現在のサーバー時刻が使用されます。
• timeout=<duration>: 評価のタイムアウト（省略可）。デフォルトでは、query.timeout フラグの値によって制限されます。
• limit=<number>: 返される系列の最大数（省略可）。これにより、行列とベクトルの系列は切り捨てられますが、スカラーや文字列には影響しません。値 0 はこの上限を無効にします。
• lookback_delta=<number>: このクエリのルックバック期間をオーバーライドする省略可能なパラメータ。

時間パラメータを省略すると、現在のサーバー時間が使用されます。

URL の文字数制限を超える可能性がある大きなクエリの場合は、POST メソッドを使用してこれらのパラメータを送信できます。リクエストの本文が URL エンコードされ、Content-Type ヘッダーが application/x-www-form-urlencoded に設定されていることを確認します。

クエリ結果のデータ セクションの形式は次のとおりです。

{
  "resultType": "matrix" | "vector" | "scalar" | "string",
  "result": <value>
}

<value> はクエリ結果データを指します。このデータの形式は resultType によって異なります。

次の例では、2015-07-01T20:10:51.781Z の時点で式 up を評価します。

curl 'http://localhost:9090/api/v1/query?query=up&time=2015-07-01T20:10:51.781Z'

{
   "status" : "success",
   "data" : {
      "resultType" : "vector",
      "result" : [
         {
            "metric" : {
               "__name__" : "up",
               "job" : "prometheus",
               "instance" : "localhost:9090"
            },
            "value": [ 1435781451.781, "1" ]
         },
         {
            "metric" : {
               "__name__" : "up",
               "job" : "node",
               "instance" : "localhost:9100"
            },
            "value" : [ 1435781451.781, "0" ]
         }
      ]
   }
}

範囲クエリ

次のエンドポイントは、一定の期間にわたって式クエリを評価します。

GET /api/v1/query_range
POST /api/v1/query_range

Prometheus 式クエリでは、次の URL クエリ パラメータを使用できます。

• query=<string>: Prometheus 式のクエリ文字列。
• start=<rfc3339 | unix_timestamp>: 開始タイムスタンプ（この値は含まれる）。
• end=<rfc3339 | unix_timestamp>: 終了タイムスタンプ（この値を含む）。
• step=<duration | float>: クエリ解決ステップの幅（期間形式または秒単位の浮動小数点数）。
• timeout=<duration>: 評価のタイムアウト（省略可）。デフォルトでは、query.timeout フラグの値によって制限されます。
• limit=<number>: 返される系列の最大数（省略可）。これにより、行列とベクトルの系列は切り捨てられますが、スカラーや文字列には影響しません。値 0 はこの上限を無効にします。
• lookback_delta=<number>: このクエリのルックバック期間をオーバーライドする省略可能なパラメータ。

URL の文字数制限を超える可能性がある大きなクエリの場合は、POST メソッドを使用してこれらのパラメータを送信できます。リクエストの本文が URL エンコードされ、Content-Type ヘッダーが application/x-www-form-urlencoded に設定されていることを確認します。

クエリ結果のデータ セクションの形式は次のとおりです。

{
  "resultType": "matrix",
  "result": <value>
}

次の例では、クエリの解像度が 15 秒で、30 秒の範囲で up 式を評価します。

curl 'http://localhost:9090/api/v1/query_range?query=up&start=2015-07-01T20:10:30.781Z&end=2015-07-01T20:11:00.781Z&step=15s'

{
   "status" : "success",
   "data" : {
      "resultType" : "matrix",
      "result" : [
         {
            "metric" : {
               "__name__" : "up",
               "job" : "prometheus",
               "instance" : "localhost:9090"
            },
            "values" : [
               [ 1435781430.781, "1" ],
               [ 1435781445.781, "1" ],
               [ 1435781460.781, "1" ]
            ]
         },
         {
            "metric" : {
               "__name__" : "up",
               "job" : "node",
               "instance" : "localhost:9091"
            },
            "values" : [
               [ 1435781430.781, "0" ],
               [ 1435781445.781, "0" ],
               [ 1435781460.781, "1" ]
            ]
         }
      ]
   }
}

指標とラベルの命名

指標の命名ガイドライン

指標名を定義する際は、次の原則を考慮してください。

• 指標名には、1 語のアプリケーション プレフィックスを含めるべきです。クライアント ライブラリでは、このプレフィックスを「名前空間」と呼ぶことがあります。この接頭辞は、指標が属するドメインを識別します。アプリケーション固有の指標の場合、通常はアプリケーションの名前が接頭辞として使用されます。

  例:

  • prometheus_notifications_total（Prometheus サーバーに固有）
  • process_cpu_seconds_total（多くのクライアント ライブラリによってエクスポートされる）
  • http_request_duration_seconds（すべての HTTP リクエスト）

• 指標名は単一の単位を表さなければなりません（秒とミリ秒、または秒とバイトを混在させないでください）。

• 指標名では、派生単位（ミリ秒、メガバイト、キロメートルなど）ではなく、基本単位（秒、バイト、メートルなど）を使用すべきです。

• 指標名には、単位の複数形の接尾辞を含めるべきです。累積カウントの場合は、単位の接尾辞に加えて「total」という接尾辞を使用する必要があります（該当する場合）。

  例:

  • http_request_duration_seconds
  • node_memory_usage_bytes
  • http_requests_total（単位のない累積カウント）
  • process_cpu_seconds_total（単位付きの累積カウントの場合）
  • foobar_build_info（実行中のバイナリに関するメタデータを提供する疑似指標）

• 他のすべてのルールが守られている場合、指標名は、辞書式順序で並べ替えたときに便利なようにコンポーネントを並べ替えても構いません。関連する指標には、共通の名前コンポーネントが先頭に配置され、一緒に並べ替えられるようになっています。

  例:

  • prometheus_tsdb_head_truncations_closed_total
  • prometheus_tsdb_head_truncations_established_total
  • prometheus_tsdb_head_truncations_failed_total
  • prometheus_tsdb_head_truncations_total

• 指標名は、すべてのラベル ディメンションで同じ論理的な「測定対象」を一貫して表す必要があります。

  例:

  • リクエスト期限
  • データ転送のバイト数
  • リソースの瞬時使用率（%）

ラベルの命名ガイドライン

何かを測定する場合は、ラベルを使用して特性を区別します。次に例を示します。

• API HTTP リクエストの合計数（api_http_requests_total）については、オペレーション タイプ（create、update、delete など）で区別します（リクエスト タイプ: operation="create|update|delete"）。
• API リクエストの所要時間（秒単位）（api_request_duration_seconds）については、リクエスト ステージ（stage="extract|transform|load"）別に（extract、transform、load など）区別します。

ラベル名が指標名自体に含まれていると、冗長性が生じ、後でラベルが集計された場合に混乱を招く可能性があるため、ラベル名を指標名に含めることは避けてください。