Configurazione di Cloud Logging per Java

Puoi scrivere i log in Cloud Logging da applicazioni Java utilizzando l'appendice di logback o java.util.logging handler, o utilizzando direttamente la libreria Cloud Logging per Java.

Per utilizzare l'agente Cloud Logging, non è necessario installare nella 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.

    Go to project selector

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

  3. Attiva Cloud Logging API.

    Abilita l'API

Appendice di logback per Cloud Logging

Con l'appendice 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.8-alpha</version>
</dependency>

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

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

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

libraryDependencies += "com.google.cloud" % "google-cloud-logging-logback" % "0.131.8-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 del log o fornire altri potenziatori. 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 l'utilizzo dell'appendice 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 in locale o all'esterno di Google Cloud. Questo snippet mostra come accedere utilizzando l'interfaccia 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");
  }
}

Gestore java.util.logging

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

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.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.43.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.19.0"

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

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

Configurazione java.util.logging

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 in locale 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 sezioni seguenti trattano la configurazione comune java.util.logging e l'appendice Logback per Cloud Logging.

Predefiniti

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

  • Nome log : java.log

  • Soglia minima per registrare : INFO

  • Gravità scarico : 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 pari o superiori alla gravità di svuotamento vengono immediatamente scritto.

Rilevamento delle risorse monitorate

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

L'appendice logback e il gestore java.util.logging forniscono del tipo di risorsa di App Engine, Compute Engine e Google Kubernetes Engine diverse applicazioni.

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

Puoi eseguire l'override del tipo di risorsa monitorata impostando un tipo valido nella configurazione dell'appender di logback. o java.util.logging Configurazione gestore.

Campi ed etichette aggiuntivi

Con l'appendice logback e il gestore java.util.logging, puoi aggiungere o aggiorna i campi su un oggetto LogEntry utilizzando un'istanza di LoggingEnhancer.

I potenziatori devono essere configurati come mostrato in Configurazione dell'appendice di log o il Configurazione 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, vedi documentazione relativa nella libreria Cloud Logging per Java. Puoi anche segnalare problemi utilizzando il tracker dei problemi.

Scrivi i log con la libreria client di Cloud Logging

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

Esegui su Google Cloud

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

App Engine

Cloud Logging è abilitato automaticamente per App Engine e default service account ha le autorizzazioni IAM per scrivere voci di log per impostazione predefinita.

nell'ambiente standard di App Engine, default, utilizza il parametro java.util.logging.Logger API; questo 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 è in bundle con la libreria Cloud Logging per Java.

È possibile utilizzare il gestore java.util.logging per registrare direttamente a Cloud Logging fornendo il logging.properties in 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'appender logback.

Quando viene eseguito nell'ambiente flessibile di App Engine, L'istanza TraceLoggingEnhancer aggiunge un ID traccia sicuro per thread a ogni voce di log utilizzando l'etichetta trace_id.

Google Kubernetes Engine (GKE)

GKE concede automaticamente l'account di servizio predefinito del ruolo IAM Writer log (roles/logging.logWriter). Se utilizzi Identità carico di lavoro con questo account di servizio predefinito per consentire ai carichi di lavoro di accedere API Google Cloud, non sono necessarie ulteriori configurazioni. Tuttavia, se utilizzi Workload Identity con un l'account di servizio IAM personalizzato, quindi assicurati che il servizio ha il ruolo di Writer log (roles/logging.logWriter).

Se necessario, puoi anche utilizzare il seguente comando per aggiungere logging.write quando crei il cluster:

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

Compute Engine

Quando utilizzi istanze VM di Compute Engine, aggiungi cloud-platform di ambito di accesso a ogni istanza. Quando crei una nuova istanza tramite Console Google Cloud, puoi farlo nella sezione Identità e accesso API. del riquadro Crea istanza. Usa il 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 in Identità e accesso API . Qualunque servizio l'account selezionato, accertati di aver ricevuto Ruolo Writer log in IAM e Amministratore di nella console Google Cloud.

Esegui localmente e altrove

Per utilizzare la libreria Cloud Logging per Java al di fuori di Google Cloud, compresa l'esecuzione della libreria sulla tua workstation, sul data center computer o sulle istanze VM di un altro cloud provider, fornisci l'ID progetto Google Cloud e i dati account di servizio le credenziali direttamente nella libreria Cloud Logging per Java.

Per gli account di servizio esistenti:

  1. Concedi all'account di servizio l'accesso IAM Ruolo IAM Autore di log (roles/logging.logWriter). Per ulteriori informazioni su IAM vedi Controllo dell'accesso.

  2. Configura Credenziali predefinite dell'applicazione.

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

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

Visualizza i log

Nella console Google Cloud, 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 risorsa la selezione potrebbe non essere ovvia. Ecco alcuni suggerimenti per aiutarti a data di inizio:

  • Se esegui il deployment della tua applicazione in App Engine o utilizzi 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, configurazione di logging del cluster determina il tipo di risorsa del log le voci corrispondenti. Per una panoramica Discussione su Legacy Google Cloud Observability e Google Cloud Observability le soluzioni di Kubernetes Monitoring e il modo in cui queste opzioni influiscono risorsa, consulta Migrazione a Kubernetes Monitoring di Google Cloud Observability.

  • Se la tua 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 utilizzarne una predefinita.

  • Se non vedi alcun log in Esplora log, per vedere tutte le voci di log, passare alla modalità di query avanzata e utilizzare 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 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.