OpenTelemetry を使用してアプリにカスタム トレースと指標を追加する

このドキュメントでは、OpenTelemetry を使用して、オブザーバビリティ コードをアプリケーションに追加する方法について説明します。OpenTelemetry は、一般的なフレームワークのテレメトリーを生成する計測ライブラリを備えています。アプリ固有の動作を測定するカスタム計測を追加することで、ライブラリで生成されたテレメトリーを拡張できます。

このドキュメントで説明する原則とコンセプトは、OpenTelemetry でサポートされているすべての言語で記述されたアプリに適用できます。計測について詳しくは、次のドキュメントをご覧ください。

サンプルコードは GitHub で入手できます。これは、Go でトレースと指標を生成するで説明されている Go アプリと同じものです。サンプル全体を表示するには、（その他）をクリックして、[GitHub で表示] を選択します。

始める前に

Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Enable the APIs

カスタム トレースを作成する

アプリケーションからカスタム トレースを生成するには、OpenTelemetry スパンを作成する計測コードを追加します。OpenTelemetry では、スパンはトレースの構成要素です。

スパンは次の手順で作成します。

  1. OpenTelemetry Tracer を取得するようにアプリを変更します。OpenTelemetry では、トレーサーはスパンを作成します。次のコードに示すように、トレーサーを取得できます。

    const scopeName = "github.com/GoogleCloudPlatform/golang-samples/opentelemetry/instrumentation/app/work"

var (
	meter                = otel.Meter(scopeName)
	tracer               = otel.Tracer(scopeName)
	sleepHistogram       metric.Float64Histogram
	subRequestsHistogram metric.Int64Histogram
)

    scopeName で表されるトレーサー名は、生成されたトレースの計測スコープを識別します。

  2. tracer インスタンスを使用してスパンを作成します。次のコードサンプルでは、computeSubrequests 関数が呼び出されるたびにスパンを生成します。

    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
}

    上記のコードサンプルでは、computeSubrequests 関数によって生成されたスパンは、関数全体で行われた処理を表します。これは、関数の最初のステップで tracer.Start を使用して新しいスパンが開始され、span.End() の前の defer キーワードによって、関数が終了する直前にスパンが終了するようにするためです。

カスタム指標を作成する

アプリケーションで指標を生成するには、アプリの実行中に取得した測定値を記録する計測コードを追加します。

指標を作成するには、次の手順を行います。

  1. OpenTelemetry Meter を取得するようにアプリを変更します。OpenTelemetry では、メーターが指標を記録するための指標計測へのアクセス権を付与します。次のコードに示すように、メーターを取得できます。

    const scopeName = "github.com/GoogleCloudPlatform/golang-samples/opentelemetry/instrumentation/app/work"

var (
	meter                = otel.Meter(scopeName)
	tracer               = otel.Tracer(scopeName)
	sleepHistogram       metric.Float64Histogram
	subRequestsHistogram metric.Int64Histogram
)

    メーター名（scopeName で表される）は、生成された指標の計測スコープを識別します。

  2. meter インスタンスを使用して、指標を記録できる計測を作成します。たとえば、次のコードでは、meter を使用して OpenTelemetry ヒストグラムを作成しています。

    sleepHistogram, err = meter.Float64Histogram("example.sleep.duration",
	metric.WithDescription("Sample histogram to measure time spent in sleeping"),
	metric.WithExplicitBucketBoundaries(0.05, 0.075, 0.1, 0.125, 0.150, 0.2),
	metric.WithUnit("s"))
if err != nil {
	panic(err)
}

    上記のコードによって、sleepHistogram という名前のヒストグラムが生成されます。

  3. sleepHistogram インスタンスを使用して、関数 randomSleep が呼び出されたときに決定されるスリープ時間を記録します。

    func randomSleep(r *http.Request) time.Duration {
	// simulate the work by sleeping 100 to 200 ms
	sleepTime := time.Duration(100+rand.Intn(100)) * time.Millisecond
	time.Sleep(sleepTime)

	hostValue := attribute.String("host.value", r.Host)
	// custom histogram metric to record time slept in seconds
	sleepHistogram.Record(r.Context(), sleepTime.Seconds(), metric.WithAttributes(hostValue))
	return sleepTime
}

    これらの計測によって記録された指標は、OpenTelemetry エクスポータの構成に基づいてアプリケーションからエクスポートされます。

次のステップ