v1.metrics の概要

このドキュメントでは、Telemetry（OTLP）API を使用して プロジェクト Google Cloud に送信される指標データが Cloud Monitoring の構造にマッピングされる方法について説明します。この API は、 OpenTelemetry Line Protocol を実装しています。`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 認証情報で認証します。

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

Telemetry API を使用してテレメトリー データを Google Cloud プロジェクトに送信するには、 次の操作も行う必要があります。

Cloud Monitoring の OTLP 指標

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

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

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

Prometheus マッピング

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

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

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

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

prometheus-target ラベル 使用される値（優先順位順）
location（必須）
  • location 属性
  • cloud.availability_zone 属性
  • cloud.region 属性
  • 空の場合はポイントを拒否する
cluster
  • cluster 属性
  • k8s.cluster.name 属性
  • __gce__（cloud.platform 属性が gcp_compute_engine の場合）
  • __run__（cloud.platform 属性が gcp_cloud_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 属性
  • service.name 属性（ の場合）unknown_service:foo
  • 空の文字列
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 リソースごとに、変換によって target_info を除くすべてのリソース属性を含む service.name、service.instance.id、およびservice.namespace 指標が追加されます。

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

Prometheus 指標のマッピング

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

  • OTLP Gauge は Cloud Monitoring Gauge にマッピングされます。
  • OTLP Sum は次のようにマッピングされます。
    • Cloud Monitoring Gauge にマッピングされます。is_monotonic が false に設定されている場合。
    • `aggregation_temporality` が `AGGREGATION_TEMPORALITY_CUMULATIVE` に設定されている場合は、Cloud Monitoring Cumulative にマッピングされます。
    • `aggregation_temporality` が `AGGREGATION_TEMPORALITY_DELTA` に設定されている場合は、Cloud Monitoring Delta にマッピングされます。
  • OTLP Histogram は、Cloud Monitoring Distribution に、 指標の種類が 累積またはデルタ の 、 aggregation_temporality の値に応じてマッピングされます。
  • OTLP Summary 指標は、各コンポーネント（count、sum、各 quantile）の個別の時系列に展開されます。
    • カウント指標と合計指標の名前には、それぞれ _count または _sum が付加され、Cloud Monitoring 累積指標としてDOUBLE型で書き込まれます。
    • 各分位点は、独自の ゲージ 時系列（ タイプ DOUBLE）になり、quantile ラベルが付きます。

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

OTLP ポイントの種類 Monitoring 指標の種類 Monitoring 値の型 サフィックス メモ
GAUGE GAUGE DOUBLE /gauge  
GAUGE（metric.metadata["prometheus.type"]="unknown"） GAUGE DOUBLE /unknown Prometheus Unknowns は、 OpenTelemetry Collector によってカウンタとゲージに分割されます。
SUM（monotonic、CUMULATIVE） CUMULATIVE DOUBLE /counter  
SUM（monotonic、CUMULATIVE、 metric.metadata["prometheus.type"]="unknown"） CUMULATIVE DOUBLE /unknown:counter Prometheus Unknowns は、 OpenTelemetry Collector によってカウンタとゲージに分割されます。
SUM（monotonic、DELTA） DELTA DOUBLE /delta  
SUM（non-monotonic、CUMULATIVE） GAUGE DOUBLE /gauge  
SUM（non-monotonic、DELTA） サポート対象外 Delta-temporality UpDownCounters はサポートされていません。
HISTOGRAM（CUMULATIVE） CUMULATIVE 明示的なバケットを持つ DISTRIBUTION /histogram  
EXPONENTIAL HISTOGRAM（CUMULATIVE） CUMULATIVE 指数バケットを持つ DISTRIBUTION /histogram  
HISTOGRAM（DELTA） DELTA 明示的なバケットを持つ DISTRIBUTION /histogram:delta  
EXPONENTIAL HISTOGRAM（DELTA） DELTA 指数バケットを持つ DISTRIBUTION /histogram:delta  
SUMMARY
(合計,
カウント,
分位点)		  
CUMULATIVE
CUMULATIVE
GAUGE
DOUBLE
DOUBLE
DOUBLE		  
_sum/summary:counter
_count/summary
/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 指標のすべての整数ポイント値を double 値に変換します。

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

Cloud Monitoring とデータ所在地

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

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

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