エグザンプラを使用して指標とトレースを関連付ける

このドキュメントでは、指標データポイントに関連付けられたサンプル データポイントであるエグザンプラについて説明します。エグザンプラの 1 つの用途は、トレースへのリンクを保存して、指標データとトレースデータを関連付けることです。このドキュメントでは、OpenTelemetry を使用してエグザンプラを生成する方法についても説明します。

エグザンプラについて

エグザンプラは、任意のデータを指標データに関連付ける方法です。これらのフィールドを使用して、指標以外のデータを測定値に関連付けることができます。エグザンプラの 1 つの用途は、トレースデータを指標データに関連付けることです。Cloud Monitoring では、エグザンプラは Distribution 値タイプの指標データに関連付けることができます。分布値指標は、多くの測定値を収集してバケットでグループ化します。各ポイントはヒストグラムであり、バケット数を示す配列になります。実際の測定値は保持されず、バケットの数のみが保持されます。詳細については、分布値の指標についてをご覧ください。

指標データポイントが書き込まれると、Exemplar オブジェクトの配列をそのデータに関連付けることができます。エグザンプラを使用すると、指標データに有用な情報が付加されます。たとえば、OpenTelemetry がエグザンプラを書き込むと、現在のトレーススパンにリンクが関連付けられます。

ヒストグラム データは通常、ヒートマップで表示されます。ポイントにエグザンプラが含まれている場合、Cloud Monitoring はヒートマップにドットを追加します。

  • 指標ポイントの概要情報を表示するには、アノテーションのツールチップを有効にします。
  • トレースにアクセスするには、アノテーションを選択します。

たとえば、Go でトレースと指標を生成するで説明するサンプル アプリケーションでは、OpenTelemetry を使用して指標データ、トレースデータ、エグザンプラを書き込みます。次のスクリーンショットは、アプリケーションを複数回実行した後の prometheus/http_server_duration_milliseconds/histogram 指標の値を示しています。

複数のエグザンプラを示すヒートマップの例。

上のスクリーンショットには、複数の教師あり学習モデルが示されています。1 つのエグザンプラのツールチップが表示され、日付、トレース名、パーセンタイル、レイテンシ値が示されています。

アノテーションを選択すると、エグザンプラでリンクされているトレースが表示されます。

エグザンプラのトレースの詳細の例。

表示される情報が十分でない場合は、[Trace で表示] を選択して [Trace エクスプローラ] ページを開きます。このページでは、トレース属性を確認したり、ログエントリへのリンクに使用できます。

OpenTelemetry エグザンプラを有効にする方法

上の例に示すように、OpenTelemetry を構成して、トレースの現在のスパンを指標の測定値にリンクするエグザンプラを書き込むことができます。ただし、エグザンプラを書き込むには、次のことを行う必要があります。

  1. OpenTelemetry 指標とトレース SDK の両方を構成します。

  2. カスタム計測にエグザンプラを含めるには、指標がスパンに記録され、指標の測定値とともにスパンのコンテキストが渡されるようにします。

    たとえば、computeSubrequests 関数は前のガイダンスに従っています。関数 subRequestsHistogram.Record は tracer.Start と span.End の間に呼び出されます。これにより、遅延が発生します。また、コンテキスト ctx が tracer.Start から Record 関数に渡されている点にも注意してください。

    func computeSubrequests(r *http.Request, subRequests int) error {
	// Add custom span representing the work done for the subrequests
	ctx, span := tracer.Start(r.Context(), "subrequests")
	defer span.End()

	// Make specified number of http requests to the /single endpoint.
	for i := 0; i < subRequests; i++ {
		if err := callSingle(ctx); err != nil {
			return err
		}
	}
	// record number of sub-requests made
	subRequestsHistogram.Record(ctx, int64(subRequests))
	return nil
}

    このサンプルの詳細については、カスタム トレースと指標をアプリに追加するをご覧ください。

次のステップ