Leistung mit clientseitigen Tracing-Daten überwachen

Wenn Sie Firestore-Anfragen end-to-end überwachen und beheben möchten, können Sie in den Clientbibliotheken Protokolle aktivieren. Clientseitiges Tracing kann Aufschluss über die Leistung Ihrer Anwendung geben und Ihnen helfen, Probleme beim Debuggen zu beheben.

Clientseitige Traces, die durch Ausführen von RPCs vom Client erfasst werden, enthalten die folgenden Informationen:

  • Zeiträume mit Zeitstempeln für den Zeitpunkt, zu dem der Client die RPC-Anfrage gesendet und die RPC-Antwort empfangen hat, einschließlich der Latenz, die durch das Netzwerk und das Clientsystem verursacht wird
  • Attribute (Schlüssel/Wert-Paare), die Informationen zum Client und seiner Konfiguration enthalten
  • Protokolle, die mit wichtigen Ereignissen in den Spannen verknüpft sind
  • Stack-Traces, wenn ein Absturz im Client auftritt

OpenTelemetry

Traces für die Clientbibliotheken werden mit OpenTelemetry APIs instrumentiert. OpenTelemetry ist ein branchenübliches Open-Source-Observability-Framework. OpenTelemetry bietet eine breite Palette von Tools wie Instrumentierungs-APIs und SDKs, Collector, backendspezifische Exporteure und flexible Konfigurationsoptionen wie Stichprobensteuerungen und Grenzwerte für Zeiträume.

Traces mit Exportern und Collectorn exportieren

Im Rahmen Ihrer Konfigurationen können Sie Ihre Traces in ein Observability-Backend exportieren. Die meisten Anbieter von Observability-Diensten bieten Exportfunktionen an, z. B. Cloud Trace.

Zusätzlich zu einem Exporter empfiehlt OpenTelemetry, einen Collector einzurichten. Mit einem Collector können Sie Daten schnell aus Ihrem Dienst auslagern und zusätzliche Vorgänge wie Wiederholungen, Batchverarbeitung und Verschlüsselung übernehmen lassen. Ein Collector wird parallel zu Ihrer Anwendung ausgeführt. Der Collector empfängt OTLP-Nachrichten, verarbeitet sie und exportiert sie in Ihr Observability-Backend.

Beschränkungen

Für clientseitige Traces gelten die folgenden Einschränkungen:

  • Trace-Bereiche sind für die Java- und Node.js-Clientbibliotheken verfügbar.
  • Die Clientbibliothek generiert keine Trace-Bereiche für Echtzeit-Listener.

Abrechnung

Zusätzlich zur Firestore-Nutzung können für das clientseitige Tracing Gebühren anfallen.

Für das Erfassen von Traces oder die Nutzung des OpenTelemetry-Frameworks fallen keine Kosten an.

Die Aufnahme von Trace-Spans in Ihr Observability-Backend kann in Rechnung gestellt werden. Wenn Sie beispielsweise Cloud Trace als Backend verwenden, werden Ihnen die Kosten gemäß den Cloud Trace-Preisen in Rechnung gestellt. Wenn Sie einen anderen Anbieter von Observability-Diensten nutzen, erkundigen Sie sich nach seinem Abrechnungsmodell und den zugehörigen Kosten.

Um die Abrechnung besser nachvollziehen zu können, beginnen Sie mit einem kleinen Stichprobenverhältnis (ein kleiner Prozentsatz Ihrer RPCs wird erfasst) basierend auf Ihrem Traffic.

Hinweis

Hinweise:

  • Achten Sie darauf, dass Sie das Dienstkonto, unter dem Ihre App Traces in Ihr Observability-Backend schreibt, mit den erforderlichen Identity and Access Management-Rollen einrichten:

    Trace-Vorgang IAM-Rolle
    Traces lesen roles/cloudtrace.user
    Traces schreiben roles/cloudtrace.agent
    Lese-/Schreibspuren roles/cloudtrace.admin

  • Prüfen Sie, ob die Trace API für dieses Projekt aktiviert ist.

