Cloud Logging für Java einrichten

Mit dem Logback-Appender oder einem java.util.logging handler können Sie Logs von Java-Anwendungen in Cloud Logging schreiben. Dies ist auch direkt über die Cloud Logging-Bibliothek für Java möglich.

Der Cloud Logging-Agent muss nicht installiert sein, um die Cloud Logging-Bibliothek für Java verwenden zu können.

Hinweise

  1. Melden Sie sich bei Ihrem Google Cloud-Konto an. Wenn Sie mit Google Cloud noch nicht vertraut sind, erstellen Sie ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.

  2. Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.

    Zur Projektauswahl

  3. Die Abrechnung für das Google Cloud-Projekt muss aktiviert sein.

  4. Cloud Logging API aktivieren.

    Aktivieren Sie die API

    5.

  5. Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.

    Zur Projektauswahl

  6. Die Abrechnung für das Google Cloud-Projekt muss aktiviert sein.

  7. Cloud Logging API aktivieren.

    Aktivieren Sie die API

    8.

Logback-Appender für Cloud Logging

Wenn Sie mit dem Logback-Appender arbeiten, können Sie Cloud Logging mit der SLF4J-Logging-Fassade verwenden.

Abhängigkeit installieren

Wenn Sie Maven verwenden, fügen Sie Ihrer Datei pom.xml den folgenden Code hinzu. Weitere Informationen zu BOMs finden Sie unter The Google Cloud Platform Libraries BOM.

<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-logging-logback</artifactId>
  <version>0.131.4-alpha</version>
</dependency>

Wenn Sie Gradle verwenden, fügen Sie den Abhängigkeiten Folgendes hinzu:

implementation 'com.google.cloud:google-cloud-logging-logback:0.131.4-alpha'

Wenn Sie sbt nutzen, fügen Sie den Abhängigkeiten Folgendes hinzu:

libraryDependencies += "com.google.cloud" % "google-cloud-logging-logback" % "0.131.4-alpha"

Logback-Konfiguration

Logback kann programmgesteuert oder mit einem in XML oder Groovy geschriebenen Skript konfiguriert werden.

Sie können den unteren Wichtigkeitsschwellenwert oder den Lognamen anpassen oder zusätzliche Enhancer bereitstellen. Dies ist ein Beispiel für eine Logback-Konfiguration im XML-Format:

<configuration>
  <appender name="CLOUD" class="com.google.cloud.logging.logback.LoggingAppender">
    <!-- Optional : filter logs at or above a level -->
    <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
      <level>INFO</level>
    </filter>
    <log>application.log</log> <!-- Optional : default java.log -->
    <resourceType>gae_app</resourceType> <!-- Optional : default: auto-detected, fallback: global -->
    <enhancer>com.example.logging.logback.enhancers.ExampleEnhancer</enhancer> <!-- Optional -->
    <flushLevel>WARN</flushLevel> <!-- Optional : default ERROR -->
  </appender>

  <root level="info">
    <appender-ref ref="CLOUD" />
  </root>
</configuration>

Beispiel

Nachdem Sie Logback für die Verwendung des Cloud Logging Logback-Appenders konfiguriert haben, können Sie Logs mithilfe der SLF4J Logging API weiterleiten. Geben Sie die Google Cloud-Konfiguration an, wenn Sie das Beispiel lokal oder außerhalb von Google Cloud ausführen möchten. Dieses Snippet zeigt das Logging mit der SLF4J-Fassade in Ihrer Anwendung:


import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class Quickstart {
  private static final Logger logger = LoggerFactory.getLogger(Quickstart.class);

  public static void main(String[] args) {
    logger.info("Logging INFO with Logback");
    logger.error("Logging ERROR with Logback");
  }
}

java.util.logging-Handler

Sie können die Cloud Logging API auch mit einem standardmäßigen Java Logging API-Handler verwenden.

Abhängigkeit installieren

Wenn Sie Maven mit einer BOM verwenden, fügen Sie der Datei pom.xml Folgendes hinzu:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>26.35.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-logging</artifactId>
  </dependency>

  <!-- ...
</dependencies>

Wenn Sie Maven ohne BOM verwenden, fügen Sie Ihren Abhängigkeiten Folgendes hinzu:

<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-logging</artifactId>
  <version>3.16.2</version>
