Configurazione di Cloud Logging per Java

Puoi scrivere log in Cloud Logging dalle applicazioni Java utilizzando l' appender Logback o un java.util.logging handler, oppure utilizzando direttamente la libreria Cloud Logging per Java.

Non è necessario installare l'agente Cloud Logging per utilizzare la libreria Cloud Logging per Java.

Prima di iniziare

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the Cloud Logging API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

Appender Logback per Cloud Logging

Utilizzando l'appender Logback, puoi utilizzare Cloud Logging con la facciata di logging SLF4J.

Installazione della dipendenza

Se utilizzi Maven, aggiungi quanto segue al file pom.xml. Per saperne di più sulle BOM, consulta La BOM delle librerie di Google Cloud Platform.

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

Se utilizzi Gradle, aggiungi quanto segue alle dipendenze:

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

Se utilizzi sbt, aggiungi quanto segue alle dipendenze:

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

Configurazione di Logback

Logback può essere configurato a livello di programmazione o utilizzando uno script espresso in XML o Groovy.

Puoi personalizzare la soglia di gravità minima, il nome del log o fornire ulteriori miglioramenti. Di seguito è riportata una configurazione di Logback di esempio in formato XML:

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

Esempio

Dopo aver configurato Logback per utilizzare l'appender Logback di Cloud Logging, puoi reindirizzare i log utilizzando l'API di logging SLF4J. Fornisci Google Cloud configurazione se prevedi di eseguire l'esempio localmente o al di fuori di Google Cloud. Questo snippet mostra come eseguire il logging utilizzando la facciata SLF4J all'interno dell'applicazione:


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");
  }
}

L'handler java.util.logging

Puoi anche utilizzare l'API Cloud Logging utilizzando un handler API Java Logging predefinito handler.

Installazione della dipendenza

Se utilizzi Maven con una BOM, aggiungi quanto segue al file pom.xml file:

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

Se utilizzi Maven senza una BOM, aggiungi quanto segue alle dipendenze:

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

Se utilizzi Gradle, aggiungi quanto segue alle dipendenze:

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

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

Se utilizzi sbt, aggiungi quanto segue alle dipendenze:

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

Se utilizzi Visual Studio Code o IntelliJ, puoi aggiungere librerie client al tuo progetto utilizzando i seguenti plug-in IDE:

I plug-in forniscono funzionalità aggiuntive, come la gestione delle chiavi per i service account. Per maggiori dettagli, consulta la documentazione di ogni plug-in.

Configurazione di java.util.logging

Gli handler di logging possono essere aggiunti a livello di programmazione o utilizzando un file di configurazione. Il percorso del file di configurazione deve essere fornito all'applicazione come proprietà di sistema:

  -Djava.util.logging.config.file=/path/to/logging.properties

Ecco un esempio di file di configurazione: 

# 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

Esempio

Fornisci Google Cloud configurazione se prevedi di eseguire l'esempio localmente o al di fuori di Google Cloud. Questo snippet mostra come eseguire il logging utilizzando 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");
  }
}

Configurazione comune

Le sezioni seguenti riguardano la configurazione comune al gestore java.util.logging e all'appender Logback per Cloud Logging.

Predefiniti

L'appender Logback e l'handler java.util.logging utilizzano i seguenti valori predefiniti per creare un'istanza di un client Cloud Logging:

  • Nome log : java.log

  • Soglia minima per il logging : INFO

  • Gravità di scaricamento : ERROR

La libreria Cloud Logging per Java raggruppa i messaggi in batch in base alle dimensioni e al tempo trascorso dall'ultima scrittura. I batch con richieste di logging con gravità pari o superiore alla gravità di scaricamento vengono scritti immediatamente.

Rilevamento delle risorse monitorate

Tutti i log inviati tramite le librerie Cloud Logging richiedono un tipo di risorsa monitorata per identificare l'applicazione.

L'appender Logback e l'handler java.util.logging forniscono il rilevamento automatico del tipo di risorsa delle applicazioni App Engine, Compute Engine e Google Kubernetes Engine.

In altri ambienti viene utilizzata una risorsa monitorata global come predefinita.

Puoi sostituire il tipo di risorsa monitorata con un tipo valido nella configurazione dell'appender Logback o nella java.util.logging configurazione dell'handler.

Campi ed etichette aggiuntivi

Utilizzando l'appender Logback e l'java.util.logging handler, puoi aggiungere o aggiornare i campi di un oggetto LogEntry utilizzando un'istanza di LoggingEnhancer.

I miglioramenti devono essere configurati come mostrato nella configurazione dell'appender Logback o nella java.util.logging configurazione dell'handler:


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");
  }
}

L'utilizzo di etichette personalizzate potrebbe non essere supportato per la tua configurazione. Ad esempio, i log di Dataflow non includono queste etichette.

Per saperne di più sull'installazione, consulta la documentazione della libreria Cloud Logging per Java. Puoi anche segnalare i problemi utilizzando il tracker dei problemi.

Scrivere log con la libreria client Cloud Logging

Per informazioni sull'utilizzo diretto della libreria client Cloud Logging per Java, consulta Librerie client Cloud Logging.

Esegui su Google Cloud

