OpenTelemetry を使用してカスタム クライアントサイド指標をキャプチャする

このドキュメントでは、OpenTelemetry を使用してカスタム クライアント指標をキャプチャする方法について説明します。カスタム クライアント指標は、Java および Go のクライアント ライブラリを使用して利用できます。

カスタム クライアントサイド指標を使用すると、システムのレイテンシの原因を特定できます。詳細については、Spanner リクエストのレイテンシ ポイントをご覧ください。

Spanner クライアント ライブラリでは、OpenTelemetry オブザーバビリティ フレームワークを使って統計情報とトレースも確認できます。詳細については、OpenTelemetry を使用してトレースの収集を設定するをご覧ください。

OpenTelemetry は、トレース、指標、ログなどのテレメトリー データを作成して管理できるオープンソースのオブザーバビリティ フレームワークとツールキットです。

始める前に

テレメトリー データをエクスポートするには、適切なオプションを使用して OpenTelemetry SDK を構成する必要があります。OpenTelemetry プロトコル（OTLP）エクスポータを使用することをおすすめします。

OpenTelemetry を使用してカスタム クライアントサイド指標を設定するには、OpenTelemetry SDK と OTLP エクスポータを構成する必要があります。

1. 次のコードを使用して、必要な依存関係をアプリケーションに追加します。

   Java

   <dependencyManagement>
     <dependencies>
       <dependency>
         <groupId>com.google.cloud</groupId>
         <artifactId>libraries-bom</artifactId>
         <version>26.32.0</version>
         <type>pom</type>
         <scope>import</scope>
       </dependency>
       <dependency>
         <groupId>io.opentelemetry</groupId>
         <artifactId>opentelemetry-bom</artifactId>
         <version>1.35.0</version>
         <type>pom</type>
         <scope>import</scope>
       </dependency>
     </dependencies>
   </dependencyManagement>
   
   <dependencies>
     <dependency>
       <groupId>com.google.cloud</groupId>
       <artifactId>google-cloud-spanner</artifactId>
     </dependency>
     <dependency>
       <groupId>io.opentelemetry</groupId>
       <artifactId>opentelemetry-sdk</artifactId>
     </dependency>
     <dependency>
       <groupId>io.opentelemetry</groupId>
       <artifactId>opentelemetry-sdk-metrics</artifactId>
     </dependency>
     <dependency>
       <groupId>io.opentelemetry</groupId>
       <artifactId>opentelemetry-sdk-trace</artifactId>
     </dependency>
     <dependency>
       <groupId>io.opentelemetry</groupId>
       <artifactId>opentelemetry-exporter-otlp</artifactId>
     </dependency>
   </dependencies>

   Go

   go.opentelemetry.io/otel v1.34.0
   go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc v1.28.0
   go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.28.0
   go.opentelemetry.io/otel/metric v1.34.0
   go.opentelemetry.io/otel/sdk v1.34.0
   go.opentelemetry.io/otel/sdk/metric v1.34.0