</dependency>

Wenn Sie Gradle verwenden, fügen Sie den Abhängigkeiten Folgendes hinzu:

implementation platform('com.google.cloud:libraries-bom:26.37.0')

implementation 'com.google.cloud:google-cloud-logging'

Wenn Sie sbt nutzen, fügen Sie den Abhängigkeiten Folgendes hinzu:

libraryDependencies += "com.google.cloud" % "google-cloud-logging" % "3.16.2"

Wenn Sie Visual Studio Code, IntelliJ oder Eclipse verwenden, können Sie Ihrem Projekt mithilfe der folgenden IDE-Plug-ins Clientbibliotheken hinzufügen:

Diese Plug-ins bieten zusätzliche Funktionen wie die Schlüsselverwaltung für Dienstkonten. Einzelheiten finden Sie in der Dokumentation der einzelnen Plug-ins.

java.util.logging configuration

Logging-Handler können programmgesteuert oder mit einer Konfigurationsdatei hinzugefügt werden. Der Pfad zur Konfigurationsdatei muss Ihrer Anwendung als Systemattribut übergeben werden: -Djava.util.logging.config.file=/path/to/logging.properties

Hier ein Beispiel für eine Konfigurationsdatei: 

# To use this configuration, add to system properties : -Djava.util.logging.config.file="/path/to/file"
#
.level = INFO

# it is recommended that io.grpc and sun.net logging level is kept at INFO level,
# as both these packages are used by Cloud internals and can result in verbose / initialization problems.
io.grpc.netty.level=INFO
sun.net.level=INFO

com.example.logging.jul.Quickstart.handlers=com.google.cloud.logging.LoggingHandler
# default : java.log
com.google.cloud.logging.LoggingHandler.log=custom_log

# default : INFO
com.google.cloud.logging.LoggingHandler.level=FINE

# default : ERROR
com.google.cloud.logging.LoggingHandler.flushLevel=ERROR

# default : auto-detected, fallback "global"
com.google.cloud.logging.LoggingHandler.resourceType=container

# custom formatter
com.google.cloud.logging.LoggingHandler.formatter=java.util.logging.SimpleFormatter
java.util.logging.SimpleFormatter.format=%3$s: %5$s%6$s

#optional enhancers (to add additional fields, labels)
com.google.cloud.logging.LoggingHandler.enhancers=com.example.logging.jul.enhancers.ExampleEnhancer

Beispiel

Geben Sie die Google Cloud-Konfiguration an, wenn Sie das Beispiel lokal oder außerhalb von Google Cloud ausführen möchten. Dieses Snippet zeigt das Logging mit java.util.logging: 


import java.util.logging.Logger;

public class Quickstart {
  private static final Logger logger = Logger.getLogger(Quickstart.class.getName());

  public static void main(String[] args) {
    logger.info("Logging INFO with java.util.logging");
    logger.severe("Logging ERROR with java.util.logging");
  }
}

Gängige Konfiguration

In den folgenden Abschnitten geht es um die gängige Konfiguration für den Handler java.util.logging und den Logback-Appender für Cloud Logging.

Standardeinstellungen

Für den Logback-Appender und den java.util.logging-Handler gelten die folgenden Standardwerte zur Instanziierung eines Cloud Logging-Clients:

  • Logname: java.log

  • Unterer Schwellenwert für das Logging: INFO

  • Löschwichtigkeit: ERROR

Die Cloud Logging-Bibliothek für Java fasst Nachrichten je nach Größe und Zeitangabe seit dem letzten Schreibvorgang in Batches zusammen. Batches mit Logging-Anfragen, die mindestens die Löschwichtigkeit aufweisen, werden sofort ausgeschrieben.

Erkennung überwachter Ressourcen

Bei allen Logs, die über die Cloud Logging-Bibliotheken gesendet werden, ist ein überwachter Ressourcentyp erforderlich, durch den Ihre Anwendung identifiziert wird.

Der Logback-Appender und der java.util.logging-Handler ermöglichen die automatische Erkennung des Ressourcentyps Ihrer App Engine-, Compute Engine- und Google Kubernetes Engine-Anwendungen.

In anderen Umgebungen wird standardmäßig die überwachte Ressource des Typs global verwendet.

