Menyiapkan pengumpulan rekaman aktivitas menggunakan OpenTelemetry

Dokumen ini menunjukkan cara menyiapkan pelacakan sisi klien dan menyeluruh menggunakan OpenTelemetry. Anda harus menyiapkan pelacakan sisi klien sebelum dapat memilih untuk menggunakan pelacakan menyeluruh. Untuk informasi selengkapnya, lihat Ringkasan pengumpulan rekaman aktivitas.

Sebelum memulai

  • Untuk memastikan bahwa akun layanan yang digunakan aplikasi Anda memiliki izin yang diperlukan untuk menyiapkan pengumpulan rekaman aktivitas, minta administrator untuk memberikan akun layanan yang digunakan aplikasi Anda peran IAM Cloud Trace Agent (roles/cloudtrace.agent) di project Anda.

Mengonfigurasi pelacakan sisi klien

Untuk mengonfigurasi pelacakan sisi klien, Anda perlu mengekspor rekaman aktivitas. Anda dapat mengekspor rekaman aktivitas ke kolektor atau langsung ke backend observabilitas. Anda dapat mengonfigurasi pelacakan menggunakan OpenTelemetry API.

Mengekspor rekaman aktivitas ke kolektor menggunakan OpenTelemetry API

Untuk mengekspor trace ke kolektor menggunakan OpenTelemetry API, konfigurasikan OpenTelemetry SDK dan eksporter OLTP:

  1. Tambahkan dependensi yang diperlukan ke aplikasi Anda menggunakan kode berikut:

    Java

    <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-trace</artifactId>
</dependency>
<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-exporter-otlp</artifactId>
</dependency>

    Go

    go.opentelemetry.io/otel v1.28.0
go.opentelemetry.io/otel/sdk v1.28.0
go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.28.0

  2. Konfigurasikan objek OpenTelemetry dan aktifkan pelacakan.

    Java

    Resource resource = Resource
    .getDefault().merge(Resource.builder().put("service.name", "My App").build());

OtlpGrpcSpanExporter otlpGrpcSpanExporter =
    OtlpGrpcSpanExporter
        .builder()
        .setEndpoint(otlpEndpoint) // Replace with your OTLP endpoint
        .build();

// Using a batch span processor
// You can use `.setScheduleDelay()`, `.setExporterTimeout()`,
// `.setMaxQueueSize`(), and `.setMaxExportBatchSize()` to further customize.
BatchSpanProcessor otlpGrpcSpanProcessor =
    BatchSpanProcessor.builder(otlpGrpcSpanExporter).build();

// Create a new tracer provider
sdkTracerProvider = SdkTracerProvider.builder()
    // Use Otlp exporter or any other exporter of your choice.
    .addSpanProcessor(otlpGrpcSpanProcessor)
    .setResource(resource)
    .setSampler(Sampler.traceIdRatioBased(0.1))
    .build();

// Export to a collector that is expecting OTLP using gRPC.
OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
    .setTracerProvider(sdkTracerProvider).build();

// Enable OpenTelemetry traces before Injecting OpenTelemetry
SpannerOptions.enableOpenTelemetryTraces();

// Inject OpenTelemetry object via Spanner options or register as GlobalOpenTelemetry.
SpannerOptions options = SpannerOptions.newBuilder()
    .setOpenTelemetry(openTelemetry)
    .build();
Spanner spanner = options.getService();

    Go

    
// Ensure that your Go runtime version is supported by the OpenTelemetry-Go
// compatibility policy before enabling OpenTelemetry instrumentation.

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

ctx := context.Background()

// Create a new resource to uniquely identify the application
res, err := resource.Merge(resource.Default(),
	resource.NewWithAttributes(semconv.SchemaURL,
		semconv.ServiceName("My App"),
		semconv.ServiceVersion("0.1.0"),
	))
if err != nil {
	log.Fatal(err)
}

// Create a new OTLP exporter.
defaultOtlpEndpoint := "http://localhost:4317" // Replace with the endpoint on which OTLP collector is running
traceExporter, err := otlptracegrpc.New(ctx, otlptracegrpc.WithEndpoint(defaultOtlpEndpoint))
if err != nil {
	log.Fatal(err)
}

// Create a new tracer provider
tracerProvider := sdktrace.NewTracerProvider(
	sdktrace.WithResource(res),
	sdktrace.WithBatcher(traceExporter),
	sdktrace.WithSampler(sdktrace.TraceIDRatioBased(0.1)),
)

// Register tracer provider as global
otel.SetTracerProvider(tracerProvider)

Mengekspor langsung ke backend observabilitas menggunakan OpenTelemetry API

Untuk mengonfigurasi library klien Spanner agar dapat mengekspor span rekaman aktivitas ke Cloud Trace atau backend penyedia layanan observabilitas lainnya secara langsung, ikuti langkah-langkah berikut:

  1. Tambahkan dependensi yang diperlukan ke aplikasi Anda menggunakan kode berikut:

    Java

    <dependency>
<groupId>com.google.cloud</groupId>
<artifactId>google-cloud-spanner</artifactId>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-api</artifactId>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-sdk</artifactId>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-sdk-common</artifactId>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-sdk-trace</artifactId>
</dependency>
<dependency>
<groupId>com.google.cloud.opentelemetry</groupId>
<artifactId>exporter-trace</artifactId>
<version>0.30.0</version>
</dependency>

    Go

    go.opentelemetry.io/otel v1.28.0
go.opentelemetry.io/otel/sdk v1.28.0
github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace v1.24.1

  2. Konfigurasikan objek OpenTelemetry dan aktifkan pelacakan.

    Java

    Resource resource = Resource
    .getDefault().merge(Resource.builder().put("service.name", "My App").build());

