v1.metrics の概要

このドキュメントでは、Telemetry（OTLP）API を使用して Google Cloud プロジェクトに送信された指標データが Cloud Monitoring の構造にマッピングされる方法について説明します。この API は、OpenTelemetry OTLP プロトコルを実装します。otlphttp エクスポータと OpenTelemetry Collector を使用してアプリケーションを計測する場合、または OpenTelemetry SDK を使用する場合は、この API にデータを送信できます。

OpenTelemetry は、テレメトリーの取り込みと可視化をサポートする Google Cloudエンジニアが常駐する、 Google Cloudがサポートするオープンソース プロジェクトです。

Cloud Monitoring の OTLP 指標

OpenTelemetry Collector と otlphttp エクスポータを使用して指標が Cloud Monitoring に取り込まれる場合、または OpenTelemetry SDK を使用して直接送信される場合、OTLP 指標は Cloud Monitoring 指標構造にマッピングされます。このセクションでは、次のことを説明します。

モニタリング対象リソースのマッピング

すべての指標ポイントは、Prometheus マッピングを使用して、Google Cloud Managed Service for Prometheus にそのまま書き込まれます。

Prometheus マッピング

Prometheus 指標では、モニタリング対象リソースタイプ prometheus_target を使用する必要があります。

prometheus_target リソースタイプの次のラベルは、Monarch 内のデータをスキーマ化して効率的に保存するために使用されます。これらの属性の値を正確に指定するほど、クエリ可能性とスケーラビリティが向上します。

明示的な値がない場合に使用するフォールバック ロジックを実装していますが、これらのラベルの値を設定する際は、できるだけ明示的に指定することを強くおすすめします。

次の表に、ラベルの値のソースを優先順位の高い順に示します。

prometheus-target ラベル 使用された値（優先順位順）
location（必須）
  • location 属性
  • cloud.availability_zone 属性
  • cloud.region 属性
cluster
  • cluster 属性
  • k8s.cluster.name 属性
  • cloud.platform 属性が gcp_compute_engine の場合、__gce__
  • cloud.platform 属性が gcp_cloud_run の場合、__run__
  • 空の文字列
namespace
  • namespace 属性
  • k8s.namespace.name 属性
  • service.namespace 属性
  • 空の文字列
job
  • job 属性
  • "service.namespace" + "/" + service.namespace 属性
  • service.name 属性
  • service.name 属性（unknown_service:foo ではない場合）
  • faas.name 属性
  • k8s.deployment.name 属性
  • k8s.statefulset.name 属性
  • k8s.job.name 属性
  • k8s.cronjob.name 属性
  • unknown_service:foo の場合、service.name 属性
  • 空の文字列
instance
空の場合はポイントを拒否
  • instance 属性
  • service.instance.id 属性
  • faas.instance 属性
  • k8s.pod.name:k8s.container.name 属性
  • コンテナ名が存在しない場合は k8s.pod.name 属性
  • host.id 属性

指標のマッピング

指標は Prometheus の時系列形式に変換されます。指標名にはドメインがないか、ドメイン prometheus.googleapis.com が必要です。変換後、指標名には prometheus.googleapis.com 接頭辞と、OTLP ポイントの種類に基づく追加の接尾辞が含まれます。結果の Cloud Monitoring 指標は次の構造になります。

prometheus.googleapis.com/{metric_name}/{suffix}

また、一意の OpenTelemetry リソースごとに、変換によって service.name、service.instance.id、service.namespace を除くすべてのリソース属性を含む target_info 指標が追加されます。

コレクタが値の型を INT64 として指定している場合でも、すべての OTLP INT64 指標は Cloud Monitoring の DOUBLE 値の型に変換されます。この変更が行われるのは、時系列が Monarch にある場合、値の型を変更できないためです。INT64 値をサポートする最も一般的な結果は、指標を削除することでのみ解決できる競合が発生することです。

Prometheus 指標のマッピング

指標タイプは次のようにマッピングされます。

  • OTLP ゲージは Cloud Monitoring のゲージにマッピングされます。
  • OTLP Sum は次のようにマッピングされます。
    • is_monotonic が false に設定されている場合、Cloud Monitoring のゲージ。
    • aggregation_temporality が AGGREGATION_TEMPORALITY_CUMULATIVE に設定されている場合、Cloud Monitoring の累積。
    • aggregation_temporality が AGGREGATION_TEMPORALITY_DELTA に設定されている場合、Cloud Monitoring の delta。
  • OTLP ヒストグラムは、aggregation_temporality の値に応じて、指標の種類が cumulative または delta の Cloud Monitoring 分布にマッピングされます。
  • OTLP の概要指標は、各コンポーネント（count、sum、各 quantile）の個々の時系列に展開されます。
    • カウント指標と合計指標の名前には、それぞれ _count または _sum が接尾辞として付けられ、Cloud Monitoring の DOUBLE 型の累積指標として書き込まれます。
    • 各分位点は、quantile ラベルを持つ DOUBLE タイプの独自のゲージ時系列になります。

