Esegui la migrazione del logging ai runtime Java di seconda generazione

Alcuni aspetti della registrazione nei runtime di seconda generazione (Java 11 e versioni successive) sono diversi da quelli del runtime di prima generazione (Java 8). A differenza del runtime di prima generazione, nei runtime di seconda generazione, l'app I log non vengono raggruppati in log delle richieste all'interno di Esplora log. Inoltre, nei runtime di seconda generazione, App Engine scrive ogni log dell'app associato una richiesta come voce di log separata in Cloud Logging.

Questa guida descrive come implementare gli stessi metodi di registrazione utilizzati nelle app di runtime di prima generazione e ottenere quasi gli stessi risultati di filtraggio e correlazione dei log durante la migrazione dell'app a Java 11 e versioni successive.

Differenze principali

La tabella seguente illustra le differenze di logging tra il primo e il runtime di seconda generazione:

Runtime di prima generazione (Java 8) Runtime di seconda generazione (Java 11 e versioni successive)
Log delle richieste e delle app (chiamati anche log delle applicazioni) App Engine incorpora tutti i log dell'app nel log delle richieste. App Engine non incorpora i log delle app nel log delle richieste.
stdout e stderr App Engine incorpora i log scritti in stdout e stderr nel log delle richieste. App Engine non incorpora i log scritti in stdout e stderr.
Log della piattaforma App Engine App Engine non emette log della piattaforma interna. App Engine emette i log interni della piattaforma durante l'avvio o l'arresto di un con il nome log /var/log/google_init.log.
Quota dell'API Cloud Logging Ogni richiesta corrisponde Cloud Logging in scrittura. Ogni voce del log dell'app associata a una richiesta corrisponde a una scrittura di Cloud Logging. L'utilizzo dell'API Cloud Logging aumenta runtime di seconda generazione.

Log delle richieste e log delle app

Il comportamento di logging nei runtime di prima e seconda generazione è diverso nei seguenti modi:

  • Nel runtime di prima generazione, App Engine incorpora i log delle app nel protoPayload.line campo dei log delle richieste. Puoi visualizzare i log dell'app espandendo una richiesta in Esplora log.

    L'immagine seguente mostra i log delle richieste e delle app correlati nel runtime di prima generazione:

    Log correlati in Java 8

  • Nei runtime di seconda generazione, i log delle richieste non contengono il log delle app perché il campo protoPayload.line non è presente nel log delle richieste. App Engine registra invece ogni log dell'app come voce separata. La dipende dalla configurazione del logging. var/log/app contiene i log emessi utilizzando framework di logging standard come java.util.logging o la Simple Logging Facade per Java (SLF4J). I log stderr e stdout contengono app log registrati utilizzando System.err.print() o System.out.print().

    L'immagine seguente mostra log di richieste e app separati nei runtime di seconda generazione:

    Log separati in Java 11

stdout e stderr

Nel runtime di prima generazione, App Engine considera i log emessi stdout e stderr come log delle app e raggruppa automaticamente questi log delle app sotto il log delle richieste associato.

Nei runtime di seconda generazione, App Engine non correla i log emessi stdout e stderr per impostazione predefinita. Per raggruppare le entità dei log delle app con il log delle richieste utilizzando stdout e stderr, segui le istruzioni riportate in Scrivere log strutturati in stdout e stderr.

