Migrar a geração de registros para ambientes de execução Java de segunda geração

Alguns aspectos da geração de registros nos ambientes de execução de segunda geração (Java 11+) são diferentes do ambiente de execução de primeira geração (Java 8). Ao contrário do ambiente de execução de primeira geração, nos de segunda geração, os registros de aplicativos não são agrupados nos registros de solicitação na Análise de registros. Além disso, nos ambientes de execução de segunda geração, o App Engine grava cada registro de aplicativo associado a uma solicitação como uma entrada de registro separada no Cloud Logging.

Este guia descreve como implementar os mesmos métodos de geração de registros usados nos apps de ambiente de execução de primeira geração e conseguir praticamente os mesmos resultados de filtragem e correlação de registro ao migrar seu app para o Java 11+.

Principais diferenças

A tabela a seguir aborda as diferenças na geração de registros entre os ambientes de execução de primeira e segunda geração:

	Ambiente de execução de primeira geração (Java 8)	Ambientes de execução de segunda geração (Java 11+)
Registros de solicitações e apps (também chamados de registros de aplicativos)	O App Engine incorpora todos os registros de apps no registro de solicitação.	O App Engine não incorpora registros de aplicativos ao registro de solicitações associado.
`stdout` e `stderr`	O App Engine incorpora registros gravados em `stdout` e `stderr` no registro de solicitação.	O App Engine não incorpora registros gravados em `stdout` e `stderr`.
Registros da plataforma App Engine	O App Engine não emite registros internos da plataforma.	O App Engine emite registros da plataforma interna durante a inicialização ou o encerramento de uma instância com o nome de registro `/var/log/google_init.log`.
Cota da API Cloud Logging	Cada solicitação corresponde a uma gravação do Cloud Logging.	Cada entrada de registro do app associada a uma solicitação corresponde a uma gravação do Cloud Logging. O uso da API Cloud Logging aumenta nos ambientes de execução de segunda geração.

Registros de solicitação e de apps

O comportamento de geração de registros em ambientes de execução de primeira e segunda geração é diferente das seguintes maneiras:

No ambiente de execução de primeira geração, o App Engine incorpora os registros do aplicativo no campo protoPayload.line dos registros de solicitação. Para acessar os registros de aplicativos, abra uma solicitação na Análise de registros.

A imagem a seguir mostra registros correlacionados de solicitações e aplicativos nos ambientes de execução de primeira geração:
Nos ambientes de execução de segunda geração, os registros de solicitação não contêm entradas de registro do app porque o campo protoPayload.line está ausente no registro de solicitação. Em vez disso, o App Engine registra cada registro de app como uma entrada separada. O nome do registro depende da configuração da geração de registros. var/log/app contém registros emitidos usando frameworks de geração de registros padrão, como java.util.logging ou a Facade simples de geração de registros para Java (SLF4J, na sigla em inglês). Os registros stderr e stdout contêm registros de apps que são registrados usando System.err.print() ou System.out.print().

A imagem a seguir mostra registros separados de solicitações e aplicativos nos ambientes de execução de segunda geração:

`stdout` e `stderr`

No ambiente de execução de primeira geração, o App Engine considera os registros emitidos para stdout e stderr como registros de aplicativos e agrupa automaticamente essas entradas de registro de aplicativo no registro de solicitação associado.

Nos ambientes de execução de segunda geração, o App Engine não correlaciona registros emitidos para stdout e stderr por padrão. Para agrupar entidades de registro do app com o registro de solicitação usando stdout e stderr, siga as instruções em Gravar registros estruturados em stdout e stderr. ,

Não recomendamos a geração de registros para stdout e stderr, já que alguns registros da plataforma do App Engine (JVM, local, registros da infraestrutura interna) também são emitidos para stderr. Os registros de apps e de plataforma aparecem junto com o nome do registro stderr, o que causa ambiguidade. Isso é exagerado nos ambientes de execução de segunda geração, já que o App Engine tem um volume maior de registros da plataforma.

Registros da plataforma App Engine

No ambiente de execução de primeira geração, o App Engine não emite registros da plataforma.

Nos ambientes de execução de segunda geração, o App Engine emite registros da plataforma durante a inicialização ou o encerramento da instância com o nome de registro /var/log/google_init.log.

Você pode ignorar os registros da plataforma com segurança. Para evitar que esses registros apareçam, adicione um filtro à Análise de registros com a consulta logName="/var/log/google_init.log".

A imagem a seguir mostra os registros da plataforma nos ambientes de execução de segunda geração:

Registros de plataforma

Cota da API Cloud Logging

No ambiente de execução de primeira geração, o App Engine incorpora todos os registros de aplicativos emitidos durante uma solicitação em um único registro de solicitação e envia a solicitação incorporada ao Cloud Logging. Cada solicitação corresponde a uma gravação do Cloud Logging.

Nos ambientes de execução de segunda geração, o App Engine envia cada registro de aplicativo para o Cloud Logging em entradas de registro separadas, causando um aumento no número total de gravações do Cloud Logging por solicitação.

O Google Cloud determina o faturamento com base no armazenamento geral usado pelo Cloud Logging. Mesmo que o armazenamento geral necessário para registros não aumente significativamente, as gravações por minuto aumentam, dependendo de quantos registros de aplicativos o App Engine grava por solicitação. Se o aplicativo exceder a cota de gravação do Cloud Logging, é possível solicitar um aumento da sua cota de uso.