2. OTLP エクスポータを使用して OpenTelemetry オブジェクトを作成し、SpannerOptions を使用して Spanner に挿入します。

   Java

   // Enable OpenTelemetry metrics and traces before Injecting OpenTelemetry
   SpannerOptions.enableOpenTelemetryMetrics();
   SpannerOptions.enableOpenTelemetryTraces();
   
   // Create a new meter provider
   SdkMeterProvider sdkMeterProvider = SdkMeterProvider.builder()
       // Use Otlp exporter or any other exporter of your choice.
       .registerMetricReader(
           PeriodicMetricReader.builder(OtlpGrpcMetricExporter.builder().build()).build())
       .build();
   
   // Create a new tracer provider
   SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder()
       // Use Otlp exporter or any other exporter of your choice.
       .addSpanProcessor(SimpleSpanProcessor.builder(OtlpGrpcSpanExporter
           .builder().build()).build())
           .build();
   
   // Configure OpenTelemetry object using Meter Provider and Tracer Provider
   OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
       .setMeterProvider(sdkMeterProvider)
       .setTracerProvider(sdkTracerProvider)
       .build();
   
   // Inject OpenTelemetry object via Spanner options or register as GlobalOpenTelemetry.
   SpannerOptions options = SpannerOptions.newBuilder()
       .setOpenTelemetry(openTelemetry)
       .build();
   Spanner spanner = options.getService();
   
   DatabaseClient dbClient = spanner
       .getDatabaseClient(DatabaseId.of(projectId, instanceId, databaseId));
   
   captureGfeMetric(dbClient);
   captureQueryStatsMetric(openTelemetry, dbClient);
   
   // Close the providers to free up the resources and export the data. */
   sdkMeterProvider.close();
   sdkTracerProvider.close();

   Go

   // Ensure that your Go runtime version is supported by the OpenTelemetry-Go compatibility policy before enabling OpenTelemetry instrumentation.
   // Refer to compatibility here https://github.com/googleapis/google-cloud-go/blob/main/debug.md#opentelemetry
   
   import (
   	"context"
   	"fmt"
   	"io"
   	"log"
   	"strconv"
   	"strings"
   
   	"cloud.google.com/go/spanner"
   	"go.opentelemetry.io/otel"
   	"go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc"
   	"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
   	"go.opentelemetry.io/otel/metric"
   	sdkmetric "go.opentelemetry.io/otel/sdk/metric"
   	"go.opentelemetry.io/otel/sdk/resource"
   	sdktrace "go.opentelemetry.io/otel/sdk/trace"
   	semconv "go.opentelemetry.io/otel/semconv/v1.24.0"
   	"google.golang.org/api/iterator"
   )
   
   func enableOpenTelemetryMetricsAndTraces(w io.Writer, db string) error {
   	// db = `projects/<project>/instances/<instance-id>/database/<database-id>`
   	ctx := context.Background()
   
   	// Create a new resource to uniquely identify the application
   	res, err := newResource()
   	if err != nil {
   		log.Fatal(err)
   	}
   
   	// Enable OpenTelemetry traces by setting environment variable GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING to the case-insensitive value "opentelemetry" before loading the client library.
   	// Enable OpenTelemetry metrics before injecting meter provider.
   	spanner.EnableOpenTelemetryMetrics()
   
   	// Create a new tracer provider
   	tracerProvider, err := getOtlpTracerProvider(ctx, res)
   	defer tracerProvider.ForceFlush(ctx)
   	if err != nil {
   		log.Fatal(err)
   	}
   	// Register tracer provider as global
   	otel.SetTracerProvider(tracerProvider)
   
   	// Create a new meter provider
   	meterProvider := getOtlpMeterProvider(ctx, res)
   	defer meterProvider.ForceFlush(ctx)
   
   	// Inject meter provider locally via ClientConfig when creating a spanner client or set globally via setMeterProvider.
   	client, err := spanner.NewClientWithConfig(ctx, db, spanner.ClientConfig{OpenTelemetryMeterProvider: meterProvider})
   	if err != nil {
   		return err
   	}
   	defer client.Close()
   	return nil
   }
   
   func getOtlpMeterProvider(ctx context.Context, res *resource.Resource) *sdkmetric.MeterProvider {
   	otlpExporter, err := otlpmetricgrpc.New(ctx)
   	if err != nil {
   		log.Fatal(err)
   	}
   	meterProvider := sdkmetric.NewMeterProvider(
   		sdkmetric.WithResource(res),
   		sdkmetric.WithReader(sdkmetric.NewPeriodicReader(otlpExporter)),
   	)
   	return meterProvider
   }
   
   func getOtlpTracerProvider(ctx context.Context, res *resource.Resource) (*sdktrace.TracerProvider, error) {
   	traceExporter, err := otlptracegrpc.New(ctx)
   	if err != nil {
   		return nil, err
   	}
   
   	tracerProvider := sdktrace.NewTracerProvider(
   		sdktrace.WithResource(res),
   		sdktrace.WithBatcher(traceExporter),
   		sdktrace.WithSampler(sdktrace.AlwaysSample()),
   	)
   
   	return tracerProvider, nil
   }
   
   func newResource() (*resource.Resource, error) {
   	return resource.Merge(resource.Default(),
   		resource.NewWithAttributes(semconv.SchemaURL,
   			semconv.ServiceName("otlp-service"),
   			semconv.ServiceVersion("0.1.0"),
   		))
   }
   

