Como configurar o Stackdriver 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.

Não é necessário instalar o agente do Stackdriver Logging para usar a biblioteca do Stackdriver 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. Selecione ou crie um projeto do GCP.

    Acessar a página Gerenciar recursos

  3. Verifique se o faturamento foi ativado para o projeto.

    Saiba como ativar o faturamento

  4. Ativar Stackdriver Logging API.

    Ativar a API

Logback appender para Stackdriver Logging

Com o Logback (em inglês) appender, use o Stackdriver Logging com a fachada de geração de registros SLF4J (em inglês).

Como instalar a dependência

Se você estiver usando o Maven, adicione ao seu arquivo pom.xml:
<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-logging-logback</artifactId>
  <version>0.79.0-alpha</version>
</dependency>
Se você estiver usando o Gradle, adicione às suas dependências:
compile 'com.google.cloud:google-cloud-logging-logback:0.79.0-alpha'
Se você estiver usando o SBT, adicione às suas dependências:
libraryDependencies += "com.google.cloud" % "google-cloud-logging-logback" % "0.79.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.

Você pode 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, adicione ao seu arquivo pom.xml:
<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-logging</artifactId>
  <version>1.61.0</version>
</dependency>
Se você estiver usando o Gradle, adicione às suas dependências:
compile 'com.google.cloud:google-cloud-logging:1.61.0'
Se você estiver usando o SBT, adicione às suas dependências:
libraryDependencies += "com.google.cloud" % "google-cloud-logging" % "1.61.0"

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 da geração de registros podem ser adicionados programaticamente ou usando um arquivo de configuração. O caminho para o arquivo de configuração precisa ser fornecido para o 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

Nas seções a seguir, é abordada a configuração que é comum ao gerenciador java.util.logging e ao Logback appender para Stackdriver Logging.

Padrões

O Logback appender e o gerenciador java.util.logging usam os seguintes padrões para instanciar um cliente do Stackdriver Logging:

  • Nome do registro: java.log

  • Limite mínimo para registrar: INFO

  • Gravidade da limpeza: ERROR

A biblioteca do Stackdriver Logging para Java armazena mensagens em lotes 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 Stackdriver Logging exigem um tipo de recurso monitorado para identificar o aplicativo.

A detecção automática do tipo de recurso de aplicativos do App Engine, Compute Engine e Google Kubernetes Engine é fornecida pelo Logback appender e pelo gerenciador java.util.logging.

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

Para adicionar ou atualizar campos em um objeto LogEntry usando uma instância de LoggingEnhancer (ambos os links em inglês), use o Logback appender e o gerenciador java.util.logging.

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 saber mais informações sobre a instalação, consulte a documentação (em inglês) da biblioteca do Stackdriver 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 a biblioteca de cliente do Cloud do Stackdriver Logging para Go diretamente, consulte Bibliotecas de cliente do Stackdriver Logging.

Como executar no Google Cloud Platform

O uso da biblioteca do Stackdriver Logging para Java exige o papel Gravador de registros do Cloud IAM no GCP. A maioria dos ambientes do GCP oferece esse papel por padrão.

App Engine

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

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

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

O ambiente padrão do App Engine usa, por padrão, a API java.util.logging.Logger (em inglês). Com isso, a gravação é feita diretamente no Stackdriver Logging 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 (em inglês) por padrão e envia os registros para stdout e stderr.

O ambiente de execução do Jetty acompanha a biblioteca do Stackdriver Logging para Java.

O gerenciador java.util.logging pode ser usado para gerar registros diretamente no Stackdriver Logging, inserindo o logging.properties no app.yaml, conforme 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, adicione 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

Quando 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 Platform, faça isso na seção de 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 total a todas as APIs do Cloud na seção Identidade e acesso à API. Seja qual for a conta de serviço selecionada, verifique se o papel Gravador de registros foi concedido na seção IAM e administrador do Console do GCP.

Como executar localmente e em outro local

Para usar a biblioteca do Stackdriver Logging para Java fora do GCP, você precisa fornecer seu ID de projeto do GCP e as credenciais da conta de serviço apropriadas diretamente à biblioteca do Stackdriver Logging para Java. Isso se aplica à execução do agente na própria estação de trabalho, nos computadores do data center ou nas instâncias de VM de outro provedor de nuvem. Para mais informações, consulte Como receber e fornecer credenciais da conta de serviço manualmente.

Como visualizar os registros

Após a implantação, você pode consultar os registros no visualizador de registros do Console do GCP.

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 de 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 ver uma discussão detalhada sobre as soluções do Stackdriver legado e do Stackdriver Kubernetes Monitoring e como essas opções afetam o tipo de recurso, consulte Como migrar para o Kubernetes Monitoring.

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

  • Caso você não veja nenhum registro no Visualizador de registros, para ver todas as entradas de registro, alterne para o modo de filtro avançado e use um filtro vazio.

    1. Para alternar para o modo de filtro avançado, 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 Filtros de registro avançados.

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Stackdriver Logging
Precisa de ajuda? Acesse nossa página de suporte.