Memantau performa dengan rekaman aktivitas sisi klien

Untuk memantau dan men-debug permintaan Firestore secara menyeluruh, Anda dapat mengaktifkan pelacakan di library klien. Pelacakan sisi klien dapat memberikan sinyal tentang performa 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 di klien

OpenTelemetry

Trace untuk library klien dilengkapi dengan instrumen 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 dan batas span.

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 OTLP, memproses pesan, dan mengekspornya ke backend observabilitas Anda.

Batasan

Pelacakan sisi klien memiliki batasan berikut:

  • Rentang rekaman aktivitas tersedia untuk library klien Java dan Node.js.
  • Library klien tidak menghasilkan span rekaman aktivitas untuk pemroses real-time.

Penagihan

Selain penggunaan Firestore, 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.

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:

Mengekspor trace ke Collector dengan OpenTelemetry API

Kode berikut mengonfigurasi library klien 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.
OpenTelemetrySdk otel = OpenTelemetrySdk.builder()
        .setTracerProvider(
          SdkTracerProvider.builder()
            .setResource(resource)
            .addSpanProcessor(otlpGrpcSpanProcessor)
            .setSampler(Sampler.traceIdRatioBased(0.1))
            .build())
          .build();

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

import { trace } from "@opentelemetry/api";
import {GrpcInstrumentation} from '@opentelemetry/instrumentation-grpc';

import pkg1 from "@opentelemetry/sdk-trace-node";
import pkg2 from "@opentelemetry/instrumentation";
import pkg3 from "@opentelemetry/exporter-trace-otlp-grpc";

const { NodeTracerProvider, BatchSpanProcessor, TraceIdRatioBasedSampler } = pkg1;
const { registerInstrumentations } = pkg2;
const { OTLPTraceExporter } =  pkg3;

const provider = new NodeTracerProvider(
  // Provide your chosen NodeTracerConfig such as sampler and span limit
  {
    sampler: new TraceIdRatioBasedSampler(0.1),
  }
);
provider.addSpanProcessor(new BatchSpanProcessor(new OTLPTraceExporter()));
provider.register();

// If you'd like to see gRPC spans (recommended), enable GrpcInstrumentation
registerInstrumentations({
  instrumentations: [
    new GrpcInstrumentation(
      // (optional): you can add GrpcInstrumentationConfig here
    ),
  ],
});


const settings: Settings = {
  projectId: 'my-project-id',
  preferRest: false,
  openTelemetry: {
    tracerProvider: trace.getTracerProvider()
  }
};

// Initialize Firestore
const firestore = new Firestore(settings);
// Add app code here

// Make sure to shut down your TracerProvider to flush any traces left in memory.
process.on('SIGINT', async () => {
  await provider
        .shutdown()
        .catch(error => console.error('Error terminating NodeTracerProvider:', error));
});

Mengekspor langsung ke backend observabilitas dengan OpenTelemetry API

Jika penyedia layanan visibilitas Anda mendukung penyerapan OTLP, Anda dapat menggunakan eksportir OpenTelemetry mereka untuk mengekspor rekaman aktivitas langsung ke backend mereka. Kode berikut mengonfigurasi library klien untuk mengekspor span rekaman aktivitas secara langsung ke Cloud Trace dengan rasio pengambilan sampel rekaman aktivitas 10%.

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
OpenTelemetrySdk otel = OpenTelemetrySdk.builder()
        .setTracerProvider(SdkTracerProvider.builder()
            .setResource(resource)
            .addSpanProcessor(gcpBatchSpanProcessor)
            .setSampler(Sampler.traceIdRatioBased(0.1))
            .build())
        .build();

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

import { trace } from "@opentelemetry/api";
import {GrpcInstrumentation} from '@opentelemetry/instrumentation-grpc';
import { TraceExporter } from "@google-cloud/opentelemetry-cloud-trace-exporter";

import pkg1 from "@opentelemetry/sdk-trace-node";
import pkg2 from "@opentelemetry/instrumentation";

const { NodeTracerProvider, BatchSpanProcessor, TraceIdRatioBasedSampler } = pkg1;
const { registerInstrumentations } = pkg2;

const provider = new NodeTracerProvider(
  // Provide your chosen NodeTracerConfig such as sampler and span limits
  {
    sampler: new TraceIdRatioBasedSampler(0.1),
  }
);
provider.addSpanProcessor(new BatchSpanProcessor(new TraceExporter()));
provider.register();

// If you'd like to see gRPC spans (recommended), enable GrpcInstrumentation
registerInstrumentations({
  instrumentations: [
    new GrpcInstrumentation(
      // (optional): you can add GrpcInstrumentationConfig here
    ),
  ],
});


const settings: Settings = {
  projectId: 'my-project-id',
  preferRest: false,
  openTelemetry: {
    tracerProvider: trace.getTracerProvider()
  }
};

// Initialize Firestore
const firestore = new Firestore(settings);
// ...

// Make sure to shut down your TracerProvider to flush any traces left in memory.
process.on('SIGINT', async () => {
  await provider
        .shutdown()
        .catch(error => console.error('Error terminating NodeTracerProvider:', error));
});

Instrumentasi tanpa kode

Selesaikan petunjuk berikut untuk mengonfigurasi rekaman aktivitas tanpa mengubah kode:

Java (Admin)
Anda dapat mengonfigurasi rekaman aktivitas tanpa mengubah kode menggunakan agen otomatis. Anda perlu menetapkan variabel lingkungan FIRESTORE_ENABLE_TRACING=ON. Anda juga harus menetapkan setelan konfigurasi lainnya seperti yang dijelaskan dalam Konfigurasi Agen. Lihat contoh berikut.

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. 


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 observabilitas dengan Agen Otomatis

Selain menetapkan variabel lingkungan FIRESTORE_ENABLE_TRACING=ON, Anda perlu menambahkan ekstensi agen Java OpenTelemetry untuk backend tertentu. Contoh berikut menggunakan ekstensi Trace exporter dan rasio sampling trace 10%. 


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                                              \
Node.js (Admin)

Untuk menyiapkan instrumentasi tanpa kode, ikuti petunjuk OpenTelemetry untuk instrumentasi JavaScript. Contoh cuplikan kode berikut mengaktifkan instrumentasi dan mengirim rekaman aktivitas ke kolektor OpenTelemetry:


npm install --save @opentelemetry/api
npm install --save @opentelemetry/auto-instrumentations-node


env \
FIRESTORE_ENABLE_TRACING=ON \
OTEL_TRACES_EXPORTER=otlp \
OTEL_NODE_ENABLED_INSTRUMENTATIONS="http,grpc" \
OTEL_NODE_RESOURCE_DETECTORS="none" \
node --require @opentelemetry/auto-instrumentations-node/register my_app.js

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

Contoh Peristiwa Pelacakan Tumpukan dan Pengecualian

Stack trace yang dilihat dari Cloud Trace

Peristiwa pengecualian yang dilihat dari Cloud Trace

Langkah selanjutnya