Halaman ini diterjemahkan oleh Cloud Translation API.

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 seperti yang dialami oleh aplikasi Anda, serta insight yang dapat membantu memecahkan masalah proses debug.

Rekaman aktivitas 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 diperkenalkan oleh jaringan dan sistem klien
Atribut (key-value pair) yang menampilkan informasi tentang klien dan konfigurasinya.
Log yang terkait dengan peristiwa utama dalam span.
Pelacakan tumpukan jika terjadi error pada klien.

OpenTelemetry

Rekaman aktivitas untuk library klien Java diinstrumentasikan menggunakan OpenTelemetry API. OpenTelemetry adalah framework visibilitas open source standar industri. OpenTelemetry menawarkan berbagai alat seperti API dan SDK instrumentasi, kolektor, eksportir khusus backend, serta opsi konfigurasi yang fleksibel seperti kontrol sampling, batas span, dan lainnya.

Mengekspor rekaman aktivitas dengan pengekspor dan kolektor

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

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

Batasan

Rentang rekaman aktivitas hanya tersedia untuk library klien Java.

Penagihan

Selain penggunaan Datastore, pelacakan sisi klien dapat dikenai biaya.

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

Proses transfer span rekaman aktivitas ke backend observabilitas Anda mungkin ditagih. Misalnya, jika menggunakan Cloud Trace sebagai backend, Anda akan dikenai biaya sesuai dengan harga Cloud Trace. Jika Anda menggunakan penyedia layanan visibilitas lain, cari tahu model penagihan dan biaya terkaitnya.

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

Sebelum memulai

Sebelum memulai:

Pastikan Anda menyiapkan akun layanan tempat aplikasi Anda menulis rekaman aktivitas ke backend visibilitas 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

Aktivitas baca/tulis roles/cloudtrace.admin
Pastikan Trace API diaktifkan di project ini.

Operasi rekaman aktivitas	Peran IAM
Membaca rekaman aktivitas	`roles/cloudtrace.user`
Menulis rekaman aktivitas	`roles/cloudtrace.agent`
Aktivitas baca/tulis	`roles/cloudtrace.admin`

Mengonfigurasi rekaman aktivitas sisi klien

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

Anda dapat mengonfigurasi rekaman aktivitas dengan OpenTelemetry API. Hal ini memerlukan perubahan kode pada aplikasi Anda. Lihat contoh berikut:
- Mengekspor ke Collector dengan OpenTelemetry API
- Mengekspor langsung ke backend observabilitas dengan OpenTelemetry API
Anda dapat mengonfigurasi rekaman aktivitas tanpa mengubah kode menggunakan agen otomatis. Anda perlu menetapkan variabel lingkungan DATASTORE_ENABLE_TRACING=ON. Anda juga perlu menetapkan setelan konfigurasi lainnya seperti yang dijelaskan dalam Konfigurasi Agen. Lihat contoh berikut:
- Mengekspor ke Pengumpul dengan Agen Otomatis
- Mengekspor langsung ke backend observabilitas dengan Agen Otomatis

Mengekspor trace ke Collector dengan OpenTelemetry API

Kode berikut mengonfigurasi library klien Java Datastore untuk mengekspor span dengan rasio sampling 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 observabilitas dengan OpenTelemetry API

Kode berikut mengonfigurasi library klien Java untuk mengekspor span trace secara langsung ke Cloud Trace dengan rasio sampling trace 10%. Anda dapat menggunakan eksportir penyedia layanan observabilitas lainnya untuk mengekspor langsung ke backend mereka. Jika backend visibilitas Anda mendukung penyerapan OTLP, Anda dapat menggunakan OtlpGrpcSpanExporter OpenTelemetry untuk mengekspor ke backend, bukan 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 Pengumpul dengan Agen Otomatis

Jalankan OpenTelemetry Collector dengan penerima gRPC OTLP yang diaktifkan. Tetapkan eksportir agen ke otlp dan tentukan endpoint tempat agen harus mengekspor data. Contoh berikut menggunakan rasio sampling 10% dan mengirim trace 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 observabilitas 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 Trace exporter dan rasio sampling rekaman aktivitas 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 rekaman aktivitas ditampilkan di Cloud Trace. Untuk mengetahui informasi selengkapnya tentang kemungkinan atribut dan nilai, lihat Atribut dan peristiwa span rekaman aktivitas.

Contoh span rekaman aktivitas

Span trace yang dilihat dari Cloud Trace.

Contoh log aktivitas

Log peristiwa span rekaman aktivitas yang dilihat dari Cloud Trace.

Contoh nilai atribut

Nilai atribut span trace yang dilihat dari Cloud Trace.

Langkah selanjutnya

Lihat referensi untuk Atribut dan peristiwa span rekaman aktivitas.
Pelajari pemantauan sisi server.