SpanExporter traceExporter = TraceExporter.createWithConfiguration(
    TraceConfiguration.builder().setProjectId(projectId).build()
);

// Using a batch span processor
// You can use `.setScheduleDelay()`, `.setExporterTimeout()`,
// `.setMaxQueueSize`(), and `.setMaxExportBatchSize()` to further customize.
BatchSpanProcessor otlpGrpcSpanProcessor =
    BatchSpanProcessor.builder(traceExporter).build();

// Create a new tracer provider
sdkTracerProvider = SdkTracerProvider.builder()
    // Use Otlp exporter or any other exporter of your choice.
    .addSpanProcessor(otlpGrpcSpanProcessor)
    .setResource(resource)
    .setSampler(Sampler.traceIdRatioBased(0.1))
    .build();

// Export to a collector that is expecting OTLP using gRPC.
OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
    .setTracerProvider(sdkTracerProvider).build();

// Enable OpenTelemetry traces before Injecting OpenTelemetry
SpannerOptions.enableOpenTelemetryTraces();

// Inject OpenTelemetry object via Spanner options or register it as global object.
// To register as the global OpenTelemetry object,
// use "OpenTelemetrySdk.builder()....buildAndRegisterGlobal()".
SpannerOptions options = SpannerOptions.newBuilder()
    .setOpenTelemetry(openTelemetry)
    .build();
Spanner spanner = options.getService();

    Go

    
// Ensure that your Go runtime version is supported by the OpenTelemetry-Go
// compatibility policy before enabling OpenTelemetry instrumentation.

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

// Create a new resource to uniquely identify the application
res, err := resource.Merge(resource.Default(),
	resource.NewWithAttributes(semconv.SchemaURL,
		semconv.ServiceName("My App"),
		semconv.ServiceVersion("0.1.0"),
	))
if err != nil {
	log.Fatal(err)
}

// Create a new cloud trace exporter
exporter, err := traceExporter.New(traceExporter.WithProjectID(projectID))
if err != nil {
	log.Fatal(err)
}

// Create a new tracer provider
tracerProvider := sdktrace.NewTracerProvider(
	sdktrace.WithResource(res),
	sdktrace.WithBatcher(exporter),
	sdktrace.WithSampler(sdktrace.TraceIDRatioBased(0.1)),
)

// Register tracer provider as global
otel.SetTracerProvider(tracerProvider)

Mengonfigurasi pelacakan menyeluruh

Bagian ini memberikan petunjuk untuk mengonfigurasi pelacakan menyeluruh (Pratinjau) di library klien Spanner:

  1. Tambahkan dependensi yang diperlukan ke aplikasi Anda menggunakan kode berikut:

    Java

    Dependensi pelacakan sisi klien yang ada sudah cukup untuk mengonfigurasi pelacakan menyeluruh. Anda tidak memerlukan dependensi tambahan.

    Go

    Selain dependensi yang diperlukan untuk pelacakan sisi klien, Anda juga memerlukan dependensi berikut:

    go.opentelemetry.io/otel/propagation v1.28.0

  2. Ikut serta dalam pelacakan menyeluruh.

    Java

    SpannerOptions options = SpannerOptions.newBuilder()
  .setOpenTelemetry(openTelemetry)
  .setEnableEndToEndTracing(/* enableEndtoEndTracing= */ true)
  .build();

    Go

    Gunakan opsi EnableEndToEndTracing dalam konfigurasi klien untuk ikut serta. 

    client, _ := spanner.NewClientWithConfig(ctx, "projects/test-project/instances/test-instance/databases/test-db", spanner.ClientConfig{
SessionPoolConfig: spanner.DefaultSessionPoolConfig,
EnableEndToEndTracing:      true,
}, clientOptions...)

  3. Menetapkan penyebaran konteks rekaman aktivitas di OpenTelemetry.

    Java

    OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
  .setTracerProvider(sdkTracerProvider)
  .setPropagators(ContextPropagators.create(W3CTraceContextPropagator.getInstance()))
  .buildAndRegisterGlobal();

    Go

    // Register the TraceContext propagator globally.
otel.SetTextMapPropagator(propagation.TraceContext{})

Atribut pelacakan menyeluruh

Pelacakan menyeluruh dapat mencakup informasi berikut:

Nama atribut Deskripsi
service.name Nilai atribut selalu spanner_api_frontend.
cloud.region Region cloud Google Cloud dari frontend Spanner API yang menayangkan permintaan aplikasi Anda.
gcp.spanner.query.fingerprint Nilai atribut adalah sidik jari kueri. Untuk men-debug kueri ini lebih lanjut, lihat kolom TEXT_FINGERPRINT di tabel Statistik kueri.
gcp.spanner.participants.count Jumlah peserta yang terlibat dalam transaksi. Untuk mengetahui informasi selengkapnya, lihat Proses Operasi Baca & Tulis Spanner.

Trace sampel

Trace menyeluruh memungkinkan Anda melihat detail berikut:

  • Latensi antara aplikasi Anda dan Spanner. Anda dapat menghitung latensi jaringan untuk melihat apakah ada masalah jaringan.
  • Region cloud frontend Spanner API tempat permintaan aplikasi Anda ditayangkan. Anda dapat menggunakannya untuk memeriksa panggilan lintas wilayah antara aplikasi dan Spanner.

Pada contoh berikut, permintaan aplikasi Anda ditayangkan oleh frontend Spanner API di region us-west1 dan latensi jaringannya adalah 8.542 md (55,47 md - 46,928 md).

Melihat rekaman aktivitas menyeluruh.

Langkah selanjutnya