Para mais informações, consulte os pricing do Cloud Logging.

Visão geral do processo de migração

Mesmo que os registros de aplicativos não sejam incorporados nos registros de solicitação nos ambientes de execução de segunda geração, é possível manter a experiência de visualização de registros como os aplicativos de primeira geração.

Escolha uma das seguintes opções para configurar a geração de registros nos ambientes de execução de segunda geração:

Usar o pacote java.util.logging (JUL): o App Engine tem suporte integrado para correlacionar registros de solicitação e de aplicativos com um ID de trace. Se o ID de rastreamento estiver presente nos registros do aplicativo, a Análise de registros renderizará os registros agrupados em um registro de solicitação.
Use o Simple Logging Facade para Java (SLF4J, na sigla em inglês): é necessário modificar o código-fonte para adicionar o ID do trace, dependendo do back-end de geração de registros usado pelo app:
- SLF4J com pacote java.util.logging
- SLF4J com anexador Logback

Usar o pacote `java.util.logging` (JUL)

Se os apps que usam o ambiente de execução de primeira geração implementarem o pacote java.util.logging para todos os requisitos de geração de registros, a migração para ambientes de execução de segunda geração não vai exigir mudanças no código.

O exemplo a seguir mostra como usar o pacote java.util.logging para geração de registros nos ambientes de execução de segunda geração:

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

Agrupar registros de apps com o registro de solicitações

Nos ambientes de execução de segunda geração, o campo protoPayload.line no registro de solicitação não contém registros de apps. A Análise de registros usa o campo trace para agrupar registros de solicitação e de apps. O pacote java.util.logging adiciona automaticamente o ID de trace a todos os registros de solicitações e de apps. Para visualizar registros correlacionados na Análise de registros, consulte Ver registros correlacionados.

Usar o Simple Logging Facade para Java (SLF4J)

O SLF4J é a interface de geração de registros mais usada em aplicativos Java. Sendo uma fachada, a interface SLF4J é independente da plataforma de seu back-end de registro, permitindo que você escolha qualquer back-end adequado para seus aplicativos.

A imagem abaixo mostra opções de integração para dois back-ends SLF4J, incluindo a biblioteca java.util.logging e o Logback appender:

Visão geral do SLF4J

SLF4J com pacote `java.util.logging`

O SLF4J permite integrar seu app ao Cloud Logging ao usar o SLF4J com java.util.logging como back-end de geração de registros. Por padrão, o App Engine adiciona um ID de trace a todos os registros de solicitações e aplicativos. Com esse mecanismo, é possível agrupar registros de solicitações e de apps na Análise de registros.

Para implementar o SLF4J com java.util.logging, siga estas etapas:

Adicione a dependência slf4j-jdk14.jar ao arquivo pom.xml. O arquivo slf4j-jdk14.jar fornece a integração de back-end para a biblioteca 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>

Crie um arquivo WEB-INF/logging.properties para adicionar configurações personalizadas:
```
com.example.appengine.java8.HelloAppEngine.level = INFO
```

Atualize o arquivo appengine-web.xml para incluir o valor <property> para WEB-INF/logging.properties:

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

A imagem a seguir mostra como o SLF4J com java.util.logging adiciona automaticamente o ID de rastreamento a um registro de app:

Agrupar registros de apps por solicitação com um ID de trace

Para ajustar a visualização da Análise de registros a uma visualização focada em solicitações, como o ambiente de execução de primeira geração, consulte Visualizar registros correlacionados.

Usar o SLF4J com o Logback appender

Se os apps de ambiente de execução de primeira geração usam a implementação integrada do SLF4J com o Logback, atualize o código-fonte e implemente outras etapas para agrupar os registros de app e solicitação.

Para integrar seu app ao Cloud Logging, siga estas etapas:

Adicione o google-cloud-logging-logback appender ao arquivo pom.xml para instalar o appender de geração de registros para 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>

Crie um otimizador de geração de registros para adicionar um ID de trace a cada campo LogEntry. A classe TraceIdLoggingEnhancer a seguir usa a API ApiProxy para recuperar o ID de trace associado a uma solicitação:

  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]

Adicione a configuração de appender do Cloud Logging ao arquivo logback.xml para definir o Logback. O framework de Logback gerencia a configuração por meio do arquivo logback.xml no 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>

A imagem a seguir mostra a estrutura final do diretório do app:

Estrutura do diretório

Mostrar registros correlacionados

É possível visualizar registros correlacionados na Análise de registros usando o campo "ID do trace" em cada entrada de registro. Para visualizar registros correlacionados na Análise de registros:

No painel de navegação do console do Google Cloud, selecione Logging e clique em Análise de registros:

Acessar o Explorador de registros
Em Tipo de recurso, selecione Aplicativo GAE.
Para visualizar e correlacionar registros de solicitações, em Nome do registro, selecione request_log. Como alternativa, para correlacionar por registros de solicitação, clique em Correlacionar por e selecione request_log.
No painel Resultados da consulta, clique em Expandir para expandir uma entrada de registro. Na expansão, cada registro de solicitação mostrará os registros de aplicativos associados.