GFE レイテンシをキャプチャする

Google Front End（GFE）レイテンシは、Google ネットワークがクライアントからリモート プロシージャ コールを受信してから、GFE がレスポンスの最初のバイトを受信するまでの時間（ミリ秒単位）です。

GFE レイテンシをキャプチャするには、次のコードを使用します。

static void captureGfeMetric(DatabaseClient dbClient) {
  // GFE_latency and other Spanner metrics are automatically collected
  // when OpenTelemetry metrics are enabled.

  try (ResultSet resultSet =
      dbClient
          .singleUse() // Execute a single read or query against Cloud Spanner.
          .executeQuery(Statement.of("SELECT SingerId, AlbumId, AlbumTitle FROM Albums"))) {
    while (resultSet.next()) {
      System.out.printf(
          "%d %d %s", resultSet.getLong(0), resultSet.getLong(1), resultSet.getString(2));
    }
  }
}

// GFE_Latency and other Spanner metrics are automatically collected
// when OpenTelemetry metrics are enabled.
func captureGFELatencyMetric(ctx context.Context, client spanner.Client) error {
	stmt := spanner.Statement{SQL: `SELECT SingerId, AlbumId, AlbumTitle FROM Albums`}
	iter := client.Single().Query(ctx, stmt)
	defer iter.Stop()
	for {
		row, err := iter.Next()
		if err == iterator.Done {
			return nil
		}
		if err != nil {
			return err
		}
		var singerID, albumID int64
		var albumTitle string
		if err := row.Columns(&singerID, &albumID, &albumTitle); err != nil {
			return err
		}
	}
}

このコードサンプルでは、Cloud Monitoring にエクスポートするときに、指標名に文字列 spanner/gfe_latency を追加します。この指標は、追加された文字列を使用して Cloud Monitoring で検索できます。

Cloud Spanner API リクエストのレイテンシを把握する

Cloud Spanner API リクエストのレイテンシとは、Cloud Spanner API フロントエンドがクライアントからリクエストの最初のバイトを受け取ってから、レスポンスの最後のバイトを送り終えるまでの時間（秒単位）です。

このレイテンシ指標は、Cloud Monitoring の指標の一部として利用できます。

クライアントのラウンドトリップ レイテンシをキャプチャする

クライアントのラウンドトリップ レイテンシとは、クライアントが Cloud Spanner API リクエストの最初のバイトを GFE および Cloud Spanner API フロントエンドを経由でデータベースに送信してから、レスポンスの最後のバイトをデータベースから受信するまでの時間（ミリ秒単位）のことです。

OpenTelemetry では、Spanner クライアントのラウンドトリップ レイテンシ指標はサポートされていません。代わりに、オペレーション レイテンシのクライアントサイド指標を確認することができます。詳細については、クライアントサイドの指標の説明をご覧ください。

ブリッジを使用して OpenCensus で指標を計測し、データを OpenTelemetry に移行することもできます。

クエリのレイテンシをキャプチャする

クエリのレイテンシとは、Spanner データベースで SQL クエリを実行するのにかかる時間（ミリ秒単位）のことです。

クエリのレイテンシをキャプチャするには、次のコードを使用します。

