Telemetriesignale in Cloud-Clientbibliotheken für Java aktivieren

Google Cloud bietet leistungsstarke Monitoring-, Protokollierungs- und Diagnosefunktionen für Java-Anwendungen.

Die Java-Clientbibliotheken sind so instrumentiert, dass sie Daten zu Tracing, Messwerten und Logging ausgeben. Die Instrumentierung ist optional. Sie müssen sie explizit aktivieren. In diesem Dokument werden die verfügbaren Signale und die Aktivierung beschrieben.

Verfügbare Signale

Zu den Golden Signals gehören die folgenden Telemetriedaten, die den OpenTelemetry semantischen Konventionen entsprechen:

  • Traces:HTTP-/gRPC-Traces auf niedriger Ebene, die die von den Clientbibliotheken ausgeführten Netzwerkanfragen darstellen.
  • Messwerte:Messwerte für Clientanfragen, mit denen Latenz und Anfrageraten erfasst werden. Der primäre Messwert ist gcp.client.request.duration.
  • Logs:Umsetzbare Fehlerlogs auf der Ebene DEBUG mit Details zu fehlgeschlagenen Anfragen auf der Transportschicht, auch wenn sie später erfolgreich wiederholt werden.

Die Signale enthalten standardmäßige OpenTelemetry-Attribute (z. B. http.response.status_code und rpc.system.name) und Google Cloud-spezifische benutzerdefinierte Attribute, die Folgendes und Ähnliches umfassen können:

  • gcp.client.service: Der Dienstname (z. B. pubsub oder storage).
  • gcp.client.repo: Das Repository der Clientbibliothek (z. B. googleapis/google-cloud-java).
  • gcp.client.version: Die Version der Clientbibliothek.
  • gcp.client.artifact: Der spezifische Modulpfad (z. B. com.google.cloud:google-cloud-secretmanager).
  • gcp.resource.destination.id: Die ID der Ressource, auf die sich die Aktion bezieht.
  • gcp.errors.domain: Die Fehlerdomain für umsetzbare Fehlerlogs.
  • gcp.errors.metadata.<key>: Zusätzliche Metadatenschlüssel für Fehler für fehlgeschlagene Anfragen (vereinfacht).

Eine vollständige Liste der Standardattribute finden Sie in den semantischen Konventionen von OpenTelemetry für HTTP und gRPC.

Telemetrie aktivieren

Zum Schutz sensibler Daten sind Telemetriesignale standardmäßig deaktiviert. Sie müssen sie explizit aktivieren.

Tracing und Messwerte

In den generierten Java-Clientbibliotheken müssen Sie Tracing und Messwerte programmatisch aktivieren, indem Sie bei der Initialisierung die entsprechende Tracer-Factory in den Einstellungen Ihres Clients angeben:

  • Tracing:Konfigurieren Sie den Client mit einer OpenTelemetryTracingFactory.
  • Messwerte:Konfigurieren Sie den Client mit einer OpenTelemetryMetricsFactory.
  • Beides:Wenn Sie sowohl Tracing als auch Messwerte aktivieren möchten, konfigurieren Sie den Client mit einer CompositeTracerFactory, die beide Factories umschließt.

Logging

Umsetzbare Fehlerlogs sind direkt in das zentrale ApiTracer-Framework eingebunden. Wenn Sie umsetzbare Fehlerlogs global für alle Ihre Google Cloud Clientbibliotheken aktivieren möchten, verwenden Sie die folgende Umgebungsvariable:

export GOOGLE_SDK_JAVA_LOGGING=true

Weitergabe von Trace-Kontext

Für die Weitergabe von Trace-Kontext in den Java-Clientbibliotheken muss das Tracing explizit aktiviert sein.

Wenn die Trace-Generierung aktiviert ist (z. B. durch Konfigurieren einer OpenTelemetryTracingFactory) und Ihre Anwendung im aktuellen Kontext eine aktive OpenTelemetry-Span hat, wenn eine Clientbibliothek-Methode aufgerufen wird, verwendet die Bibliothek diese, um einen Trace-Kontext für die ausgehenden Anfragen bereitzustellen. So können Sie Traces auf Anwendungsebene mit Logs und Verhaltensweisen des Backend-Dienstes korrelieren.

Telemetrie exportieren

Nachdem die Telemetrie in den Clientbibliotheken aktiviert wurde, muss Ihre Anwendung so konfiguriert sein, dass diese Daten erfasst und an Ihr Observability-Back-End exportiert werden.

Tracing und Messwerte

Wenn Sie die von den Java-Clientbibliotheken generierten Traces und Messwerte exportieren möchten, initialisieren Sie das OpenTelemetry SDK mit dem gewünschten Exporter (z. B. OTLP) und richten Sie den globalen Text Map Propagator in Ihrer Anwendung ein.

Weitere Informationen zum Erfassen und Exportieren von OpenTelemetry-Daten nach Cloud Monitoring oder Cloud Trace finden Sie unter Instrumentierungsansatz auswählen.

Logging

Die Java-Clientbibliotheken verwenden Standard-Logging-Frameworks wie SLF4J und java.util.logging. Wenn GOOGLE_SDK_JAVA_LOGGING=true festgelegt ist, werden umsetzbare Fehlerlogs auf der Ebene DEBUG ausgegeben.

Wenn Sie diese strukturierten Logs an Cloud Logging weiterleiten möchten, konfigurieren Sie Ihr Logging-Framework (z. B. Logback) so, dass JSON in die Standardausgabe (stdout) geschrieben wird. Wenn Sie in einer Umgebung wie Google Kubernetes Engine oder Cloud Run bereitstellen, werden diese Logs automatisch von den integrierten Agents erfasst.

Eine detaillierte Anleitung zum Konfigurieren von Logback oder java.util.logging zur Ausgabe von mit Cloud Logging kompatiblem JSON, einschließlich der Trace-Korrelation, finden Sie unter Strukturiertes Logging für Java konfigurieren.