Affinché un'applicazione possa scrivere log utilizzando la libreria Cloud Logging per Java, il account di servizio della risorsa sottostante deve avere il ruolo IAM Writer log (roles/logging.logWriter). La maggior parte degli Google Cloud ambienti configura automaticamente il account di servizio predefinito in modo che abbia questo ruolo.

App Engine

Cloud Logging è abilitato automaticamente per App Engine e il service account predefinito della tua app dispone delle autorizzazioni IAM per scrivere voci di log.

Per impostazione predefinita, l'ambiente standard di App Engine utilizza l'API java.util.logging.Logger, che scrive direttamente in Cloud Logging ed è facile da configurare.

Per ulteriori dettagli, consulta la documentazione di App Engine su lettura e scrittura dei log delle applicazioni.

Ambiente flessibile di App Engine

Nell'ambiente flessibile di App Engine, java.util.logging utilizza ConsoleHandler per impostazione predefinita e invia i log a stdout e stderr.

Il Runtime Jetty è incluso nella libreria Cloud Logging per Java.

L'java.util.logging handler può essere utilizzato per eseguire il logging direttamente in Cloud Logging fornendo logging.properties in app.yaml come mostrato di seguito:

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

Il logging degli ID traccia è disponibile nei runtime Jetty se utilizzi l'handler java.util.logging o l'appender Logback.

Quando viene eseguita nell'ambiente flessibile di App Engine, un' TraceLoggingEnhancer aggiunge un ID traccia thread-safe a ogni voce di log utilizzando l'etichetta trace_id.

Google Kubernetes Engine (GKE)

GKE concede automaticamente al account di servizio predefinito il ruolo IAM Writer log (roles/logging.logWriter). Se utilizzi Workload Identity Federation for GKE con questo account di servizio predefinito per consentire ai carichi di lavoro di accedere ad API specifiche Google Cloud , non è necessaria alcuna configurazione aggiuntiva. Tuttavia, se utilizzi Workload Identity Federation for GKE con un account di servizio IAM personalizzato, assicurati che il service account personalizzato abbia il ruolo Writer log (roles/logging.logWriter).

Se necessario, puoi anche utilizzare il seguente comando per aggiungere l'ambito di accesso logging.write durante la creazione del cluster:

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

Compute Engine

Quando utilizzi le istanze VM di Compute Engine, aggiungi lo cloud-platform ambito di accesso a ogni istanza. Quando crei una nuova istanza tramite la Google Cloud console, puoi farlo nella sezione Identità e accesso API del riquadro Crea istanza. Utilizza il service account predefinito di Compute Engine o un altro account di servizio di tua scelta e seleziona Consenti l'accesso completo a tutte le API Cloud nella sezione Identità e accesso API. Qualunque sia il service account selezionato, assicurati che gli sia stato concesso il ruolo Writer log nella sezione IAM e amministrazione della Google Cloud console.

Esegui localmente e altrove

Per utilizzare la libreria Cloud Logging per Java al di fuori di Google Cloud, inclusa l'esecuzione della libreria sulla tua workstation, sui computer del tuo data center's o sulle istanze VM di un altro provider cloud, devi configurare le Credenziali predefinite dell'applicazione (ADC) nel tuo ambiente locale per l'autenticazione alla libreria Cloud Logging per Java.

Per saperne di più, consulta Configura ADC per on-premise o un altro provider cloud.

Visualizzare i log

Nella Google Cloud console, vai alla pagina Esplora log:

Vai a Esplora log

Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Logging.

In Esplora log, devi specificare una o più risorse, ma la selezione delle risorse potrebbe non essere ovvia. Ecco alcuni suggerimenti che ti aiuteranno a iniziare.

  • Se esegui il deployment dell'applicazione in App Engine o utilizzi le librerie specifiche di App Engine, imposta la risorsa su Applicazione GAE.

  • Se esegui il deployment dell'applicazione su Compute Engine, imposta la risorsa su Istanza VM GCE.

  • Se esegui il deployment dell'applicazione su Google Kubernetes Engine, la configurazione di logging del cluster determina il tipo di risorsa delle voci di log. Per una discussione dettagliata sulle soluzioni Legacy Google Cloud Observability e Google Cloud Observability Kubernetes Monitoring e su come queste opzioni influiscono sul tipo di risorsa, consulta Eseguire la migrazione a Google Cloud Observability Kubernetes Monitoring.

  • Se l'applicazione utilizza direttamente l'API Cloud Logging, la risorsa dipende dall'API e dalla configurazione. Ad esempio, nella tua applicazione puoi specificare una risorsa o utilizzare una risorsa predefinita.

  • Se non vedi alcun log in Esplora log, per visualizzare tutte le voci di log, passa alla modalità di query avanzata e utilizza una query vuota.

    1. Per passare alla modalità di query avanzata, fai clic su menu (&blacktriangledown;) nella parte superiore di Esplora log e seleziona Converti in filtro avanzato.
    2. Cancella i contenuti visualizzati nella casella del filtro.
    3. Fai clic su Invia filtro.

    Puoi esaminare le singole voci per identificare le tue risorse.

Per ulteriori informazioni, consulta Utilizzo di Esplora log.