使用 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.24.0
   go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc v1.23.1
   go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.23.1
   go.opentelemetry.io/otel/metric v1.24.0
   go.opentelemetry.io/otel/sdk v1.24.0
   go.opentelemetry.io/otel/sdk/metric v1.23.1

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 延迟时间：

Java

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));
    }
  }
}

Go

// 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 Spanner API 前端发送响应的最后一个字节之间的时间（以秒为单位）。

此延迟时间指标在 Cloud Monitoring 指标中提供。

捕获客户端往返延迟时间

客户端往返延迟时间是指客户端发送到数据库（通过 GFE 和 Cloud Spanner API 前端）的 Cloud Spanner API 请求的第一个字节到客户端从数据库收到的响应的最后一个字节之间的时长（以毫秒为单位）。

不支持使用 OpenTelemetry 获取 Spanner 客户端往返延迟时间指标。您可以改为查看操作延迟时间客户端指标。如需了解详情，请参阅客户端指标说明。

您还可以使用 bridge 通过 OpenCensus 对指标进行插桩，并将数据迁移到 OpenTelemetry。

捕获查询延迟时间

查询延迟时间是在 Spanner 数据库中运行 SQL 查询所需的时长（以毫秒为单位）。

您可以使用以下代码捕获查询延迟时间：

Java

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);
  }
}

Go

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。
• 了解如何使用指标诊断延迟时间。