Como configurar o Cloud Logging para Java

Grave registros no Stackdriver Logging pelos aplicativos em Java usando o Logback appender ou um gerenciador java.util.logging. Também é possível usar diretamente a biblioteca do Stackdriver Logging para Java.

O agente do Cloud Logging não precisa ser instalado para usar a biblioteca do Cloud Logging para Java.

Antes de começar

  1. Faça login na sua Conta do Google.

    Se você ainda não tiver uma, inscreva-se.

  2. No Console do Cloud, na página de seletor de projetos, selecione ou crie um projeto do Cloud.

    Acessar a página do seletor de projetos

  3. Verifique se a cobrança está ativada para o seu projeto do Google Cloud. Saiba como confirmar se a cobrança está ativada para o seu projeto.

  4. Ative Cloud Logging API.

    Ative a API

Logback appender para o Cloud Logging

Usando o Logback appender, você pode usar o Cloud Logging com a fachada de registro SLF4J.

Como instalar a dependência

Se você estiver usando o Maven, adicione isto ao arquivo pom.xml:

<dependencyManagement>
 <dependencies>
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>libraries-bom</artifactId>
    <version>3.0.0</version>
    <type>pom</type>
    <scope>import</scope>
   </dependency>
 </dependencies>
</dependencyManagement>

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

Se estiver usando o Gradle, adicione o seguinte às suas dependências:

compile 'com.google.cloud:google-cloud-logging-logback:0.116.0-alpha'

Se você estiver usando o sbt, adicione isto às dependências:

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

Configuração de Logback

O Logback pode ser configurado (em inglês) de maneira programática ou usando um script expresso em XML ou Groovy.

É possível personalizar o limite mínimo de gravidade, o nome do registro ou oferecer outros aprimoramentos. Esta é uma configuração de amostra do Logback no 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>

Exemplo

Depois de configurar o Logback para usar o Logback appender do Stackdriver Logging, redirecione os registros usando a API SLF4J Logging. Este snippet mostra como registrar com a fachada SLF4J dentro do seu aplicativo:


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

O gerenciador java.util.logging

Você também pode usar a API Stackdriver Logging utilizando um gerenciador (em inglês) padrão da API Java Logging.

Como instalar a dependência

Se você estiver usando o Maven com BOM, adicione isto ao arquivo pom.xml:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>5.3.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 você estiver usando o Maven sem BOM, adicione isto às dependências:

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

Se estiver usando o Gradle, adicione o seguinte às suas dependências:

compile 'com.google.cloud:google-cloud-logging:1.101.1'

Se você estiver usando o sbt, adicione isto às dependências:

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

Caso você esteja usando o IntelliJ ou o Eclipse, poderá adicionar bibliotecas de cliente ao seu projeto usando estes plug-ins de ambiente de desenvolvimento integrado:

Os plug-ins também oferecem outras funcionalidades, como gerenciamento de chaves de contas de serviço. Consulte a documentação de cada plug-in para mais detalhes.

Configuração do java.util.logging

Os gerenciadores de geração de registro podem ser adicionados programaticamente ou usando um arquivo de configuração. O caminho do arquivo de configuração precisa ser fornecido ao seu aplicativo como uma propriedade do sistema:-Djava.util.logging.config.file=/path/to/logging.properties

Veja um exemplo de um arquivo de configuração:

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

Exemplo

Veja como gerar registros com este snippet usando 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");
      }
    }

Configuração comum

As seções a seguir abordam a configuração comum ao manipulador java.util.logging e ao anexador de logback para o Cloud Logging.

Padrões

O manipulador de logback e o manipulador java.util.logging usam os seguintes padrões para instanciar um cliente do Cloud Logging:

  • Nome do registro: java.log

  • Limite mínimo para registrar: INFO

  • Gravidade da limpeza: ERROR

A biblioteca do Cloud Logging para Java envia lotes de mensagens por tamanho e hora desde a última gravação. Os lotes com solicitações de geração de registro em ou acima da gravidade de limpeza são gravados imediatamente.

Detecção de recursos monitorados

Todos os registros enviados por meio das bibliotecas do Cloud Logging exigem um tipo de recurso monitorado para identificar seu aplicativo.

O Logback appender e o gerenciador java.util.logging fornecem detecção automática do tipo de recurso de seus aplicativos App Engine, Compute Engine e Google Kubernetes Engine.

Um recurso monitorado global é usado como o padrão em outros ambientes.

É possível modificar o tipo de recurso monitorado para um tipo válido na Configuração do Logback appender ou na Configuração do gerenciador java.util.logging.

Outros campos e rótulos

Com o Logback appender e o gerenciador java.util.logging, é possível adicionar ou atualizar campos em um objeto LogEntry usando uma instância de LoggingEnhancer.

Os mecanismos de aprimoramento precisam ser configurados conforme mostrado na Configuração do Logback appender ou na Configuração do gerenciador 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");
      }
    }

Para mais informações sobre a instalação, consulte a documentação da biblioteca do Cloud Logging para Java. Além disso, use o rastreador de problemas (em inglês) para informá-los.

