Leistung mit clientseitigen Tracing-Daten überwachen

Wenn Sie Firestore-Anfragen im Datastore-Modus (Datastore) von Anfang bis Ende überwachen und debuggen möchten, können Sie Traces in der Java-Clientbibliothek 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.
  • Stapelüberprüfungen, wenn auf dem Client ein Absturz auftritt.

OpenTelemetry

Traces für die Java-Clientbibliothek 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, Span-Limits und mehr.

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 (OpenTelemetry Protocol), verarbeitet sie und exportiert sie in Ihr Observability-Backend.

Beschränkungen

Trace-Spans sind nur für die Java-Clientbibliothek verfügbar.

Abrechnung

Neben der Datastore-Nutzung können auch 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:

Traces mit OpenTelemetry-APIs in einen Collector exportieren

Mit dem folgenden Code wird die Datastore-Java-Clientbibliothek so konfiguriert, dass Spans mit einer Abtastrate von 10% in einen OpenTelemetry Collector exportiert werden.

Java

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 use `.setScheduleDelay()`, `.setExporterTimeout()`,
// `.setMaxQueueSize`(), and `.setMaxExportBatchSize()` 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();


DatastoreOptions datastoreOptions = DatastoreOptions
  .newBuilder()
  .setOpenTelemetryOptions(
    DatastoreOpenTelemetryOptions.newBuilder()
      .setTracingEnabled(true)
      .setOpenTelemetry(otel)
      .build())
  .build();

Datastore datastore = datastoreOptions.getService();

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

Mit dem folgenden Code wird die Java-Clientbibliothek so konfiguriert, dass Trace-Spans mit einem Trace-Abtastverhältnis von 10% direkt nach Cloud Trace exportiert werden. Sie können die Exporter anderer Anbieter von Observability-Diensten verwenden, um Daten direkt in ihr Backend zu exportieren. Wenn Ihr Observability-Backend die OTLP-Erfassung unterstützt, können Sie OpenTelemetry OtlpGrpcSpanExporter verwenden, um Daten in Ihr Backend zu exportieren, anstatt einen benutzerdefinierten Exporter zu verwenden.

Java

// 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 use `.setScheduleDelay()`, `.setExporterTimeout()`,
// `.setMaxQueueSize`(), and `.setMaxExportBatchSize()` 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();


DatastoreOptions datastoreOptions = DatastoreOptions
  .newBuilder()
  .setOpenTelemetryOptions(
    DatastoreOpenTelemetryOptions.newBuilder()
      .setTracingEnabled(true)
      .setOpenTelemetry(otel)
      .build())
  .build();

Datastore datastore = datastoreOptions.getService();

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.

Terminal

DATASTORE_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 DATASTORE_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.

Terminal

DATASTORE_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                                              \
-Dotel.service.name="My Application"                                       \
-jar myapp.jar

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

Ein Trace-Span, der in Cloud Trace angezeigt wird.

Beispiel für ein Ereignisprotokoll

Ein Trace-Span-Ereignislog, das in Cloud Trace aufgerufen wird.

Beispielwerte für Attribute

Attributwerte eines Trace-Spans, der in Cloud Trace angezeigt wird.

Nächste Schritte