Memantau performa dengan trace sisi klien

Untuk memantau dan men-debug permintaan Firestore secara menyeluruh, Anda dapat dan mengaktifkan trace di library klien Java. Pelacakan sisi klien dapat memberikan mendapatkan sinyal tentang performa yang dialami aplikasi, serta yang dapat membantu mengatasi masalah proses debug.

Rekaman aktivitas sisi klien, yang dikumpulkan dengan menjalankan RPC dari klien, berikan informasi berikut:

  • Span dengan stempel waktu saat klien mengirim permintaan RPC dan saat klien menerima respons RPC, termasuk latensi yang jaringan dan sistem klien
  • Atribut (pasangan nilai kunci) yang menampilkan informasi tentang klien dan konfigurasinya
  • Log yang terkait dengan peristiwa utama dalam span
  • Stack trace jika terjadi error di klien

OpenTelemetry

Rekaman aktivitas untuk library klien Java diinstrumentasikan menggunakan OpenTelemetry API. OpenTelemetry adalah framework kemampuan observasi open source berstandar industri. OpenTelemetry menawarkan berbagai alat seperti API instrumentasi dan SDK, kolektor, pengekspor khusus backend, dan opsi konfigurasi fleksibel seperti kontrol pengambilan sampel, batas rentang, dan banyak lagi.

Mengekspor rekaman aktivitas dengan pengekspor dan kolektor

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

Selain pengekspor, OpenTelemetry merekomendasikan untuk menyiapkan Kolektor. Kolektor memungkinkan layanan memindahkan data dengan cepat dan memungkinkan kolektor menangani seperti percobaan ulang, pengelompokan, dan enkripsi. Kolektor berlari bersama aplikasi Anda. Kolektor menerima pesan OTLP, memproses pesan tersebut, dan mengekspornya ke backend kemampuan observasi.

Batasan

Rekaman aktivitas sisi klien memiliki batasan berikut:

  • Span trace tersedia untuk library klien Java.
  • Library klien tidak menghasilkan span rekaman aktivitas untuk pemroses real-time.

Penagihan

Selain penggunaan Firestore, pelacakan sisi klien dapat menimbulkan tambahan.

Tidak ada biaya untuk mengumpulkan trace atau penggunaan OpenTelemetry Google Workspace for Education.

Penyerapan span trace ke backend kemampuan observasi Anda dapat dikenai biaya. Misalnya, jika menggunakan Cloud Trace sebagai backend, Anda ditagih sesuai dengan harga Cloud Trace. Jika Anda menggunakan penyedia layanan kemampuan observasi lain, cari tahu model penagihannya dan biaya terkait.

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

Sebelum memulai

Sebelum memulai:

  • Pastikan Anda menyiapkan akun layanan tempat aplikasi menulis rekaman aktivitas ke backend kemampuan observasi yang memiliki Peran Identity and Access Management:

    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 trace sisi klien. Anda dapat mengekspor ke Kolektor atau langsung ke backend kemampuan observasi. Anda juga memiliki opsi berikut untuk mengonfigurasi trace sisi klien:

Mengekspor rekaman aktivitas ke Collector dengan API OpenTelemetry

Kode berikut mengonfigurasi library klien Java Firestore untuk mengekspor span dengan rasio sampling 10% ke OpenTelemetry Collector.

Java (Admin)

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 also use other `BatchSpanProcessorBuilder` methods
// to further customize.
BatchSpanProcessor otlpGrpcSpanProcessor =
  BatchSpanProcessor.builder(otlpGrpcSpanExporter).build();

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

Firestore firestore = FirestoreOptions
  .newBuilder()
  .setOpenTelemetryOptions(
    FirestoreOpenTelemetryOptions.newBuilder()
      .setTracingEnabled(true)
      .setOpenTelemetry(otel)
      .build())
  .build().getService();

Mengekspor langsung ke backend kemampuan observasi dengan OpenTelemetry API

Kode berikut mengonfigurasi library klien Java untuk langsung mengekspor rekaman aktivitas akan diperluas ke Cloud Trace dengan rasio pengambilan sampel trace sebesar 10%. Anda dapat menggunakan penyedia layanan kemampuan observasi lainnya, pengekspor untuk langsung diekspor ke backend. Jika backend kemampuan observasi Anda mendukung penyerapan OTLP, Anda dapat menggunakan OpenTelemetry OtlpGrpcSpanExporter untuk mengekspor ke backend Anda daripada menggunakan pengekspor khusus.

Java (Admin)

// 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 also use other `BatchSpanProcessorBuilder` methods
// to further customize.
SpanProcessor gcpBatchSpanProcessor =
  BatchSpanProcessor.builder(gcpTraceExporter).build();

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

Firestore firestore = FirestoreOptions
  .newBuilder()
  .setOpenTelemetryOptions(
    FirestoreOpenTelemetryOptions.newBuilder()
      .setTracingEnabled(true)
      .setOpenTelemetry(otel)
      .build())
  .build().getService();

Mengekspor ke Kolektor dengan Agen Otomatis

Jalankan OpenTelemetry Collector Anda dengan penerima gRPC OTLP diaktifkan. Setel pengekspor agen ke otlp dan menentukan endpoint tempat agen seharusnya mengekspor data. Contoh berikut menggunakan rasio sampling 10% dan mengirimkan rekaman aktivitas ke Kolektor yang memproses port localhost 4317.

Terminal

FIRESTORE_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 FIRESTORE_ENABLE_TRACING=ON, Anda perlu menambahkan ekstensi agen OpenTelemetry Java ke backend. Contoh berikut menggunakan ekstensi pengekspor Trace dan rasio sampling trace 10%.

Terminal

FIRESTORE_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                                              \

Contoh rekaman aktivitas

Contoh berikut menunjukkan cara informasi rekaman aktivitas ditampilkan di Cloud Trace. Untuk informasi selengkapnya tentang kemungkinan atribut dan nilai, lihat Melacak atribut dan peristiwa span.

Contoh span trace

Rentang trace yang dilihat dari Cloud Trace

Contoh log peristiwa

Log peristiwa rentang trace yang dilihat dari Cloud Trace

Contoh nilai atribut

Nilai atribut span trace yang dilihat dari Cloud Trace

Contoh Stack Trace dan Peristiwa Pengecualian

Pelacakan tumpukan dilihat dari Cloud Trace

Peristiwa pengecualian yang dilihat dari Cloud Trace

Langkah selanjutnya