Sie können den Typ der überwachten Ressource in der Logback-Appender-Konfiguration oder in der Konfiguration des java.util.logging-Handlers mit einem gültigen Typ überschreiben.

Zusätzliche Felder und Labels

Mit dem Logback-Appender und dem java.util.logging-Handler können Sie Felder auf einem LogEntry mithilfe einer LoggingEnhancer hinzufügen oder aktualisieren.

Die Enhancer müssen wie in der Logback-Appender-Konfiguration oder der java.util.logging-Handler-Konfiguration konfiguriert sein:


import com.google.cloud.logging.LogEntry;
import com.google.cloud.logging.LoggingEnhancer;

// Add / update additional fields to the log entry
public class ExampleEnhancer implements LoggingEnhancer {

  @Override
  public void enhanceLogEntry(LogEntry.Builder logEntry) {
    // add additional labels
    logEntry.addLabel("test-label-1", "test-value-1");
  }
}

Die Verwendung benutzerdefinierter Labels wird für Ihre Konfiguration möglicherweise nicht unterstützt. Beispielsweise enthalten Dataflow-Logs diese Labels nicht.

Weitere Informationen zur Installation finden Sie in der Dokumentation zur Cloud Logging-Bibliothek für Java. Probleme können Sie über die Problemverfolgung melden.

Logs mit der Cloud Logging-Clientbibliothek schreiben

Informationen zur direkten Verwendung der Cloud Logging-Clientbibliothek für Java finden Sie unter Cloud Logging-Clientbibliotheken.

In Google Cloud ausführen

Damit eine Anwendung Logs mithilfe der Cloud Logging-Bibliothek für Java schreiben kann, muss das Dienstkonto für die zugrunde liegende Ressource die IAM-Rolle Logautor (roles/logging.logWriter) haben. In den meisten Google Cloud-Umgebungen wird das Standarddienstkonto automatisch für diese Rolle konfiguriert.

App Engine

Cloud Logging ist für App Engine automatisch aktiviert und das Standarddienstkonto Ihrer Anwendung hat standardmäßig die IAM-Berechtigungen zum Schreiben von Logeinträgen.

In der App Engine-Standardumgebung wird standardmäßig die java.util.logging.Logger API verwendet. Dadurch wird direkt in Cloud Logging geschrieben und die Konfiguration somit vereinfacht.

Weitere Informationen finden Sie in der App Engine-Dokumentation Anwendungslogs lesen und schreiben.

Flexible App Engine-Umgebung

In der flexiblen App Engine-Umgebung verwendet java.util.logging standardmäßig ConsoleHandler und sendet die Logs an stdout und stderr.

Die Jetty-Laufzeit wird zusammen mit der Cloud Logging-Bibliothek für Java bereitgestellt.

Mit dem java.util.logging-Handler können Sie Logs direkt in Cloud Logging schreiben. Dazu müssen die logging.properties, wie hier dargestellt, in der Datei app.yaml angegeben werden:

    env_variables:
      JETTY_ARGS: -Djava.util.logging.config.file=WEB-INF/logging.properties

In Jetty-Laufzeiten ist das Logging von Trace-IDs möglich, wenn Sie den java.util.logging-Handler oder den Logback-Appender verwenden.

Bei der Ausführung in der flexiblen App Engine-Umgebung fügt eine TraceLoggingEnhancer jedem Logeintrag mit dem Label trace_id eine Thread-sichere Trace-ID hinzu.

Google Kubernetes Engine (GKE)

GKE weist dem Standarddienstkonto automatisch die IAM-Rolle Logautor (roles/logging.logWriter) zu. Wenn Sie Workload Identity mit diesem Standarddienstkonto verwenden, damit Arbeitslasten auf bestimmte Google Cloud APIs zugreifen können, ist keine zusätzliche Konfiguration erforderlich. Wenn Sie Workload Identity jedoch mit einem benutzerdefinierten IAM-Dienstkonto verwenden, muss das benutzerdefinierte Dienstkonto die Rolle „Logautor“ (roles/logging.logWriter) haben.

Bei Bedarf können Sie auch den folgenden Befehl verwenden, um beim Erstellen des Clusters den Zugriffsbereich logging.write hinzuzufügen:

gcloud container clusters create example-cluster-name \
    --scopes https://www.googleapis.com/auth/logging.write

