Menyiapkan pengumpulan rekaman aktivitas menggunakan OpenTelemetry

Dokumen ini menunjukkan cara menyiapkan pelacakan sisi klien dan end-to-end menggunakan OpenTelemetry. Sebelum dapat mengaktifkan pelacakan end-to-end, Anda harus menyiapkan pelacakan sisi klien. Untuk mengetahui 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 peran IAM berikut kepada akun layanan yang digunakan aplikasi Anda di project Anda:

  • Pastikan Cloud Trace dan Telemetry API diaktifkan di project Anda. Untuk mengetahui informasi selengkapnya tentang cara mengaktifkan API, lihat Mengaktifkan API.

Mengonfigurasi pelacakan sisi klien

Untuk mengekspor rekaman aktivitas menggunakan OpenTelemetry Protocol (OTLP), konfigurasi aplikasi Anda. Anda dapat mengirim data ke OpenTelemetry Collector atau langsung ke Cloud Trace melalui Telemetry API. Kedua metode menggunakan dependensi dan konfigurasi yang sama. Keduanya hanya berbeda di endpoint OTLP yang digunakan eksportir.

Mengekspor rekaman aktivitas menggunakan OpenTelemetry Protocol

Untuk mengekspor rekaman aktivitas menggunakan OpenTelemetry Protocol, konfigurasi OpenTelemetry SDK dan pengekspor OTLP:

  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

    Node.js

    "@opentelemetry/exporter-trace-otlp-grpc": "^0.57.0",
"@opentelemetry/sdk-trace-base": "^1.26.0",
"@opentelemetry/sdk-trace-node": "^1.26.0",

    Python

    pip install opentelemetry-api opentelemetry-sdk
pip install opentelemetry-exporter-otlp

  2. Konfigurasi 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)

    Node.js

    const {NodeTracerProvider} = require('@opentelemetry/sdk-trace-node');
const {
  OTLPTraceExporter,
} = require('@opentelemetry/exporter-trace-otlp-grpc');
const {
  BatchSpanProcessor,
  TraceIdRatioBasedSampler,
} = require('@opentelemetry/sdk-trace-base');
const {Resource} = require('@opentelemetry/resources');
const {Spanner} = require('@google-cloud/spanner');

// Define a Resource with service metadata
const resource = new Resource({
  'service.name': 'my-service',
  'service.version': '1.0.0',
});

// Create an OTLP gRPC trace exporter
const traceExporter = new OTLPTraceExporter({
  url: 'http://localhost:4317', // Default OTLP gRPC endpoint
});

// Create a provider with a custom sampler
const provider = new NodeTracerProvider({
  sampler: new TraceIdRatioBasedSampler(1.0), // Sample 100% of traces
  resource,
  spanProcessors: [new BatchSpanProcessor(traceExporter)],
});

// Uncomment following line to register tracerProvider globally or pass it in Spanner object
// provider.register();

// Create the Cloud Spanner Client.
const spanner = new Spanner({
  projectId: projectId,
  observabilityOptions: {
    tracerProvider: provider,
    enableExtendedTracing: true,
    enableEndToEndTracing: true,
  },
});

    Python

    # Setup OpenTelemetry, trace and OTLP exporter.
tracer_provider = TracerProvider(sampler=ALWAYS_ON)
otlp_exporter = OTLPSpanExporter(endpoint="http://localhost:4317")
tracer_provider.add_span_processor(BatchSpanProcessor(otlp_exporter))

# Setup the Cloud Spanner Client.
spanner_client = spanner.Client(
    project_id,
    observability_options=dict(tracer_provider=tracer_provider, enable_extended_tracing=True, enable_end_to_end_tracing=True),
)

Mengonfigurasi pelacakan end-to-end

Bagian ini memberikan petunjuk untuk mengonfigurasi pelacakan end-to-end 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 end-to-end. Anda tidak memerlukan dependensi tambahan.

    Go

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

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

    Node.js

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

    Python

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

  2. Aktifkan pelacakan menyeluruh.

    Java

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

    Go

    Gunakan opsi EnableEndToEndTracing di konfigurasi klien untuk memilih ikut serta. 

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

    Node.js

    const spanner = new Spanner({
projectId: projectId,
observabilityOptions: {
tracerProvider: openTelemetryTracerProvider,
enableEndToEndTracing: true,
}
})

    Python

    observability_options={
"tracer_provider": tracer_provider,
"enable_end_to_end_tracing": True,
}
spanner = spanner.Client(project_id, observability_options=observability_options)

  3. Tetapkan penerapan 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{})

    Node.js

    const {propagation} = require('@opentelemetry/api');
const {W3CTraceContextPropagator} = require('@opentelemetry/core');
propagation.setGlobalPropagator(new W3CTraceContextPropagator());

    Python

    from opentelemetry.propagate import set_global_textmap
from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
set_global_textmap(TraceContextTextMapPropagator())

Atribut pelacakan menyeluruh

Perekaman aktivitas end-to-end dapat mencakup informasi berikut:

Nama atribut Deskripsi
service.name Nilai atribut selalu spanner_api_frontend.
cloud.region Region cloud Google Cloud frontend Spanner API yang melayani permintaan aplikasi Anda.
gcp.spanner.server.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.server.paxos.participantcount Jumlah peserta yang terlibat dalam transaksi. Untuk mengetahui informasi selengkapnya, lihat Proses Operasi Baca & Tulis Spanner.
gcp.spanner.isolation_level Nilai atribut adalah tingkat isolasi transaksi. Nilai yang mungkin adalah SERIALIZABLE dan REPEATABLE_READ. Untuk mengetahui informasi selengkapnya, lihat Ringkasan tingkat isolasi.

Contoh rekaman aktivitas

Trace end-to-end 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 menggunakan ini untuk memeriksa panggilan lintas region antara aplikasi dan Spanner.

Dalam contoh berikut, permintaan aplikasi Anda ditayangkan oleh frontend Spanner API di region us-west1 dan latensi jaringan adalah 8,542 md (55,47 md - 46,928 md).

Lihat rekaman aktivitas end-to-end.

Langkah berikutnya