Leistung mit clientseitigen Traces überwachen

Um Firestore-Anfragen durchgängig zu überwachen und zu debuggen, können Sie Aktivieren Sie Traces in der Java-Clientbibliothek. Clientseitiges Tracing kann eine Signale zur Leistung Ihrer Anwendung sowie die bei der Fehlerbehebung helfen können.

Clientseitige Traces, die durch Ausführen von RPCs vom Client aus erfasst werden, stellen Sie folgende Informationen bereit:

  • Spans mit Zeitstempeln, die angeben, wann der Client die RPC-Anfrage gesendet hat, und wann der Client die RPC-Antwort erhalten hat, einschließlich der durch den Netzwerk- und Clientsystem
  • Attribute (Schlüssel/Wert-Paare), die Informationen über den Client und Konfiguration
  • Mit Schlüsselereignissen in den Spans verknüpfte Logs
  • Stacktraces bei einem Absturz auf dem Client

OpenTelemetry

Traces für die Java-Clientbibliothek werden mit OpenTelemetry-APIs OpenTelemetry ist ein branchenübliches Open-Source-Framework für die Beobachtbarkeit. OpenTelemetry bietet ein breites Spektrum an Tools wie Instrumentierungs-APIs und SDKs, Collectors, Backend-spezifische Exporteure und flexible Konfigurationsoptionen wie Steuerelementen für die Stichprobenerhebung, Span-Limits und mehr.

Traces mit Exportern und Collectors exportieren

Im Rahmen Ihrer Konfigurationen können Sie Traces ein Back-End für die Beobachtbarkeit. Die meisten Anbieter von Beobachtbarkeitsdiensten Exportprogramme, die Sie verwenden können, Cloud Trace

Neben einem Exporter empfiehlt OpenTelemetry, eine Collector. Ein Collector lässt dein Daten schnell verlagern, und der Collector kann sich um zusätzliche wie Wiederholungsversuche, Batchverarbeitung und Verschlüsselung. Ein Collector läuft parallel Ihre Anwendung. Der Collector empfängt OTLP-Nachrichten, verarbeitet die Nachrichten und exportiert sie in Ihr Beobachtbarkeits-Back-End.

Beschränkungen

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

  • Traces-Spans sind für die Java-Clientbibliothek verfügbar.
  • Die Clientbibliothek erstellt keine Trace-Spans für Echtzeit-Listener.

Abrechnung

Neben der Firestore-Nutzung können beim clientseitigen Tracing Gebühren.

Für das Erfassen von Traces oder die Nutzung von OpenTelemetry fallen keine Gebühren an. Framework.

Die Aufnahme von Trace-Spans in das Beobachtbarkeits-Back-End kann kostenpflichtig sein. Wenn Sie beispielsweise Cloud Trace als Back-End verwenden, werden gemäß den Cloud Trace-Preisen abgerechnet. Wenn Sie einen anderen Anbieter von Beobachtbarkeitsberichten nutzen, sollten Sie dessen Abrechnungsmodell ermitteln. und die damit verbundenen Kosten.

Um die Abrechnung besser zu verstehen, ein geringes Trace-Sampling-Verhältnis (einen kleinen Prozentsatz Ihrer RPCs verfolgen) auf Ihren Traffic.

Hinweise

Hinweis

  • Richten Sie das Dienstkonto ein, unter das Ihre App Traces schreibt. für das Beobachtbarkeits-Back-End mit den erforderlichen Identity and Access Management-Rollen:

    Trace-Vorgang IAM-Rolle
    Traces lesen roles/cloudtrace.user
    Traces schreiben roles/cloudtrace.agent
    Lese-/Schreib-Traces 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 Daten in einen Collector oder direkt in ein Beobachtbarkeits-Back-End exportieren. Sie haben außerdem die folgenden Möglichkeiten, clientseitige Traces zu konfigurieren:

Traces mit OpenTelemetry APIs in einen Collector exportieren

Mit dem folgenden Code wird die Firestore-Java-Clientbibliothek konfiguriert um Spans mit einer Stichprobenrate von 10% in einen OpenTelemetry Collector zu exportieren.

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.
OpenTelemetry otel = OpenTelemetrySdk.builder()
        .setTracerProvider(SdkTracerProvider.builder()
            .setResource(resource)
            .addSpanProcessor(otlpGrpcSpaaudit-loggingnProcessor)
            .setSampler(Sampler.traceIdRatioBased(0.1))
            .build());

Firestore firestore = FirestoreOptions
  .newBuilder()
  .setOpenTelemetryOptions(
    FirestoreOpenTelemetryOptions.newBuilder()
      .setTracingEnabled(true)
      .setOpenTelemetry(otel)
      .build())
  .build().getService();

Mit OpenTelemetry APIs direkt in ein Beobachtbarkeits-Back-End exportieren

Mit dem folgenden Code wird die Java-Clientbibliothek so konfiguriert, dass Trace direkt exportiert wird überspannt Cloud Trace mit einer Trace-Sampling-Quote von 10 %. Sie können andere Anbieter von Beobachtbarkeitsdiensten die Exporteure direkt in ihre Back-End. Wenn Ihr Beobachtbarkeits-Back-End die OTLP-Aufnahme unterstützt, können Sie mit OpenTelemetry OtlpGrpcSpanExporter in Ihr Backend exportieren. statt einen benutzerdefinierten Exporter zu verwenden.

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
OpenTelemetry otel = OpenTelemetrySdk.builder()
        .setTracerProvider(SdkTracerProvider.builder()
            .setResource(resource)
            .addSpanProcessor(gcpBatchSpanProcessor)
            .setSampler(Sampler.traceIdRatioBased(0.1))
            .build());

Firestore firestore = FirestoreOptions
  .newBuilder()
  .setOpenTelemetryOptions(
    FirestoreOpenTelemetryOptions.newBuilder()
      .setTracingEnabled(true)
      .setOpenTelemetry(otel)
      .build())
  .build().getService();

Mit automatischen Agenten in einen Collector exportieren

Führen Sie den OpenTelemetry Collector mit aktivierten OTLP-gRPC-Empfängern aus. Legen Sie die Exporteur des Agents auf otlp und geben Sie den Endpunkt an, an dem der Agent ausgeführt werden soll. um die Daten zu exportieren. Im folgenden Beispiel wird eine Stichprobenrate von 10% verwendet. dem Collector, der den Localhost-Port 4317 überwacht.

Terminal

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 automatischen Agents direkt in ein Beobachtbarkeits-Backend exportieren

Sie können nicht nur die Umgebungsvariable FIRESTORE_ENABLE_TRACING=ON festlegen, müssen Sie die OpenTelemetry-Java-Agent-Erweiterung für Ihr spezifisches Back-End. Im folgenden Beispiel wird die Trace-Exporter-Erweiterung verwendet. und ein Trace Sampling-Verhältnis von 10 %.

Terminal

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                                              \

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 für Trace-Spans

Beispiel für einen Trace-Span

Einen in Cloud Trace angezeigten Trace-Span

Beispiel für ein Ereignisprotokoll

Ein Trace-Span-Ereignisprotokoll, das in Cloud Trace angezeigt wird

Beispiele für Attributwerte

Attributwerte eines in Cloud Trace angezeigten Trace-Spans

Beispiel für einen Stacktrace und ein Ausnahmeereignis

Ein Stacktrace von Cloud Trace

Ein Ausnahmeereignis, das von Cloud Trace aufgerufen wurde

Nächste Schritte