Non è consigliabile accedere a stdout e stderr perché alcuni App Engine dei log della piattaforma (JVM, Jetty, log dell'infrastruttura interna) vengono emessi stderr. I log dell'app e della piattaforma vengono visualizzati insieme al nome del log stderr, il che causa ambiguità. Questo problema è esagerato nei runtime di seconda generazione poiché App Engine ha un volume maggiore di log della piattaforma.

Log della piattaforma App Engine

Nel runtime di prima generazione, App Engine non emette log della piattaforma.

Nei runtime di seconda generazione, App Engine emette log della piattaforma durante l'avvio o l'arresto dell'istanza con il nome /var/log/google_init.log.

Puoi ignorare tranquillamente i log della piattaforma. Per evitare di visualizzare questi log, aggiungi un filtro a Esplora log con la query logName="/var/log/google_init.log".

L'immagine seguente mostra i log della piattaforma nei runtime di seconda generazione:

Log della piattaforma

Quota dell'API Cloud Logging

Nel runtime di prima generazione, App Engine incorpora tutti i log dell'app emessi durante una richiesta in un singolo log delle richieste e invia i dati a Cloud Logging. Ogni richiesta corrisponde a una scrittura di Cloud Logging.

Nei runtime di seconda generazione, App Engine invia ogni log dell'app a Cloud Logging in voci di log separate, causando un aumento del numero totale di scritture di Cloud Logging per richiesta.

Google Cloud determina la fatturazione in base allo spazio di archiviazione complessivo utilizzato da Cloud Logging utilizzi. Anche se lo spazio di archiviazione complessivo richiesto per i log non aumenta in modo significativo, l'aumento delle scritture al minuto, in base al numero di log delle app scritture da App Engine per ogni richiesta. Se la tua app supera la quota di scrittura di Cloud Logging, puoi richiedere un aumento della quota di utilizzo.

Per ulteriori informazioni, consulta i prezzi per Cloud Logging.

Panoramica del processo di migrazione

Anche se i log delle app non sono incorporati all'interno dei log delle richieste nella seconda generazione è possibile conservare l'esperienza di visualizzazione dei log come app di prima generazione.

Puoi scegliere una delle seguenti opzioni per la configurazione del logging nei runtime di seconda generazione:

Utilizza il pacchetto java.util.logging (Luglio)

Se le tue app che utilizzano il runtime di prima generazione implementano il pacchetto java.util.logging per tutti i requisiti di registrazione, la migrazione ai runtime di seconda generazione non richiede modifiche al codice.

L'esempio seguente mostra come utilizzare il pacchetto java.util.logging per il logging dei runtime di seconda generazione:

    package com.example.appengine.my_app;
    import java.io.IOException;
    import javax.servlet.annotation.WebServlet;
    import javax.servlet.http.*;
    import java.util.logging.Logger;

    @WebServlet(name = "HelloAppEngine", value = "/")
    public class HelloAppEngine extends HttpServlet {

      // Use the java.util.logging.Logger to log messages
      private static final Logger logger = Logger.getLogger(HelloAppEngine.class.getName());

      @Override
      public void doGet(HttpServletRequest request, HttpServletResponse response)
          throws IOException {
        // Sample log messages
        logger.info("Info message");
        logger.warning("Warning message");
        logger.severe("Severe message");

        response.setContentType("text/plain");
        response.getWriter().println("Hello App Engine");
      }
    }

Raggruppare i log delle app con il log delle richieste

Nei runtime di seconda generazione, il campo protoPayload.line nella richiesta non contiene i log delle app. Esplora log utilizza il campo trace per log delle richieste di gruppo e log delle app. Il pacchetto java.util.logging aggiunge automaticamente l'ID traccia a tutti i log delle richieste e delle app. Per visualizzare i log correlati nella Esplora log, consulta Visualizzare i log correlati.

Utilizza la Simple Logging Facade per Java (SLF4J)

SLF4J è l'interfaccia di logging più diffusa nelle applicazioni Java. Poiché è una rappresentazione, l'interfaccia SLF4J è indipendente dalla piattaforma del backend di logging, il che ti consente di scegliere qualsiasi backend adatto alle tue app.

L'immagine seguente mostra le opzioni di integrazione per due backend SLF4J, tra cui Libreria java.util.logging e aggiunta di logback:

Panoramica di SLF4J

SLF4J con pacchetto java.util.logging

SLF4J ti consente di integrare la tua app con Cloud Logging quando utilizzi SLF4J con java.util.logging come backend di logging. Per impostazione predefinita, App Engine aggiunge un ID traccia a tutti i log delle richieste e delle app. Questo meccanismo consente di raggruppare le richieste e i log delle app in Esplora log.

Per implementare SLF4J con java.util.logging:

  1. Aggiungi la dipendenza slf4j-jdk14.jar al file pom.xml. La Il file slf4j-jdk14.jar fornisce l'integrazione del backend per Libreria java.util.logging:

    <!-- SLF4J interface -->
<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-api</artifactId>
  <version>2.0.4</version>
</dependency>
<!-- JUL implementation for SLF4J -->
<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-jdk14</artifactId>
  <version>2.0.9</version>
</dependency>

  2. Crea un file WEB-INF/logging.properties per aggiungere configurazioni personalizzate:

    com.example.appengine.java8.HelloAppEngine.level = INFO

  3. Aggiorna il file appengine-web.xml in modo da includere il valore <property> per WEB-INF/logging.properties:

    <system-properties>
  <property name="java.util.logging.config.file" value="WEB-INF/logging.properties"/>
</system-properties>

La seguente immagine mostra come SLF4J con java.util.logging aggiunge automaticamente l'ID traccia in un log dell'app:

Raggruppa i log delle app per richiesta con ID traccia

Per ottimizzare la visualizzazione di Esplora log in modo che sia incentrata sulle richieste, come il runtime di prima generazione, consulta Visualizzare i log correlati.

Utilizzare SLF4J con l'appender Logback

Se le app di runtime di prima generazione utilizzano l'implementazione integrata di SLF4J con Logback, devi aggiornare il codice sorgente e implementare passaggi aggiuntivi per raggruppare i log delle richieste e delle app.

Per integrare l'app con Cloud Logging, segui questi passaggi:

  1. Aggiungi l'appendice google-cloud-logging-logback al file pom.xml per Installa l'appender di logging per Logback:

     <!-- SLF4J interface -->
 <dependency>
       <groupId>org.slf4j</groupId>
       <artifactId>slf4j-api</artifactId>
       <version>2.0.4</version>
 </dependency>

 <!-- Logback JARs -->
 <dependency>
       <groupId>ch.qos.logback</groupId>
       <artifactId>logback-classic</artifactId>
       <version>1.3.6</version>
 </dependency>
 <dependency>
       <groupId>ch.qos.logback</groupId>
       <artifactId>logback-core</artifactId>
       <version>1.3.5</version>
 </dependency>

 <!-- Google Cloud logging appender for Logback -->
 <dependency>
   <groupId>com.google.cloud</groupId>
   <artifactId>google-cloud-logging-logback</artifactId>
 </dependency>

  2. Crea un potenziatore di log per aggiungere un ID traccia a ogni campo LogEntry. La seguente classe TraceIdLoggingEnhancer utilizza l'API ApiProxy per recupera l'ID traccia associato a una richiesta:

      import com.google.appengine.api.utils.SystemProperty;
  import com.google.cloud.logging.LogEntry;
  import com.google.cloud.logging.LoggingEnhancer;

  import com.google.apphosting.api.ApiProxy;
  import com.google.apphosting.api.ApiProxy.Environment;

  // Add trace ID to the log entry
  public class TraceIdLoggingEnhancer implements LoggingEnhancer {

    @Override
    public void enhanceLogEntry(LogEntry.Builder logEntry) {
      final String PROJECT_ID = SystemProperty.applicationId.get();

      Environment environment = ApiProxy.getCurrentEnvironment();

      if (environment instanceof ApiProxy.EnvironmentWithTrace) {
        ApiProxy.EnvironmentWithTrace environmentWithTrace = (ApiProxy.EnvironmentWithTrace) environment;
        environmentWithTrace
            .getTraceId()
            .ifPresent(
                id ->
                  logEntry.setTrace(String.format("projects/%s/traces/%s", PROJECT_ID, id)));
      }
    }
  }
  // [END logging_enhancer]

  3. Aggiungi la configurazione dell'appender di Cloud Logging nel file logback.xml per configurare Logback. Il framework Logback gestisce la configurazione tramite logback.xml file in WEB-INF/classes:

    <configuration>
  <appender name="CLOUD" class="com.google.cloud.logging.logback.LoggingAppender">
      <!-- This should be set to the new Logging Enhancer in the app code. -->
      <enhancer>com.example.appengine.my_app.enhancers.TraceIdLoggingEnhancer</enhancer>
      <resourceType>gae_app</resourceType>
  </appender>
  <root level="info">
      <appender-ref ref="CLOUD" />
  </root>
</configuration>

    L'immagine seguente mostra la struttura finale della directory dell'app:

    Struttura delle directory

Visualizza log correlati

Puoi visualizzare i log correlati in Esplora log utilizzando il campo ID traccia in ogni voce di log. Per visualizzare i log correlati in Esplora log:

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

    Vai a Esplora log

  2. In Tipo di risorsa, seleziona Applicazione GAE.

  3. Per visualizzare e correlare i log delle richieste, in Nome log seleziona request_log. In alternativa, per eseguire la correlazione in base ai log delle richieste, fai clic su Correla per e seleziona request_log:

    Correlare i log

  4. Nel riquadro Risultati delle query, per espandere una voce di log, fai clic su Espandi. All'espansione, ogni richiesta registra verranno visualizzati i log delle app associati.