v1.metrics の概要

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

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

ベスト プラクティス

アプリケーションを計測してトレースデータをGoogle Cloud プロジェクトに送信する場合は、OTLP 形式のデータをコレクタに書き込むエクスポータを使用することをおすすめします。このエクスポータは、トレースデータを Telemetry API に送信します。コレクタで、ルート URL のみを指定します。

exporters:
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com

OpenTelemetry はデータ型を検出し、必要に応じて /v1/traces、/v1/metrics、/v1/logs を自動的に追加します。詳細については、OTLP/HTTP リクエストをご覧ください。

トレースデータまたは指標データを Telemetry API にエクスポートする例については、次のドキュメントをご覧ください。

コレクタを使用できない場合は、プロセス内 OTLP エクスポータを含む OpenTelemetry ライブラリを使用して、テレメトリーを Telemetry API に送信できます。トレースデータを直接エクスポートする方法については、Cloud Trace エクスポータから OTLP エンドポイントへをご覧ください。

認証

Google Cloud プロジェクトにデータを送信するために必要な認証情報を使用して、エクスポータを構成する必要があります。たとえば、コレクタを使用する場合は、通常、googleclientauth 拡張機能を使用して Google 認証情報で認証します。

トレースデータの直接エクスポートを使用する場合の認証の例については、認証を構成するをご覧ください。この例では、 Google Cloud アプリケーションのデフォルト認証情報（ADC）を使用してエクスポータを構成し、言語固有の Google Auth ライブラリをアプリケーションに追加する方法を示します。

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（monotonic、DELTA） DELTA DOUBLE /delta  
SUM（非単調、CUMULATIVE） GAUGE DOUBLE /gauge  
SUM（非単調、DELTA） サポート対象外 デルタ一時性 UpDownCounter は対象外です。
ヒストグラム（累積） 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 はこれらのラベルを設定しません。

Cloud Monitoring とデータ所在地

指標データの保存方法については、Cloud Monitoring のデータ リージョンをご覧ください。

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

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