Leistung mit clientseitigen Traces beobachten

Leistung mit clientseitigen Traces beobachten

Vorschau

Diese Funktion unterliegt den „Bedingungen für Pre-GA-Angebote“ im Abschnitt „Allgemeine Dienstbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA‑Funktionen stehen in der vorliegenden Form zur Verfügung und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie unter den Beschreibungen der Startphase.

Wenn Sie Firestore-Anfragen von Anfang bis Ende beobachten und Fehler beheben möchten, können Sie Traces in den Clientbibliotheken aktivieren. Clientseitiges Tracing kann ein Signal für die Leistung liefern, die Ihre Anwendung bietet, sowie Einblicke, die bei der Fehlerbehebung helfen 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 er die RPC-Antwort erhalten hat, einschließlich der durch das Netzwerk und das Clientsystem verursachten Latenz
• Attribute (Schlüssel/Wert-Paare) mit Informationen zum Client und seiner Konfiguration
• Logs, die mit wichtigen Ereignissen in den Spans verknüpft sind
• Stacktraces, wenn ein Absturz im Client auftritt

OpenTelemetry

Traces für die Clientbibliotheken werden mit OpenTelemetry APIs instrumentiert. OpenTelemetry ist ein Open-Source-Framework für die Beobachtbarkeit, das dem Industriestandard entspricht. OpenTelemetry bietet eine breite Palette von Tools wie Instrumentierungs-APIs und SDKs, Collector, backend-spezifische Exporter und flexible Konfigurationsoptionen wie Stichprobensteuerungen und Span-Limits.

Traces mit Exportern und Collector exportieren

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

Neben einem Exporter empfiehlt OpenTelemetry, einen Collector einzurichten. Mit einem Collector kann Ihr Dienst Daten schnell auslagern und der Collector kann sich um zusätzliche Vorgänge wie Wiederholungen, Batching und Verschlüsselung kümmern. Ein Collector wird neben 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 erstellt keine Trace-Spans für Echtzeit-Listener.

Abrechnung

Neben der 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 Gebühren an.

Die Aufnahme von Trace-Spans in Ihr Observability-Backend kann kostenpflichtig sein. Wenn Sie beispielsweise Cloud Trace als Backend verwenden, wird Ihnen gemäß den Cloud Trace-Preisenin Rechnung gestellt. Wenn Sie einen anderen Anbieter von Observability-Diensten verwenden, informieren Sie sich über das Abrechnungsmodell und die damit verbundenen Kosten.

Um die Abrechnung besser zu verstehen, beginnen Sie mit einer kleinen Stichprobenrate für Traces (Trace eines kleinen Prozentsatzes Ihrer RPCs) basierend auf Ihrem Traffic.

Hinweis

Hinweise:

• Richten Sie das Dienstkonto ein, unter dem Ihre App Traces in Ihr Observability-Backend schreibt, und weisen Sie ihm die erforderlichen Rollen für die Identitäts- und Zugriffsverwaltung zu:

  Trace-Vorgang	IAM-Rolle
  Traces lesen	roles/cloudtrace.user
  Traces schreiben	roles/cloudtrace.agent
  Traces lesen/schreiben	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 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. Sehen Sie sich die folgenden Beispiele an:
  • Mit OpenTelemetry-APIs in einen Collector exportieren
  • Mit OpenTelemetry-APIs direkt in ein Observability-Backend exportieren
• Sie können Traces ohne Codeänderungen konfigurieren. Folgen Sie dazu den Beispielen unter Instrumentierung ohne Code.

Traces mit OpenTelemetry-APIs in einen Collector exportieren

Der folgende Code konfiguriert die Clientbibliothek so, dass Spans mit einer Stichprobenrate 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));
});
    

Mit OpenTelemetry-APIs direkt in ein Observability-Backend exportieren

Wenn Ihr Anbieter von Observability-Diensten die OTLP-Aufnahme unterstützt, können Sie den OpenTelemetry-Exporter verwenden, um Traces direkt in das Backend zu exportieren. Der folgende Code konfiguriert die Clientbibliothek so, dass Trace-Spans mit einer Stichprobenrate 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)

Sie können Traces ohne Codeänderungen mit Auto-Agents konfigurieren. Sie müssen die Umgebungsvariable FIRESTORE_ENABLE_TRACING=ON festlegen. Außerdem müssen Sie weitere Konfigurationseinstellungen vornehmen , wie unter Agent konfigurieren beschrieben. Sehen Sie sich die folgenden Beispiele an.

Mit Auto-Agents in einen Collector exportieren

Führen Sie Ihren 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 eine Stichprobenrate von 10% verwendet und Traces werden an den Collector gesendet, der auf dem Localhost-Port 4317 wartet.

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

Neben dem 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 und eine 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 zur JavaScript-Instrumentierung, um die Instrumentierung ohne Code einzurichten. Der folgende 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

Die folgenden Beispiele zeigen, wie Trace-Informationen in Cloud Trace angezeigt werden. Weitere Informationen zu möglichen Attributen und Werten finden Sie unter Attribute und Ereignisse von Trace-Spans.

Beispiel für einen Trace-Span

Beispiel für ein Ereignislog

Beispiel für Attributwerte

Beispiel für einen Stacktrace und ein Ausnahmeereignis

Nächste Schritte

• Referenz für Attribute und Ereignisse von Trace-Spans ansehen
• Informationen zur serverseitigen Überwachung