Memantau performa dengan rekaman aktivitas sisi klien

Untuk memantau dan men-debug permintaan Firestore dalam mode Datastore (Datastore) secara menyeluruh, Anda dapat mengaktifkan rekaman aktivitas di library klien Java. Pelacakan sisi klien dapat memberikan sinyal tentang performa yang dialami oleh aplikasi Anda, serta insight yang dapat membantu men-debug masalah.

Tracing sisi klien, yang dikumpulkan dengan menjalankan RPC dari klien, memberikan informasi berikut:

  • Rentang dengan stempel waktu saat klien mengirim permintaan RPC dan saat klien menerima respons RPC, termasuk latensi yang disebabkan oleh jaringan dan sistem klien
  • Atribut (key-value pair) yang menampilkan informasi tentang klien dan konfigurasinya.
  • Log yang terkait dengan peristiwa utama dalam rentang.
  • Pelacakan tumpukan jika terjadi error pada klien.

OpenTelemetry

Trace untuk library klien Java diinstrumentasikan menggunakan API OpenTelemetry. OpenTelemetry adalah framework observabilitas open source standar industri. OpenTelemetry menawarkan berbagai alat seperti API dan SDK instrumentasi, pengumpul, eksportir khusus backend, dan opsi konfigurasi fleksibel seperti kontrol pengambilan sampel, batas rentang, dan lainnya.

Mengekspor rekaman aktivitas dengan pengekspor dan pengumpul

Sebagai bagian dari konfigurasi, Anda dapat mengekspor rekaman aktivitas ke backend kemampuan pengamatan. Sebagian besar penyedia layanan observabilitas menawarkan pengekspor untuk Anda gunakan, seperti Cloud Trace.

Selain pengekspor, OpenTelemetry merekomendasikan penyiapan Collector. Pengumpul memungkinkan layanan Anda memindahkan data dengan cepat dan memungkinkan pengumpul menangani pemrosesan tambahan seperti percobaan ulang, pengelompokan, dan enkripsi. Pengumpul berjalan bersama aplikasi Anda. Pengumpul menerima pesan OpenTelemetry Protocol (OTLP), memproses pesan, dan mengekspornya ke backend kemampuan pengamatan Anda.

Batasan

Rentang rekaman aktivitas hanya tersedia untuk library klien Java.

Penagihan

Selain penggunaan Datastore, pelacakan sisi klien dapat menimbulkan biaya.

Tidak ada biaya untuk mengumpulkan rekaman aktivitas atau penggunaan framework OpenTelemetry.

Penyerapan rentang aktivitas ke backend kemampuan pengamatan Anda mungkin dikenai biaya. Misalnya, jika Anda menggunakan Cloud Trace sebagai backend, Anda akan ditagih sesuai dengan harga Cloud Trace. Jika Anda menggunakan penyedia layanan observabilitas lain, cari tahu model penagihan dan biaya terkaitnya.

Untuk lebih memahami penagihan, mulailah dengan rasio pengambilan sampel rekaman aktivitas yang kecil (rekam aktivitas sebagian kecil RPC) berdasarkan traffic Anda.

Sebelum memulai

Sebelum memulai:

  • Pastikan Anda menyiapkan akun layanan yang digunakan aplikasi Anda untuk menulis rekaman aktivitas ke backend pengamatan dengan peran Identity and Access Management yang diperlukan:

    Operasi rekaman aktivitas Peran IAM
    Membaca rekaman aktivitas roles/cloudtrace.user
    Menulis rekaman aktivitas roles/cloudtrace.agent
    Membaca/menulis rekaman aktivitas roles/cloudtrace.admin

  • Pastikan Trace API diaktifkan di project ini.

Mengonfigurasi rekaman aktivitas sisi klien

Bagian ini memberikan contoh konfigurasi untuk rekaman aktivitas sisi klien. Anda dapat mengekspor ke Pengumpul atau langsung ke backend kemampuan pengamatan. Anda juga memiliki opsi berikut untuk mengonfigurasi rekaman aktivitas sisi klien:

Mengekspor rekaman aktivitas ke Collector dengan OpenTelemetry API

Kode berikut mengonfigurasi library klien Java Datastore untuk mengekspor rentang dengan rasio pengambilan sampel 10% ke OpenTelemetry Collector.

Java

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

OtlpGrpcSpanExporter otlpGrpcSpanExporter =
  OtlpGrpcSpanExporter
  .builder()
  .setEndpoint("http://localhost:4317") // 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();

