Memantau performa dengan rekaman aktivitas sisi klien

Untuk memantau dan men-debug permintaan Firestore secara menyeluruh, Anda dapat mengaktifkan rekaman aktivitas di library klien. 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 di klien

OpenTelemetry

Trace untuk library klien 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 dan batas rentang.

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

Batasan

Tracing sisi klien memiliki batasan berikut:

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

Penagihan

Selain penggunaan Firestore, 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 untuk mengekspor rentang dengan rasio pengambilan sampel 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 kemampuan pengamatan dengan OpenTelemetry API

Jika penyedia layanan observabilitas Anda mendukung penyerapan OTLP, Anda dapat menggunakan pengekspor OpenTelemetry mereka untuk mengekspor rekaman aktivitas langsung ke backend mereka. Kode berikut mengonfigurasi library klien untuk mengekspor rentang 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 perubahan kode menggunakan agen otomatis. Anda perlu menetapkan variabel lingkungan FIRESTORE_ENABLE_TRACING=ON. Anda juga perlu menyetel setelan konfigurasi lainnya seperti yang dijelaskan dalam Konfigurasi Agen. Lihat contoh berikut.

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. 


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 Java OpenTelemetry untuk backend tertentu. Contoh berikut menggunakan ekstensi Trace exporter dan rasio pengambilan sampel 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. Cuplikan kode contoh berikut mengaktifkan instrumentasi dan mengirimkan rekaman aktivitas ke pengumpul OpenTelemetry:


npm install @opentelemetry/api
npm install @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 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 rekaman 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

Contoh Pelacakan Tumpukan dan Peristiwa Pengecualian

Stack trace yang dilihat dari Cloud Trace

Peristiwa pengecualian yang dilihat dari Cloud Trace

Langkah berikutnya