次の表に、指標のマッピングの概要を示します。

OTLP ポイントの種類 モニタリングの 指標の種類 モニタリングの 値の型 サフィックス メモ
GAUGE GAUGE DOUBLE /gauge  
GAUGE（metric.metadata["prometheus.type"]="unknown"） GAUGE DOUBLE /unknown Prometheus の不明な値は、OpenTelemetry Collector によってカウンタとゲージに分割されます。
SUM（単調増加、累積） CUMULATIVE DOUBLE /counter  
SUM（monotonic、CUMULATIVE、metric.metadata["prometheus.type"]="unknown"） CUMULATIVE DOUBLE /unknown:counter Prometheus の不明な値は、OpenTelemetry Collector によってカウンタとゲージに分割されます。
SUM（単調増加、DELTA） DELTA DOUBLE /delta  
SUM（非単調、累積） GAUGE DOUBLE /gauge  
ヒストグラム（累積） CUMULATIVE 明示的なバケットを使用した DISTRIBUTION /histogram  
指数ヒストグラム（累積） CUMULATIVE 指数関数的バケットを使用した分布 /histogram  
ヒストグラム（差分） DELTA 明示的なバケットを使用した DISTRIBUTION /histogram:delta  
指数ヒストグラム（デルタ） DELTA 指数関数的バケットを使用した分布 /histogram:delta  
SUMMARY
(sum,
count,
quantile)		  
CUMULATIVE
CUMULATIVE
GAUGE		  
DOUBLE
DOUBLE
DOUBLE		  
_sum/summary:counter
_count/summary
/summary		 要約データポイントは、カウント、合計、計算された各分位数に対して 1 つずつ、複数の時系列として書き込まれます。クォンタイル指標も quantile ラベル付きで生成されます。

googlemanagedprometheus エクスポータと Telemetry API の違い

Telemetry API（telemetry.googleapis.com）は、googlemanagedprometheus エクスポータとは異なる方法で指標を処理します。

  • Telemetry API では、指標名にピリオド（.）とスラッシュ（/）を使用できます。googlemanagedprometheus エクスポータは、これらの文字のすべてのインスタンスをアンダースコア（_）文字に変換します。たとえば、prometheus.googleapis.com/foo.bar/gauge という OTLP 指標は、OTLP エクスポータによってそのままエクスポートされますが、googlemanagedprometheus エクスポータによって prometheus.googleapis.com/foo_bar/gauge としてエクスポートされます。

    指標が取り込まれると、Cloud Monitoring は名前に基づいて指標記述子を作成します。取り込みパスでのピリオド（.）とスラッシュ（/）文字の処理方法の違いにより、googlemanagedprometheus エクスポータを使用して取り込まれた指標と otlphttp エクスポータを使用して取り込まれた指標で、結果の指標記述子が異なります。両方の取り込みパスを使用すると、2 つの指標セットが作成されます。クエリ時に完全な結果を取得するには、Prometheus バージョンと OTLP バージョンの指標の結果を手動で統合する必要があります。

  • 単位が存在する場合、Telemetry API は指標名に単位を追加しません。また、カウンタに _total 接尾辞を追加しません。したがって、Telemetry API を使用して prometheus.googleapis.com/foo/counter としてエクスポートされた指標は、googlemanagedprometheus エクスポーターによって prometheus.googleapis.com/foo_seconds_total/counter としてエクスポートされます。この違いは、_total 接尾辞と _ratio 接尾辞にも適用されます。

  • API は、指数ヒストグラムから導出された分布値の sum_of_squared_deviation 値を合成します。googlemanagedprometheus エクスポーターは、指数ヒストグラムに対してこのフィールドを設定しません。

  • API は、すべての整数ポイント値を Prometheus 指標の倍精度値に変換します。

  • scope_version または scope_name ラベルの値が空の場合、API はこれらのラベルを設定しません。

取り込まれたデータを表示する場所

Telemetry API を介して取り込まれた指標データは、[Metrics エクスプローラ] ページを使用して表示できます。指標データの表示とグラフ作成については、Metrics Explorer でグラフを作成するをご覧ください。