Leistung mit clientseitigen Traces überwachen

Leistung mit clientseitigen Traces überwachen

Vorabversion

Diese Funktion ist den „Bedingungen für Pre-GA-Angebote“ im Abschnitt „Allgemeine Dienstbedingungen“ der dienstspezifischen Nutzungsbedingungen unterworfen. Pre-GA-Funktionen sind „wie gesehen“ verfügbar und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie in den Beschreibungen der Produkteinführungsphasen.

Wenn Sie Firestore-Anfragen von Anfang bis Ende überwachen und debuggen möchten, können Sie Traces in den Clientbibliotheken aktivieren. Clientseitiges Tracing kann ein Signal für die Leistung liefern, die von Ihrer Anwendung erreicht wird, sowie Informationen, die beim Debuggen von Problemen hilfreich sein können.

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

• Spans mit Zeitstempeln, wann der Client die RPC-Anfrage gesendet und wann der Client die RPC-Antwort empfangen hat, einschließlich der durch das Netzwerk und das Clientsystem verursachten Latenz
• Attribute (Schlüssel/Wert-Paare), die Informationen zum Client und seiner Konfiguration enthalten
• Logs, die mit Schlüsselereignissen in den Spannen verknüpft sind
• Stacktraces, wenn der Client abstürzt

OpenTelemetry

Traces für die Clientbibliotheken werden mit OpenTelemetry-APIs instrumentiert. OpenTelemetry ist ein Open-Source-Framework für die Observability, das einen Branchenstandard darstellt. OpenTelemetry bietet eine Vielzahl von Tools wie Instrumentierungs-APIs und SDKs, Collectors, backend-spezifische Exporter und flexible Konfigurationsoptionen wie Sampling-Steuerelemente und Spangrenzwerte.

Traces mit Exportern und Collectors exportieren

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

Zusätzlich zu einem Exporteur empfiehlt OpenTelemetry, einen Collector einzurichten. Mit einem Collector kann Ihr Dienst Daten schnell auslagern und der Collector kann sich um die zusätzliche Verarbeitung wie Wiederholungen, Batching und Verschlüsselung kümmern. 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-Spans sind für die Java- und Node.js-Clientbibliotheken verfügbar.
• Die Clientbibliothek generiert keine Trace-Spans 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 Verwendung des OpenTelemetry-Frameworks fallen keine Kosten an.

Die Aufnahme von Trace-Spans in Ihr Observability-Backend kann kostenpflichtig sein. Wenn Sie beispielsweise Cloud Trace als Backend verwenden, wird die Abrechnung gemäß den Cloud Trace-Preisen durchgeführt. Wenn Sie einen anderen Anbieter für Observability-Dienste verwenden, informieren Sie sich über dessen Abrechnungsmodell und die zugehörigen Kosten.

Um die Abrechnung besser zu verstehen, beginnen Sie mit einem kleinen Sampling-Verhältnis für Traces (zeichnen Sie einen kleinen Prozentsatz Ihrer RPCs auf), das auf Ihrem Traffic basiert.

Hinweise

Hinweise:

• Richten Sie das Dienstkonto, unter dem Ihre App Traces in Ihr Observability-Backend schreibt, mit den erforderlichen IAM-Rollen ein:

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

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

Clientseitige Traces konfigurieren

In diesem Abschnitt finden Sie Beispielkonfigurationen für clientseitige Traces. Sie können in einen Collector oder direkt in ein Observability-Backend exportieren. Außerdem haben Sie die folgenden Optionen zum Konfigurieren clientseitiger Traces:

• Sie können Traces mit den OpenTelemetry-APIs konfigurieren. Dazu sind Codeänderungen an Ihrer Anwendung erforderlich. Betrachten Sie die folgenden Beispiele:
  • Mit OpenTelemetry-APIs in einen Collector exportieren
  • Direkt in ein Observability-Backend mit OpenTelemetry-APIs exportieren
• Sie können Traces ohne Codeänderungen konfigurieren, indem Sie den Beispielen in Instrumentierung ohne Code folgen.

Traces mit OpenTelemetry-APIs in einen Collector exportieren

Mit dem folgenden Code wird die Clientbibliothek so konfiguriert, dass Spans mit einem Stichprobenverhältnis von 10% in einen OpenTelemetry Collector exportiert werden.

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

Direkt in ein Observability-Backend exportieren – mit OpenTelemetry-APIs

Wenn Ihr Observability-Dienstanbieter die OTLP-Erfassung unterstützt, können Sie den OpenTelemetry-Exporter des Anbieters verwenden, um Traces direkt in das Backend des Anbieters zu exportieren. Mit dem folgenden Code wird die Clientbibliothek so konfiguriert, dass Trace-Spans mit einem Trace-Abtastverhältnis von 10% direkt in Cloud Trace exportiert werden.

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

Instrumentierung ohne Code

Folgen Sie der Anleitung, um Traces ohne Codeänderungen zu konfigurieren:

Java (Admin)

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 Agent-Konfiguration beschrieben. Betrachten Sie die folgenden Beispiele.

In einen Collector mit Auto-Agents exportieren

Führen Sie den OpenTelemetry Collector mit aktivierten OTLP-gRPC-Empfängern aus. Legen Sie den Exporter des Agents auf otlp fest und geben Sie den Endpunkt an, an den der Agent die Daten exportieren soll. Im folgenden Beispiel wird ein Stichprobenverhältnis von 10% verwendet und Traces werden an den Collector gesendet, der auf dem Localhost-Port 4317 empfängt.

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

Direkt in ein Observability-Backend mit Auto Agents exportieren

Zusätzlich zum Festlegen der Umgebungsvariable FIRESTORE_ENABLE_TRACING=ON müssen Sie die OpenTelemetry Java-Agent-Erweiterung für Ihr spezifisches Backend hinzufügen. Im folgenden Beispiel wird die Trace-Exporter-Erweiterung mit einer Stichprobenrate 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 (Admin)

Folgen Sie der OpenTelemetry-Anleitung für die JavaScript-Instrumentierung, um die Instrumentierung ohne Code einzurichten. Das folgende Beispiel-Code-Snippet aktiviert die Instrumentierung und sendet Traces an einen OpenTelemetry-Collector:

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

    

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 Trace-Span-Attribute und -Ereignisse.

Beispiel für einen Trace-Span

Beispiel für ein Ereignisprotokoll

Beispielwerte für Attribute

Beispiel für Stacktrace und Ausnahmeereignis

Nächste Schritte

• Referenz zu Attributen und Ereignissen für Trace-Spans
• Weitere Informationen zum serverseitigen Monitoring