Cloud Logging für Java einrichten

Sie können Logs von Java-Anwendungen mit dem Logback-Appender oder mit einem java.util.logging-Handler 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.

Hinweis

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the Cloud Logging API.

   Enable the API

5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

6. Make sure that billing is enabled for your Google Cloud project.

7. Enable the Cloud Logging API.

   Enable the API

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

If you are using Maven, add the following to your pom.xml file. For more information about BOMs, see The Google Cloud Platform Libraries BOM.

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

If you are using Gradle, add the following to your dependencies:

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

If you are using sbt, add the following to your dependencies:

libraryDependencies += "com.google.cloud" % "google-cloud-logging-logback" % "0.131.11-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 mithilfe eines standardmäßigen Java Logging API-Handlers verwenden.

Abhängigkeit installieren

If you are using Maven with a BOM, add the following to your pom.xml file:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>26.43.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>

If you are using Maven without a BOM, add this to your dependencies:

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

If you are using Gradle, add the following to your dependencies:

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

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

If you are using sbt, add the following to your dependencies:

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

If you're using Visual Studio Code, IntelliJ, or Eclipse, you can add client libraries to your project using the following IDE plugins:

• Cloud Code for VS Code
• Cloud Code for IntelliJ
• Cloud Tools for Eclipse

The plugins provide additional functionality, such as key management for service accounts. Refer to each plugin's documentation for details.

Note: Cloud Java client libraries do not currently support Android.

java.util.logging-Konfiguration

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

Hinweis: Wenn Sie die API der Cloud Logging-Bibliothek für Java direkt verwenden, gibt es keinen Standard-Lognamen und keinen unteren Schwellenwert.

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.

Hinweis: Wenn Sie die Cloud Logging API direkt verwenden, müssen Sie beim Logging mit der API einen gültigen, überwachten Ressourcentyp bereitstellen.

Zusätzliche Felder und Labels

Mit dem Logback-Appender und dem java.util.logging-Handler können Sie Felder auf einem LogEntry-Objekt mithilfe einer Instanz von 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. Dataflow-Protokolle enthalten diese Labels beispielsweise 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.

Protokolle 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 Protokolle mit der Cloud Logging-Bibliothek für Java schreiben kann, muss das Dienstkonto für die zugrunde liegende Ressource die IAM Log-Autor (roles/logging.logWriter) haben. In den meisten Google Cloud-Umgebungen wird das Standarddienstkonto automatisch mit dieser 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 versieht eine TraceLoggingEnhancer-Instanz jeden Logeintrag mithilfe des Labels trace_id mit einer threadsicheren Trace-ID.

Google Kubernetes Engine (GKE)

GKE gewährt dem Standarddienstkonto automatisch die IAM-Rolle Logautor (roles/logging.logWriter). Wenn Sie Workload Identity Federation for GKE mit diesem Standarddienstkonto verwenden, um Arbeitslasten Zugriff auf bestimmte Google Cloud APIs zu gewähren, ist keine zusätzliche Konfiguration erforderlich. Wenn Sie die Workload Identity-Föderation für GKE jedoch mit einem benutzerdefinierten IAM-Dienstkonto verwenden, muss das benutzerdefinierte Dienstkonto die Rolle „Logs Writer“ (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

Hinweis: Zur Verwendung der Cloud Logging-Bibliothek für Java auf einer Compute Engine-VM-Instanz muss der Cloud Logging-Agent nicht installiert werden.

Wenn Sie Compute Engine-VM-Instanzen verwenden, fügen Sie der jeweiligen Instanz den Zugriffsbereich für cloud-platform hinzu. In der Google Cloud Console können Sie das beim Erstellen einer neuen Instanz im Bereich Instanz erstellen im Abschnitt Identität und API-Zugriff erledigen. 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 Abschnitt IAM & Verwaltung der Google Cloud Console die Rolle „Log-Autor“ zugewiesen ist.

Lokal und extern ausführen

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

So gehen Sie bei vorhandenen Dienstkonten vor:

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

2. Richten Sie Standardanmeldedaten für Anwendungen ein.

Wenn Sie kein Dienstkonto haben, erstellen Sie eins. Weitere Informationen finden Sie unter Dienstkonten erstellen.

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

Logs ansehen

Rufen Sie in der Google Cloud Console die Seite Log-Explorer auf.

Zum Log-Explorer

Wenn Sie diese Seite über die Suchleiste suchen, wählen Sie das Ergebnis aus, dessen Zwischenüberschrift Logging ist.

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. Weitere Informationen zu den Lösungen mit Legacy Google Cloud Observability und Google Cloud Observability Kubernetes Monitoring und den jeweiligen Auswirkungen auf den Ressourcentyp finden Sie unter Zu Google Cloud Observability Kubernetes Monitoring 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ü (▾) 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.