v1.metrics の概要

このドキュメントでは、Telemetry（OTLP）API を使用して プロジェクト Google Cloud に送信される指標データが Cloud Monitoring の構造にマッピングされる方法について説明します。この API は、 OpenTelemetry プロトコルを実装しています。`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 ライブラリをアプリケーションに追加する方法を示します。

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

  • 割り当てプロジェクトを構成します。詳細については、 割り当てプロジェクトを設定するをご覧ください。

  • アプリケーションが使用するユーザーまたはサービス アカウントに、次の Identity and Access Management（IAM）ロールを付与します。

    • Service Usage コンシューマー のロール（roles/serviceusage.serviceUsageConsumer）を割り当てプロジェクトに付与します。
    • Cloud Telemetry Writer ロール（roles/telemetry.writer）をプロジェクトに付与します。このロールにより、アプリケーションはログ、指標、トレースデータを書き込むことができます。

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 の場合）
  • __vae__（cloud.platform 属性が gcp.agent_engine の場合）
  • 空の文字列
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） サポート対象外 デルタ一時性 UpDownCounter はサポートされていません。
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 でグラフを作成するをご覧ください。

割り当て

Telemetry API に関連する割り当てについては、 Telemetry API の上限をご覧ください。