static void captureQueryStatsMetric(OpenTelemetry openTelemetry, DatabaseClient dbClient) {
  // Register query stats metric.
  // This should be done once before start recording the data.
  Meter meter = openTelemetry.getMeter("cloud.google.com/java");
  DoubleHistogram queryStatsMetricLatencies =
      meter
          .histogramBuilder("spanner/query_stats_elapsed")
          .setDescription("The execution of the query")
          .setUnit("ms")
          .build();

  // Capture query stats metric data.
  try (ResultSet resultSet = dbClient.singleUse()
      .analyzeQuery(Statement.of("SELECT SingerId, AlbumId, AlbumTitle FROM Albums"),
          QueryAnalyzeMode.PROFILE)) {

    while (resultSet.next()) {
      System.out.printf(
          "%d %d %s", resultSet.getLong(0), resultSet.getLong(1), resultSet.getString(2));
    }

    String value = resultSet.getStats().getQueryStats()
        .getFieldsOrDefault("elapsed_time", Value.newBuilder().setStringValue("0 msecs").build())
        .getStringValue();
    double elapsedTime = value.contains("msecs")
        ? Double.parseDouble(value.replaceAll(" msecs", ""))
        : Double.parseDouble(value.replaceAll(" secs", "")) * 1000;
    queryStatsMetricLatencies.record(elapsedTime);
  }
}

func captureQueryStatsMetric(ctx context.Context, mp metric.MeterProvider, client spanner.Client) error {
	meter := mp.Meter(spanner.OtInstrumentationScope)
	// Register query stats metric with OpenTelemetry to record the data.
	// This should be done once before start recording the data.
	queryStats, err := meter.Float64Histogram(
		"spanner/query_stats_elapsed",
		metric.WithDescription("The execution of the query"),
		metric.WithUnit("ms"),
		metric.WithExplicitBucketBoundaries(0.0, 0.01, 0.05, 0.1, 0.3, 0.6, 0.8, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 8.0, 10.0, 13.0,
			16.0, 20.0, 25.0, 30.0, 40.0, 50.0, 65.0, 80.0, 100.0, 130.0, 160.0, 200.0, 250.0,
			300.0, 400.0, 500.0, 650.0, 800.0, 1000.0, 2000.0, 5000.0, 10000.0, 20000.0, 50000.0,
			100000.0),
	)
	if err != nil {
		fmt.Print(err)
	}

	stmt := spanner.Statement{SQL: `SELECT SingerId, AlbumId, AlbumTitle FROM Albums`}
	iter := client.Single().QueryWithStats(ctx, stmt)
	defer iter.Stop()
	for {
		row, err := iter.Next()
		if err == iterator.Done {
			// Record query execution time with OpenTelemetry.
			elapasedTime := iter.QueryStats["elapsed_time"].(string)
			elapasedTimeMs, err := strconv.ParseFloat(strings.TrimSuffix(elapasedTime, " msecs"), 64)
			if err != nil {
				return err
			}
			queryStats.Record(ctx, elapasedTimeMs)
			return nil
		}
		if err != nil {
			return err
		}
		var singerID, albumID int64
		var albumTitle string
		if err := row.Columns(&singerID, &albumID, &albumTitle); err != nil {
			return err
		}
	}
}

このコードサンプルでは、Cloud Monitoring にエクスポートするときに、指標名に文字列 spanner/query_stats_elapsed を追加します。この指標は、追加された文字列を使用して Cloud Monitoring で検索できます。

Metrics Explorer で指標を表示する

1. Google Cloud コンソールで、[Metrics Explorer] ページに移動します。

   Metrics Explorer に移動

2. プロジェクトを選択します。

3. [指標を選択] をクリックします。

4. 次の文字列を使用して、レイテンシ指標を検索します。

   • roundtrip_latency: クライアントのラウンドトリップ レイテンシ指標用。
   • spanner/gfe_latency: GFE レイテンシ指標用。
   • spanner/query_stats_elapsed: クエリ レイテンシ指標用。

5. 指標を選択して、[適用] をクリックします。

指標のグループ化または集計の詳細については、メニューを使用してクエリを作成するをご覧ください。

次のステップ

• OpenTelemetry の詳細を確認する。
• OpenTelemetry SDK を構成する方法を確認する。
• OpenTelemetry に移行する方法を確認する。
• 指標を使用してレイテンシを診断する方法を学習する。