Wenn Sie Firestore-Anfragen im Datastore-Modus (Datastore) Ende-zu-Ende überwachen und beheben möchten, können Sie in der Java-Clientbibliothek 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 vom Netzwerk und Clientsystem verursachten Latenz
- 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 auf dem Client auftritt.
OpenTelemetry
Traces für die Java-Clientbibliothek 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 Span-Limits.
Traces mit Exporteuren 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 (OpenTelemetry Protocol), verarbeitet sie und exportiert sie in Ihr Observability-Backend.
Beschränkungen
Traces-Speichen sind nur für die Java-Clientbibliothek verfügbar.
Abrechnung
Neben der Datastore-Nutzung können auch Kosten für die clientseitige Analyse 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 dem 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.
Hinweise
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.userTraces schreiben roles/cloudtrace.agentLese-/Schreibspuren roles/cloudtrace.adminPrü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:
- 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 Auto-Agents können Sie Traces ohne Codeänderungen konfigurieren. Sie müssen die Umgebungsvariable
DATASTORE_ENABLE_TRACING=ONfestlegen. Außerdem müssen Sie andere Konfigurationseinstellungen festlegen, wie unter Agentkonfiguration beschrieben. Sehen Sie sich die folgenden Beispiele an:
Traces mit OpenTelemetry APIs in einen Collector exportieren
Im folgenden Code wird die Java-Clientbibliothek für Datastore so konfiguriert, dass SPANs mit einer Stichprobenrate von 10% an 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();
Mit OpenTelemetry APIs direkt in ein Observability-Backend exportieren
Im folgenden Code wird die Java-Clientbibliothek so konfiguriert, dass Trace-Sequenzen mit einer Abtastrate von 10% direkt in Cloud Trace exportiert werden. Sie können die Exportfunktionen anderer Anbieter von Observability-Diensten verwenden, um Daten direkt in ihr Backend zu exportieren. Wenn Ihr Observability-Backend die OTLP-Aufnahme 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();
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.
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
Mit Auto Agents direkt in ein Observability-Backend exportieren
Zusätzlich zur Umgebungsvariablen DATASTORE_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.
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 Attribute und Ereignisse für Trace-Bereiche.
Beispiel für eine Trace-Span
Beispiel für ein Ereignisprotokoll
Beispielattributwerte
Nächste Schritte
- Weitere Informationen finden Sie in der Referenz zu Trace-Bereichsattributen und -Ereignissen.
- Weitere Informationen zum serverseitigen Monitoring