Configurazione di Cloud Logging per Java

Puoi scrivere log in Cloud Logging dalle applicazioni Java utilizzando l'appendice Logback, un java.util.logging handler oppure 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. Accedi al tuo account Google Cloud. Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti gratuiti per l'esecuzione, il test e il deployment dei carichi di lavoro.

2. Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.

   Nota: se non prevedi di conservare le risorse create in questa procedura, crea un progetto anziché selezionarne uno esistente. Dopo aver completato questi passaggi, puoi eliminare il progetto, rimuovendo tutte le risorse associate.

   Vai al selettore progetti

3. Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

4. Attiva Cloud Logging API.

   Abilita l'API

5. Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.

   Nota: se non prevedi di conservare le risorse create in questa procedura, crea un progetto anziché selezionarne uno esistente. Dopo aver completato questi passaggi, puoi eliminare il progetto, rimuovendo tutte le risorse associate.

   Vai al selettore progetti

6. Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

7. Attiva Cloud Logging API.

   Abilita l'API

Appendice di logback per Cloud Logging

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

Installazione della dipendenza

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.4-alpha</version>
</dependency>

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

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

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

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

Configurazione del logback

Il logback può essere configurato in modo programmatico o utilizzando uno script espresso in XML o Groovy.

Puoi personalizzare la soglia di gravità minima, il nome log o fornire strumenti di miglioramento aggiuntivi. Questa è 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 di logback di Cloud Logging, ora puoi reindirizzare i log utilizzando l'API di logging SLF4J. Fornisci la configurazione di Google Cloud se prevedi di eseguire l'esempio localmente o all'esterno di Google Cloud. Questo snippet mostra come accedere utilizzando SLF4Jiscrizione 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");
  }
}

Gestore java.util.logging

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

Installazione della dipendenza

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.37.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.16.3</version>
</dependency>

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

implementation platform('com.google.cloud:libraries-bom:26.37.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.16.3"

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 configuration

I gestori di logging possono essere aggiunti in modo programmatico 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 la configurazione di Google Cloud se prevedi di eseguire l'esempio localmente o all'esterno di Google Cloud. Questo snippet mostra come accedere 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 seguenti sezioni descrivono la configurazione comune al gestore java.util.logging e all'appendice Logback per Cloud Logging.

Valori predefiniti

L'appendice di logback e il gestore java.util.logging utilizzano i seguenti valori predefiniti per creare l'istanza di un client Cloud Logging:

• Nome log : java.log

• Soglia minima da registrare : INFO

• Gravità flush : ERROR

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

Nota: se utilizzi direttamente la libreria Cloud Logging per l'API Java, non esiste un nome di log predefinito o una soglia minima.

Rilevamento delle risorse monitorate

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

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

Una risorsa monitorata global viene utilizzata come predefinita in altri ambienti.

Puoi eseguire l'override del tipo di risorsa monitorata in un tipo valido nella Configurazione dell'appendice di log o nella Configurazione del gestore java.util.logging.

Nota: se utilizzi direttamente l'API Cloud Logging, devi fornire un tipo di risorsa monitorata valido quando utilizzi l'API per il logging.

Etichette e campi aggiuntivi

Utilizzando l'appendice Logback e il gestore java.util.logging, puoi aggiungere o aggiornare i campi in un oggetto LogEntry utilizzando un'istanza di LoggingEnhancer.

Gli strumenti di miglioramento devono essere configurati come mostrato nella configurazione dell'appendice di logback o nella configurazione del gestore java.util.logging:

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 ulteriori informazioni sull'installazione, consulta la documentazione relativa alla libreria Cloud Logging per Java. Puoi anche segnalare i problemi utilizzando Issue Tracker.

Scrivere log con la libreria client di Cloud Logging

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

Esegui su Google Cloud

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

App Engine

Cloud Logging è abilitato automaticamente per App Engine e l'account di servizio predefinito della tua app dispone per impostazione predefinita delle autorizzazioni IAM per la scrittura di voci di log.

L'ambiente standard App Engine, per impostazione predefinita, 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 in 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 è integrato nella libreria Cloud Logging per Java.

Il gestore java.util.logging può essere utilizzato per accedere direttamente a Cloud Logging fornendo il logging.properties nel tuo app.yaml, come mostrato qui:

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

Il logging degli ID traccia è disponibile sui runtime Jetty se utilizzi il gestore java.util.logging o l'appendice Logback.

Durante l'esecuzione nell'ambiente flessibile di App Engine, un'istanza TraceLoggingEnhancer aggiunge un ID traccia sicura ai thread a ogni voce di log che utilizza l'etichetta trace_id.

Google Kubernetes Engine (GKE)

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

Se necessario, puoi anche utilizzare il comando seguente 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

Nota: per utilizzare la libreria Cloud Logging per Java su un'istanza VM di Compute Engine, non è necessario installare l'agente Cloud Logging.

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

Esegui in locale 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 o sulle istanze VM di un altro cloud provider, devi fornire l'ID progetto Google Cloud e le credenziali appropriate dell'account di servizio direttamente nella libreria Cloud Logging per Java.

Per gli account di servizio esistenti:

1. Concedi all'account di servizio il ruolo IAM Writer log (roles/logging.logWriter). Per ulteriori informazioni sui ruoli IAM, consulta Controllo dell'accesso.

2. Configura le credenziali predefinite dell'applicazione.

Se non hai un account di servizio, creane uno. Per informazioni su questo processo, consulta Creare account di servizio.

Per informazioni generali sui metodi che puoi utilizzare per l'autenticazione, consulta Terminologia: account di servizio.

Visualizza i log

Nel pannello di navigazione della console Google Cloud, seleziona Logging, quindi Esplora log:

Vai a Esplora log

In Esplora log, devi specificare una o più risorse, ma la selezione delle risorse potrebbe non essere chiara. Ecco alcuni suggerimenti per aiutarti a iniziare:

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

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

• Se esegui il deployment della tua 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 di Google Cloud per l'osservabilità e sull'osservabilità di Google Cloud, e su come queste opzioni influiscono sul tipo di risorsa, consulta Migrazione a Google Cloud Observability Kubernetes Monitoring.

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

• Se non vedi log in Esplora log, per vedere 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 (▾) nella parte superiore di Esplora log, quindi seleziona Converti in filtro avanzato.
  2. Cancella i contenuti visualizzati nella casella dei filtri.
  3. Fai clic su Invia filtro.

  Puoi esaminare le singole voci per identificare le risorse.

Per ulteriori informazioni, consulta Utilizzo di Esplora log.