Como usar a biblioteca de cliente do Cloud diretamente

Para informações sobre como usar diretamente a biblioteca de cliente do Cloud Logging Cloud para Java, consulte Bibliotecas de cliente do Cloud Logging.

Como executar no Google Cloud

Usar a biblioteca do Cloud Logging para Java requer o papel de gravador de registros do Cloud IAM no Google Cloud. A maioria dos ambientes do Google Cloud fornece esse papel por padrão.

App Engine

O App Engine concede o papel de gravador de registros por padrão.

A biblioteca do Cloud Logging para Java pode ser usada sem a necessidade de fornecer credenciais explicitamente.

O Cloud Logging é ativado automaticamente para aplicativos do App Engine. Nenhuma outra configuração é necessária.

O ambiente padrão do App Engine, por padrão, usa a API java.util.logging.Logger; isso grava no Cloud Logging diretamente e é fácil de configurar.

Para mais detalhes, consulte a documentação do App Engine sobre como ler e gravar registros de aplicativos.

Ambiente flexível do App Engine

No ambiente flexível do App Engine, o java.util.logging usa o ConsoleHandler por padrão, e envia registros para stdout e stderr.

O ambiente de execução Jetty é fornecido com a biblioteca do Cloud Logging para Java.

O manipulador java.util.logging pode ser usado para fazer login diretamente no Cloud Logging, fornecendo o logging.properties no seu app.yaml, como mostrado aqui:

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

A geração de registros do código de trace está disponível nos ambientes de execução do Jetty, se você usa o gerenciador java.util.logging ou o Logback appender.

Quando gerada no ambiente flexível do App Engine, uma instância TraceLoggingEnhancer (em inglês) adiciona um código de trace seguro para thread a cada entrada de registro usando o rótulo trace_id.

Google Kubernetes Engine

No Google Kubernetes Engine, você precisa adicionar o escopo de acesso logging.write ao criar o cluster:

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

Compute Engine

Ao usar instâncias de VM do Compute Engine, adicione o escopo de acesso cloud-platform a cada instância. Ao criar uma nova instância por meio do Console do Google Cloud, é possível adicionar o escopo na seção Identidade e acesso à API do painel Criar instância. Use a conta de serviço padrão do Compute Engine ou outra de sua escolha e selecione Permitir acesso completo a todas as APIs do Cloud na seção Identidade e acesso à API. Independentemente da conta de serviço selecionada, verifique se ela recebeu o papel de gravador de registros na seção IAM e administrador do Console do Cloud.

Como executar localmente e em outro lugar

Para usar a biblioteca do Cloud Logging para Java fora do Google Cloud (incluindo a execução da biblioteca na sua própria estação de trabalho, nos computadores do seu centro de dados ou nas instâncias de VM de outro provedor de nuvem), forneça o código do projeto do Google Cloud e as credenciais da conta de serviço apropriada diretamente para a biblioteca do Cloud Logging para Java.

É possível criar e receber credenciais da conta de serviço manualmente. Ao especificar o campo Papel, use o papel de gravador de registros. Para mais informações sobre os papéis do Cloud Identity and Access Management, veja o Guia de controle de acesso.

Como visualizar os registros

Após a implantação, é possível usar o visualizador de registros do Console do Cloud.

Acessar o visualizador de registros

No visualizador de registros, é preciso especificar um ou mais recursos, mas a escolha de recursos pode não ser óbvia. Veja a seguir algumas dicas para ajudar você a começar:

  • Se você estiver implantando seu aplicativo no App Engine ou usando as bibliotecas específicas dele, defina seu recurso como Aplicativo do GAE.

  • Se você estiver implantando seu aplicativo no Compute Engine, defina o recurso como Instância da VM do GCE.

  • Se você estiver implantando seu aplicativo no Google Kubernetes Engine, a configuração de geração de registros do cluster determinará o tipo de recurso das entradas de registro. Para uma discussão detalhada sobre o pacote operacional do Legacy Google Cloud e as soluções Kubernetes Monitoring do conjunto de operações do Google Cloud e como essas opções afetam o tipo de recurso, consulte Como migrar para o conjunto de operações Kubernetes Monitoring do Google Cloud.

  • Se seu aplicativo estiver usando a API Cloud Logging diretamente, o recurso dependerá da API e da configuração. Por exemplo, no seu aplicativo, é possível especificar um recurso ou usar um que seja padrão.

  • Se você não vir registros no visualizador, para ver todas as entradas, alterne para o modo de consulta avançada e use uma consulta vazia.

    1. Para alternar para o modo de consulta avançada, clique no menu (&blacktriangledown;) na parte superior do visualizador de registros e selecione Converter para filtro avançado.
    2. Limpe o conteúdo que aparece na caixa de filtro.
    3. Clique em Enviar filtro.

    É possível examinar as entradas individuais para identificar seus recursos.

Para mais informações, consulte Como visualizar registros e Consultas avançadas de registros.