Clientseitige Traces konfigurieren

Dieser Abschnitt enthält Beispielkonfigurationen für clientseitige Traces. Sie können die Daten in einen Collector oder direkt in ein Observability-Backend exportieren. Außerdem haben Sie folgende Möglichkeiten, clientseitige Traces zu konfigurieren:

Traces mit OpenTelemetry APIs in einen Collector exportieren

Im folgenden Code wird die Clientbibliothek so konfiguriert, dass Spans mit einer Abtastrate von 10% in einen OpenTelemetry Collector exportiert werden.

Java (Administrator)

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 (Administrator)

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));
});

Mit OpenTelemetry APIs direkt in ein Observability-Backend exportieren

Wenn Ihr Dienstanbieter für Observability die OTLP-Aufnahme unterstützt, können Sie mit seinem OpenTelemetry-Exporter Traces direkt in sein Backend exportieren. Im folgenden Code wird die Clientbibliothek so konfiguriert, dass Trace-Spans mit einer Abtastrate von 10% direkt in Cloud Trace exportiert werden.

Java (Administrator)

// 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 (Administrator)

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));
});

Instrumentierung ohne Code

Führen Sie die folgenden Schritte aus, um Traces ohne Codeänderungen zu konfigurieren:

Java (Administrator)
Mit Auto-Agents können Sie Traces ohne Codeänderungen konfigurieren. Sie müssen die Umgebungsvariable FIRESTORE_ENABLE_TRACING=ON festlegen. Außerdem müssen Sie andere Konfigurationseinstellungen festlegen, wie unter Agentkonfiguration beschrieben. Betrachten Sie die folgenden Beispiele.

Mit Auto-Agenten in einen Collector exportieren

Führen Sie den OpenTelemetry Collector mit aktivierten OTLP-gRPC-Empfängern aus. Legen Sie den Exporter des Kundenservicemitarbeiters auf otlp fest und geben Sie den Endpunkt an, an den der Kundenservicemitarbeiter die Daten exportieren soll. Im folgenden Beispiel wird eine Stichprobenerhebung mit 10% verwendet und es werden Protokolle an den Collector gesendet, der den localhost-Port 4317 überwacht. 


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

Mit Auto Agents direkt in ein Observability-Backend exportieren

Zusätzlich zur Umgebungsvariablen FIRESTORE_ENABLE_TRACING=ON müssen Sie die OpenTelemetry Java-Agenterweiterung für Ihr spezifisches Backend hinzufügen. Im folgenden Beispiel wird die Trace Exporter-Erweiterung und ein Stichprobenverhältnis von 10% verwendet. 


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 (Administrator)

Wenn Sie die Instrumentierung ohne Code einrichten möchten, folgen Sie der OpenTelemetry-Anleitung für die JavaScript-Instrumentierung. Im folgenden Code-Snippet wird die Instrumentierung aktiviert und es werden Traces an einen OpenTelemetry-Collector gesendet:


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

Beispiel-Trace

In den folgenden Beispielen wird gezeigt, wie Trace-Informationen in Cloud Trace angezeigt werden. Weitere Informationen zu möglichen Attributen und Werten finden Sie unter Attribute und Ereignisse für Trace-Bereiche.

Beispiel für eine Trace-Span

Eine Trace-Span, die in Cloud Trace angezeigt wird

Beispiel für ein Ereignisprotokoll

Ein Ereignisprotokoll für eine Trace-Spanne, das in Cloud Trace angezeigt wird

Beispielattributwerte

Attributwerte einer Trace-Span, die in Cloud Trace angezeigt werden

Beispiel für einen Stack-Trace und ein Ausnahmeereignis

Ein Stack-Trace, der in Cloud Trace angezeigt wird

Ein Ausnahmeereignis, das in Cloud Trace angezeigt wird

Nächste Schritte