Compute Engine

Wenn Sie Compute Engine-VM-Instanzen verwenden, fügen Sie der jeweiligen Instanz den Zugriffsbereich für cloud-platform hinzu. Wenn Sie eine neue Instanz über die Google Cloud Console erstellen, können Sie dies im Bereich Instanz erstellen im Abschnitt Identität und API-Zugriff tun. Verwenden Sie das Compute Engine-Standarddienstkonto oder ein anderes Dienstkonto und wählen Sie im Abschnitt Identität und API-Zugriff die Option Uneingeschränkten Zugriff auf alle Cloud APIs zulassen aus. Achten Sie darauf, dass jedem ausgewählten Dienstkonto im Bereich IAM & Verwaltung der Google Cloud Console die Rolle „Logautor“ zugewiesen ist.

Lokal und extern ausführen

Wenn Sie die Cloud Logging-Bibliothek für Java außerhalb von Google Cloud verwenden möchten, beispielsweise auf Ihrer eigenen Workstation, auf den Computern Ihres Rechenzentrums oder auf den VM-Instanzen eines anderen Cloud-Anbieters, müssen Sie Ihre Google Cloud-Projekt-ID und die entsprechenden Dienstkonto-Anmeldedaten direkt in der Cloud Logging-Bibliothek für Java angeben.

Gehen Sie bei vorhandenen Dienstkonten so vor:

  1. Gewähren Sie dem Dienstkonto die IAM-Rolle Logautor (roles/logging.logWriter). Weitere Informationen zu IAM-Rollen finden Sie unter Zugriffssteuerung.

  2. Standardanmeldedaten für Anwendungen einrichten

Wenn Sie noch kein Dienstkonto haben, erstellen Sie eines. Informationen zu diesem Prozess finden Sie unter Dienstkonten erstellen.

Allgemeine Informationen zu den Authentifizierungsmethoden finden Sie unter Terminologie: Dienstkonten.

Logs ansehen

Wählen Sie im Navigationsbereich der Google Cloud Console Logging und anschließend Log-Explorer aus:

Zum Log-Explorer

Im Log-Explorer müssen Sie eine oder mehrere Ressourcen angeben. Die Auswahl der Ressourcen ist jedoch möglicherweise nicht offensichtlich. Hier sind ein paar Tipps für den Einstieg.

  • Wenn Sie Ihre Anwendung für App Engine bereitstellen oder die App Engine-spezifischen Bibliotheken verwenden, setzen Sie die Ressource auf GAE-Anwendung.

  • Wenn Sie Ihre Anwendung auf der Compute Engine bereitstellen, setzen Sie die Ressource auf GCE-VM-Instanz.

  • Wenn Sie Ihre Anwendung in Google Kubernetes Engine bereitstellen, wird der Ressourcentyp der Logeinträge von der Loggingkonfiguration des Clusters bestimmt. Eine ausführliche Erläuterung der Legacy-Lösungen für die Beobachtbarkeit von Google Cloud und von Kubernetes Monitoring für die Beobachtbarkeit von Google Cloud sowie zu den Auswirkungen dieser Optionen auf den Ressourcentyp finden Sie unter Zu Google Cloud-Kubernetes Monitoring für die Beobachtbarkeit migrieren.

  • Wenn Ihre Anwendung die Cloud Logging API direkt nutzt, ist die Ressource von der API und Ihrer Konfiguration abhängig. Sie können in Ihrer Anwendung zum Beispiel eine Ressource angeben oder eine Standardressource verwenden.

  • Wenn im Log-Explorer keine Logs zu sehen sind, wechseln Sie zum erweiterten Abfragemodus und verwenden Sie eine leere Abfrage, um alle Logeinträge zu sehen.

    1. Klicken Sie oben im Log-Explorer auf das Dreipunkt-Menü (&blacktriangledown;) und wählen Sie In erweiterten Filter umwandeln aus, um zum erweiterten Abfragemodus zu wechseln.
    2. Löschen Sie den Inhalt, der im Filterfeld angezeigt wird.
    3. Klicken Sie auf Filter senden.

    Sie können die einzelnen Einträge prüfen, um Ihre Ressourcen zu identifizieren.

Weitere Informationen finden Sie unter Log-Explorer verwenden.