// Export to a collector that is expecting OTLP using gRPC.
OpenTelemetrySdk otel = OpenTelemetrySdk.builder()
        .setTracerProvider(SdkTracerProvider.builder()
            .setResource(resource)
            .addSpanProcessor(otlpGrpcSpanProcessor)
            .setSampler(Sampler.traceIdRatioBased(0.1))
            .build())
        .build();


DatastoreOptions datastoreOptions = DatastoreOptions
  .newBuilder()
  .setOpenTelemetryOptions(
    DatastoreOpenTelemetryOptions.newBuilder()
      .setTracingEnabled(true)
      .setOpenTelemetry(otel)
      .build())
  .build();

Datastore datastore = datastoreOptions.getService();

Mengekspor langsung ke backend kemampuan pengamatan dengan OpenTelemetry API

Kode berikut mengonfigurasi library klien Java untuk mengekspor rentang aktivitas secara langsung ke Cloud Trace dengan rasio pengambilan sampel aktivitas 10%. Anda dapat menggunakan eksportir penyedia layanan observabilitas lain untuk mengekspor langsung ke backend mereka. Jika backend pengamatan Anda mendukung penyerapan OTLP, Anda dapat menggunakan OpenTelemetry OtlpGrpcSpanExporter untuk mengekspor ke backend daripada menggunakan pengekspor kustom.

Java

// TraceExporter needed for this use case
import com.google.cloud.opentelemetry.trace.TraceExporter;

Resource resource = Resource
  .getDefault().merge(Resource.builder().put(SERVICE_NAME, "My App").build());
SpanExporter gcpTraceExporter = TraceExporter.createWithDefaultConfiguration();

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

// Export directly to Cloud Trace with 10% trace sampling ratio
OpenTelemetrySdk otel = OpenTelemetrySdk.builder()
        .setTracerProvider(SdkTracerProvider.builder()
            .setResource(resource)
            .addSpanProcessor(gcpBatchSpanProcessor)
            .setSampler(Sampler.traceIdRatioBased(0.1))
            .build())
        .build();


DatastoreOptions datastoreOptions = DatastoreOptions
  .newBuilder()
  .setOpenTelemetryOptions(
    DatastoreOpenTelemetryOptions.newBuilder()
      .setTracingEnabled(true)
      .setOpenTelemetry(otel)
      .build())
  .build();

Datastore datastore = datastoreOptions.getService();

Mengekspor ke Collector dengan Agen Otomatis

Jalankan OpenTelemetry Collector dengan mengaktifkan penerima gRPC OTLP. Tetapkan pengekspor agen ke otlp dan tentukan endpoint tempat agen harus mengekspor data. Contoh berikut menggunakan rasio pengambilan sampel 10% dan mengirimkan rekaman aktivitas ke Pengumpul yang memproses port localhost 4317.

Terminal

DATASTORE_ENABLE_TRACING=ON                            \
java                                                   \
-javaagent:path/to/opentelemetry-javaagent.jar         \
-Dotel.traces.exporter=otlp                            \
-Dotel.exporter.otlp.endpoint="http://localhost:4317"  \
-Dotel.traces.sampler=traceidratio                     \
-Dotel.traces.sampler.arg=0.1                          \
-Dotel.service.name="My App"                           \
-jar myapp.jar

Mengekspor langsung ke backend kemampuan observasi dengan Agen Otomatis

Selain menetapkan variabel lingkungan DATASTORE_ENABLE_TRACING=ON, Anda perlu menambahkan ekstensi agen Java OpenTelemetry untuk backend tertentu. Contoh berikut menggunakan Ekstensi eksportir trace dan rasio pengambilan sampel trace 10%.

Terminal

DATASTORE_ENABLE_TRACING=ON                                                \
java                                                                       \
-javaagent:path/to/opentelemetry-javaagent.jar                             \
-Dotel.javaagent.extensions=/path/to/exporter-auto-0.26.0-alpha-shaded.jar \
-Dotel.traces.exporter=google_cloud_trace                                  \
-Dotel.traces.sampler=traceidratio                                         \
-Dotel.traces.sampler.arg=0.1                                              \
-Dotel.service.name="My Application"                                       \
-jar myapp.jar

Contoh rekaman aktivitas

Contoh berikut menunjukkan cara informasi trace ditampilkan di Cloud Trace. Untuk mengetahui informasi selengkapnya tentang kemungkinan atribut dan nilai, lihat Atribut dan peristiwa rentang rekaman aktivitas.

Contoh rentang rekaman aktivitas

Rentang aktivitas yang dilihat dari Cloud Trace.

Contoh log peristiwa

Log peristiwa rentang rekaman aktivitas yang dilihat dari Cloud Trace.

Contoh nilai atribut

Nilai atribut rentang rekaman aktivitas yang dilihat dari Cloud Trace.

Langkah berikutnya