Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

איסוף מדדים מותאמים אישית בצד הלקוח באמצעות OpenTelemetry

במסמך הזה מוסבר איך ללכוד מדדים מותאמים אישית של לקוחות באמצעות OpenTelemetry. מדדים מותאמים אישית של לקוחות זמינים באמצעות ספריות הלקוח של Java ושל Go.

מדדים מותאמים אישית בצד הלקוח יכולים לעזור לכם למצוא את מקור ההשהיה במערכת. מידע נוסף זמין במאמר בנושא נקודות השהיה בבקשת Spanner.

ספריות הלקוח של Spanner מספקות גם נתונים סטטיסטיים ומעקבים באמצעות Framework הניראות (observability) של OpenTelemetry. מידע נוסף זמין במאמר בנושא הגדרת איסוף מעקבים באמצעות OpenTelemetry.

‫OpenTelemetry הוא מסגרת וערכת כלים בקוד פתוח שמאפשרות לכם ליצור ולנהל נתוני טלמטריה כמו עקבות, מדדים ויומנים.

לפני שמתחילים

צריך להגדיר את OpenTelemetry SDK עם האפשרויות המתאימות לייצוא נתוני הטלמטריה. מומלץ להשתמש ב-exporter של OpenTelemetry Protocol‏ (OTLP).

כדי להגדיר מדדים מותאמים אישית בצד הלקוח באמצעות OpenTelemetry, צריך להגדיר את OpenTelemetry SDK ואת כלי הייצוא OTLP:

מוסיפים את יחסי התלות הנדרשים לאפליקציה באמצעות הקוד הבא:

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.opentelemetry.io/otel v1.43.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.43.0
go.opentelemetry.io/otel/sdk v1.43.0
go.opentelemetry.io/otel/sdk/metric v1.43.0

יוצרים אובייקט OpenTelemetry עם כלי הייצוא OTLP ומזריקים אותו ל-Spanner באמצעות SpannerOptions:

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

המשך

// 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‏ (GFE) הוא משך הזמן במילי-שניות שחלף בין הרגע שבו הרשת של Google קיבלה קריאה לפרוצדורה מרוחקת מהלקוח לבין הרגע שבו ממשק הקצה של Google קיבל את הבייט הראשון של התגובה.

אפשר לתעד את זמן האחזור של 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));
    }
  }
}

המשך

// 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
		}
	}
}

דוגמת הקוד מוסיפה את המחרוזת spanner/gfe_latency לשם המדד כשהוא מיוצא ל-Cloud Monitoring. אפשר לחפש את המדד הזה ב-Monitoring באמצעות המחרוזת שנוספה.

תיעוד של זמן האחזור של בקשות ל-Cloud Spanner API

החביון של בקשת Cloud Spanner API הוא הזמן בשניות שחלף בין הבייט הראשון של בקשת הלקוח שחלק הקצה הקדמי של Cloud Spanner API מקבל, לבין הבייט האחרון של התגובה שחלק הקצה הקדמי של Cloud Spanner API שולח.

מדד ההשהיה הזה זמין כחלק ממדדי המעקב.

תיעוד זמן האחזור הלוך ושוב של הלקוח

השהיית הלוך ושוב של הלקוח היא משך הזמן במילישניות בין הבייט הראשון של בקשת Cloud Spanner API שהלקוח שולח למסד הנתונים (דרך GFE וגם דרך ממשק הקצה של Cloud Spanner API), לבין הבייט האחרון של התגובה שהלקוח מקבל ממסד הנתונים.

אין תמיכה במדד זמן האחזור הלוך ושוב של לקוח Spanner באמצעות OpenTelemetry. במקום זאת, אפשר להציג את מדד זמן האחזור של הפעולה בצד הלקוח. מידע נוסף זמין במאמר תיאורים של מדדים מצד הלקוח.

אפשר גם להגדיר את המדד באמצעות OpenCensus עם גשר ולהעביר את הנתונים אל OpenTelemetry.

תיעוד זמן האחזור של השאילתה

זמן האחזור של השאילתה הוא משך הזמן באלפיות השנייה שנדרש להרצת שאילתות SQL במסד הנתונים של Spanner.

אפשר לתעד את זמן האחזור של השאילתה באמצעות הקוד הבא:

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

המשך

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

כשמייצאים את שם המדד ל-Monitoring, מחרוזת הקוד spanner/query_stats_elapsed מצורפת אליו. אפשר לחפש את המדד הזה ב-Monitoring באמצעות המחרוזת שנוספה.

הצגת מדדים ב-Metrics Explorer

נכנסים לדף Metrics Explorer במסוף Google Cloud .

לדף Metrics Explorer
בוחרים את הפרויקט הרצוי.
לוחצים על בחירת מדד.
אפשר לחפש מדדי זמן אחזור באמצעות המחרוזות הבאות:
- ‫roundtrip_latency: למדד השהייה הלוך ושוב של הלקוח.
- ‫spanner/gfe_latency: למדד זמן האחזור של GFE.
- ‫spanner/query_stats_elapsed: למדד זמן האחזור של השאילתה.
בוחרים את המדד ולוחצים על אישור.

מידע נוסף על קיבוץ או צבירה של מדדים זמין במאמר יצירת שאילתות באמצעות תפריטים.

המאמרים הבאים

OpenTelemetry
איך מגדירים את OpenTelemetry SDK
כך עוברים ל-OpenTelemetry.
איך משתמשים במדדים כדי לאבחן את זמן האחזור.

איסוף מדדים מותאמים אישית בצד הלקוח באמצעות OpenTelemetry קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

לפני שמתחילים

Java

המשך

Java

המשך

תיעוד זמן האחזור של GFE

Java

המשך

תיעוד של זמן האחזור של בקשות ל-Cloud Spanner API

תיעוד זמן האחזור הלוך ושוב של הלקוח

תיעוד זמן האחזור של השאילתה

Java

המשך

הצגת מדדים ב-Metrics Explorer

המאמרים הבאים

איסוף מדדים מותאמים אישית בצד הלקוח באמצעות OpenTelemetry