Menyiapkan pengumpulan rekaman aktivitas menggunakan OpenTelemetry

Dokumen ini menunjukkan cara menyiapkan pelacakan sisi klien dan menyeluruh menggunakan OpenTelemetry. Sebelum dapat memilih pelacakan menyeluruh, Anda harus menyiapkan pelacakan sisi klien. Untuk mengetahui informasi selengkapnya, lihat Ringkasan pengumpulan trace.

Sebelum memulai

  • Untuk memastikan bahwa akun layanan yang digunakan aplikasi Anda memiliki izin yang diperlukan untuk menyiapkan pengumpulan trace, minta administrator untuk memberikan peran IAM berikut ke 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 trace menggunakan OpenTelemetry Protocol (OTLP), konfigurasikan aplikasi Anda. Anda dapat mengirim data ke OpenTelemetry Collector atau langsung ke Cloud Trace melalui Telemetry API. Kedua metode tersebut menggunakan dependensi dan konfigurasi yang sama. Keduanya hanya berbeda dalam endpoint OTLP yang digunakan oleh pengekspor.

Mengekspor trace menggunakan OpenTelemetry Protocol

Untuk mengekspor trace menggunakan OpenTelemetry Protocol, konfigurasikan 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. 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)

    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 menyeluruh

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

    Python

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

  2. Pilih pelacakan menyeluruh.

    Java

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

    Go

    Gunakan opsi EnableEndToEndTracing dalam konfigurasi klien untuk memilih. 

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

Trace menyeluruh dapat mencakup informasi berikut:

Nama atribut Deskripsi
service.name Nilai atribut selalu spanner_api_frontend.
cloud.region Region Google Cloud cloud frontend Spanner API yang menayangkan 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 trace

Trace menyeluruh memungkinkan Anda melihat detail berikut:

  • Latensi antara aplikasi Anda dan Spanner. Anda dapat menghitung latensi jaringan untuk melihat apakah Anda memiliki masalah jaringan.
  • Region cloud frontend Spanner API tempat permintaan aplikasi Anda ditayangkan. Anda dapat menggunakan ini untuk memeriksa panggilan lintas region antara aplikasi Anda 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