PromQL を使用すると、次のソースからの Cloud Monitoring のデータをクエリおよびグラフ化できます。
- Cloud Monitoring システム指標のリストに記載されている指標を書き込む Google Kubernetes Engine や Compute Engine などのGoogle Cloud サービス。
- ログベースの指標などのユーザー定義の指標や Cloud Monitoring のユーザー定義の指標。
- Google Cloudの Prometheus 向けのフルマネージド マルチクラウド ソリューションである、Google Cloud Managed Service for Prometheus。PromQL によるサポートを含め、マネージド サービスについて詳しくは、Google Cloud Managed Service for Prometheus をご覧ください。
Grafana などのツールを使用して、Cloud Monitoring に取り込まれた指標データをグラフにすることもできます。使用可能な指標には、指標のリストに記載されている Managed Service for Prometheus の指標と Cloud Monitoring の指標が含まれます。Prometheus API に基づく Grafana などのツールの設定については、Grafana に関する Managed Service for Prometheus のドキュメントをご覧ください。
Grafana ダッシュボードを Cloud Monitoring にインポートすることもできます。
PromQL を使用して Cloud Monitoring の指標をクエリする
Cloud Monitoring の指標は、PromQL の UTF-8 仕様を使用してクエリできます。UTF-8 指標名は引用符で囲み、中括弧内に入れる必要があります。ラベル名に以前のバージョンと互換性のない文字が含まれている場合は、ラベル名も引用符で囲む必要があります。Cloud Monitoring 指標 kubernetes.io/container/cpu/limit_utilization の場合、次のクエリは同等です。
{"kubernetes.io/container/cpu/limit_utilization", pod_name="foo"}{__name__="kubernetes.io/container/cpu/limit_utilization", pod_name="foo"}。{"__name__"="kubernetes.io/container/cpu/limit_utilization", "pod_name"="foo"}。
Cloud Monitoring の分布値指標に対しては、Prometheus ヒストグラムと同様に、指標名に _count、_sum、_bucket サフィックスを追加して、クエリを実行できます。
PromQL では、他の指標と同様にメタデータ ラベルを使用できますが、指標名と同様に PromQL と互換性を持たせる必要があります。メタデータ システムラベル version を参照する構文は metadata_system_version で、メタデータ ユーザーラベル version の構文は metadata_user_version です。メタデータ ラベルを使用した正しい形式の PromQL クエリは、次のようになります。
{"compute.googleapis.com/instance/cpu/utilization", monitored_resource="gce_instance",metadata_user_env="prod"}sum("compute.googleapis.com/instance/cpu/utilization") by (metadata_system_region)sum("compute.googleapis.com/instance/cpu/utilization") by (metadata_user_env){"compute.googleapis.com/instance/uptime_total", "metadata_user_i-love.special/chars"="yes"}sum("compute.googleapis.com/instance/uptime_total") by ("metadata_user_i-love.special/chars")
メタデータ ラベルキーに _ 文字以外の特殊文字が含まれている場合は、PromQL の UTF-8 仕様に従って、ラベルキーを二重引用符（"）で囲む必要があります。メタデータ ラベルの先頭に文字列 metadata_user_ を付ける必要があります。
UTF-8 互換性より前に作成されたグラフとダッシュボードは、名前を以前の PromQL 互換の同等のものに変換して、Cloud Monitoring 指標をクエリします。以前の PromQL 変換ルールの詳細については、Cloud Monitoring 指標と以前の PromQL とのマッピングをご覧ください。
PromQL の学習
PromQL の基本的な使用方法については、オープンソースのドキュメントを参照することをおすすめします。使用を開始する際に、以下のリソースが役に立ちます。
モニタリング対象リソースタイプの指定
Cloud Monitoring 指標が単一の Cloud Monitoring モニタリング対象リソースタイプにのみ関連付けられている場合、手動でリソースタイプを指定しなくても PromQL クエリは機能します。ただし、一部のシステム指標など、Cloud Monitoring 内の一部の指標は複数のリソースタイプにマッピングされます。指標にマッピングされているモニタリング対象リソースタイプについては、Google Cloud 指標のリストでご確認ください。ドキュメント内の各エントリでは、そのタイプの各エントリの最初の列に、関連するモニタリング対象リソースタイプが示されています。モニタリング対象リソースタイプが表示されていない場合は、指標を任意のタイプに関連付けることができます。
指標が複数のリソースタイプに関連付けられている場合は、PromQL クエリでリソースタイプを指定する必要があります。特別なラベル monitored_resource があり、これを使用してリソースタイプを選択できます。
ほとんどの場合、モニタリング対象リソースタイプは gce_instance のような短い文字列ですが、monitoring.googleapis.com/MetricIngestionAttribution のように完全な URI として表示されることもあります。正しい形式の PromQL クエリは次のようになります。
logging_googleapis_com:byte_count{monitored_resource="k8s_container"}loadbalancing_googleapis_com:l3_external_egress_bytes_count{monitored_resource="loadbalancing.googleapis.com/ExternalNetworkLoadBalancerRule"}
必要な場合に monitored_resource ラベルを使用しないと、次のエラーが発生します。
metric is configured to be used with more than one monitored resource type;
series selector must specify a label matcher on monitored resource name
ラベル競合の解決
Cloud Monitoring では、ラベルは指標またはリソースに属します。指標ラベルのキー名がリソースラベルと同じ場合、クエリのラベルキー名に接頭辞 metric_ を追加することで指標ラベルを参照できます。
たとえば、指標 example.googleapis.com/user/widget_count でリソースラベルと指標ラベルの両方の名前が pod_name であるとします。
リソースラベルの値でフィルタリングするには、次の構文を使用します。
example_googleapis_com:user_widget_count{pod_name="RESOURCE_LABEL_VALUE"}指標ラベルの値でフィルタリングするには、次の構文を使用します。
example_googleapis_com:user_widget_count{metric_pod_name="METRIC_LABEL_VALUE"}
Cloud Monitoring の指標名と以前の PromQL とのマッピング
Cloud Monitoring の指標名には、ドメイン（compute.googleapis.com/ など）とパス（instance/disk/max_read_ops_count など）の 2 つのコンポーネントが含まれます。以前の PromQL は特殊文字 : と _ のみをサポートしているため、次のルールを適用して、Monitoring の指標名を以前の PromQL と互換性のあるものに変換する必要があります。
- 最初の
/を:に置き換えます。 - 他のすべての特殊文字（
.と他の/文字を含む）は_に置き換えます。
次の表に、指標名と以前の PromQL で同等のものを示します。
| Cloud Monitoring の指標名 | 以前の PromQL 指標名 |
|---|---|
compute.googleapis.com/instance/cpu/utilization |
compute_googleapis_com:instance_cpu_utilization |
logging.googleapis.com/log_entry_count |
logging_googleapis_com:log_entry_count |
Cloud Monitoring の分布値指標に対しては、Prometheus ヒストグラムと同様に、指標名に _count、_sum、_bucket サフィックスを追加して、クエリを実行できます。
| Cloud Monitoring の指標名 | 以前の PromQL 指標名 |
|---|---|
networking.googleapis.com/vm_flow/rtt |
networking_googleapis_com:vm_flow_rtt_sumnetworking_googleapis_com:vm_flow_rtt_countnetworking_googleapis_com:vm_flow_rtt_bucket
|
PromQL の互換性
Cloud Monitoring の PromQL は、アップストリームの PromQL とは若干異なる場合があります。
Cloud Monitoring の PromQL クエリは、内部クエリ言語を使用して Monarch バックエンドで部分的に評価されます。クエリ結果には違いがいくつかあります。このセクションに記載されている違いを除き、Cloud Monitoring の PromQL は Prometheus バージョン 2.44 で利用可能な PromQL と同等です。Prometheus バージョン 2.44 より後に追加された PromQL 関数はサポートされません。
UTF-8 のサポート
Cloud Monitoring の PromQL は UTF-8 クエリをサポートしています。
Prometheus 指標名が英数字と _ または : 文字のみで構成され、ラベルキーが英数字と _ 文字のみで構成されている場合は、従来の PromQL 構文を使用してクエリできます。たとえば、有効なクエリは job:my_metric:sum{label_key="label_value"} のようになります。
ただし、Prometheus 指標名で _ 文字または : 文字以外の特殊文字を使用している場合、またはラベルキーで _ 文字以外の特殊文字を使用している場合は、PromQL の UTF-8 仕様に従ってクエリを作成する必要があります。
UTF-8 指標名は引用符で囲み、中括弧内に入れる必要があります。ラベル名に以前のバージョンと互換性のない文字が含まれている場合は、ラベル名も引用符で囲む必要があります。次の有効なクエリの例はすべて同等です。
{"my.domain.com/metric/name_bucket", "label.key"="label.value"}{__name__="my.domain.com/metric/name_bucket", "label.key"="label.value"}{"__name__"="my.domain.com/metric/name_bucket", "label.key"="label.value"}
指標名の一致
指標名の完全一致のみがサポートされています。クエリには、指標名の完全一致を含める必要があります。
__name__ ラベルで正規表現マッチャーを使用する一般的なシナリオでは、次の回避策をおすすめします。
- Prometheus アダプタの構成では、多くの場合、
=~演算子を使用して複数の指標名を照合します。この使用方法を修正するには、構成を拡張して、指標ごとに個別のポリシーを使用し、各指標に明示的に名前を付けます。また、予期しない指標で誤って自動スケーリングが行われることもなくなります。 - 正規表現は、複数の非ディメンション指標を同じグラフにグラフ化する際によく使用されます。たとえば、
cpu_servicename_usageなどの指標がある場合は、ワイルドカードを使用してすべてのサービスをまとめてグラフに表示できます。このような非ディメンション指標を使用することは、Cloud Monitoring では明示的に推奨されない方法であり、この方法はクエリのパフォーマンスを著しく低下させます。この使用方法を修正するには、ディメンションを指標名に埋め込むのではなく、すべてのディメンションを指標ラベルに移動します。 - 複数の指標に対するクエリは、クエリ可能な指標を確認する際によく使用されます。代わりに、
/labels/__name__/values呼び出しを使用して指標を検出することをおすすめします。Cloud Monitoring の UI を使用して指標を検出することもできます。 - 複数の指標を照合すると、指標ごとにスクレイピング、取り込み、課金されたサンプル数を確認できます。この情報は、Cloud Monitoring の [指標の管理] ページに表示されます。サンプルの取り込み指標またはアトリビューション ID によって書き込まれたサンプル指標を使用して、この情報を指標データとして利用することもできます。
Staleness
Staleness は Monarch バックエンドでサポートされていません。
irate の計算
irate 関数のルックバック ウィンドウがステップサイズよりも小さい場合、ステップサイズに合わせてウィンドウが大きくなります。Monarch では、すべての入力データが出力で完全に無視されないようにするため、この変更が必要になります。この違いは rate の計算にも適用されます。
rate と increase の計算
rate 関数のルックバック ウィンドウがステップサイズよりも小さい場合、ステップサイズに合わせてウィンドウが大きくなります。Monarch では、すべての入力データが出力で完全に無視されないようにするため、この変更が必要になります。この違いは irate の計算にも適用されます。
補間計算と外挿計算に違いがあります。Monarch では Prometheus とは異なる補間アルゴリズムが使用されるため、この違いによってわずかに異なる結果が生じる可能性があります。たとえば、Monarch カウンタのサンプルは、Prometheus が使用している単一のタイムスタンプではなく、時間範囲で保存されます。したがって、Prometheus のタイムスタンプは除外されますが、Monarch のカウンタ サンプルはレート計算に含めることができます。これによって、通常はより正確なレートの結果が得られます。特に、基になる時系列の開始位置または終了位置をまたいでクエリする際により正確な結果が得られます。
histogram_quantile の計算
サンプルのないヒストグラムに対する PromQL の histogram_quantile 計算では、NaN 値が生成されます。内部クエリ言語の計算では値は生成されません。代わりに、タイムスタンプのデータポイントがドロップされます。
レートの計算の違いは、histogram_quantile クエリへの入力にも影響します。
特定の型の関数を異なる型の指標に対して実行する場合
アップストリームの Prometheus では弱い型付けが使用されるのに対し、Monarch では強い型付けが使用されます。そのため、ある特定の型の関数を、異なる型の指標に対して実行する場合（たとえば、GAUGE 指標に対して rate() を実行する場合や、COUNTER または型指定なしの指標に対して histogram_quantile() を実行する場合など）、それらの関数はアップストリームの Prometheus では機能しますが、Cloud Monitoring では機能しません。