Como configurar o Cloud Logging para Java

É possível gravar registros no Cloud Logging de aplicativos em Java usando o Logback appender ou um java.util.logging handler. Também é possível usar a biblioteca do Cloud Logging para Java diretamente.

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 Cloud. Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

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

   Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

   Acessar o seletor de projetos

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

4. Ative a Cloud Logging API.

   Ative a API

5. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

   Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

   Acessar o seletor de projetos

6. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

7. Ative a Cloud Logging API.

   Ative a API

Ao usar o Logback appender (em inglês), é possível usar o Cloud 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 o código abaixo ao arquivo pom.xml. Para mais informações sobre BOMs, consulte BOM das bibliotecas do Google Cloud Platform.

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

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

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

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

libraryDependencies += "com.google.cloud" % "google-cloud-logging-logback" % "0.131.4-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 app Logback do Cloud Logging, use a API SLF4J Logging para redirecionar os registros. Forneça a configuração do Google Cloud se você quiser executar o exemplo localmente ou fora do Google Cloud. Este snippet mostra como registrar usando a fachada SLF4J no 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

Também é possível usar a API Cloud Logging com um gerenciador 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>26.34.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>3.16.1</version>
</dependency>

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

implementation platform('com.google.cloud:libraries-bom:26.34.0')

implementation 'com.google.cloud:google-cloud-logging'

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

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

Se você estiver usando o Visual Studio Code, o IntelliJ ou o Eclipse, poderá adicionar bibliotecas de cliente ao projeto usando estes plug-ins de IDE:

• Cloud Code para VS Code
• Cloud Code para IntelliJ
• Cloud Tools for Eclipse

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.

Observação: as bibliotecas de cliente Java para Google Cloud atualmente não são compatíveis com Android.

java.util.logging configuration

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

Exemplo

Forneça a configuração do Google Cloud se você quiser executar o exemplo localmente ou fora do Google Cloud. 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 gerenciador java.util.logging e ao Logback appender para Cloud Logging.

Padrões

O gerenciador java.util.logging e o Logback appender 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 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.

Observação :se você estiver usando diretamente a biblioteca do Cloud Logging para a API Java, não haverá nome de registro padrão ou limite mínimo.

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.

Observação: se você estiver usando diretamente a API Cloud Logging, será preciso fornecer um tipo de recurso monitorado válido ao gerar registros usando a API.

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

O uso de rótulos personalizados pode não ser compatível com sua configuração. Por exemplo, os registros do Dataflow não incluem esses rótulos.

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

Gravar registros com a biblioteca de cliente do Cloud Logging

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

Executar no Google Cloud

Para que um aplicativo grave registros usando a biblioteca do Cloud Logging para Java, a conta de serviço do recurso subjacente precisa ter o papel de Gravador de registros (roles/logging.logWriter) do IAM. A maioria dos ambientes do Google Cloud configura automaticamente a conta de serviço padrão para ter esse papel.

App Engine

O Cloud Logging é ativado automaticamente para o App Engine, e a conta de serviço padrão do aplicativo tem as permissões do IAM por padrão para gravar entradas de registro.

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 gerenciador java.util.logging pode ser usado para gerar registros diretamente no Cloud Logging, fornecendo o logging.properties no 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 executada no ambiente flexível do App Engine, uma instância TraceLoggingEnhancer adiciona um ID de rastreamento thread-safe a cada entrada de registro usando o rótulo trace_id.

Google Kubernetes Engine (GKE)

O GKE concede automaticamente à conta de serviço padrão o papel do IAM de Gravador de registros (roles/logging.logWriter). Se você usar a Identidade da carga de trabalho com essa conta de serviço padrão para permitir que as cargas de trabalho acessem APIs específicas do Google Cloud, nenhuma outra configuração será necessária. No entanto, se você usar a Identidade da carga de trabalho com uma conta de serviço do IAM personalizada, verifique se essa conta tem o papel de Gravador de registros (roles/logging.logWriter).

Se necessário, também é possível usar o seguinte comando para 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

Observação: para usar a biblioteca do Cloud Logging para Java em uma instância de VM do Compute Engine, não é necessário instalar o agente do Cloud Logging.

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, faça isso 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. Seja qual for a conta de serviço selecionada, verifique se ela recebeu o papel de gravador de registros na seção IAM e administrador do console do Google Cloud.

Execute 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 data center ou nas instâncias de VM de outro provedor de nuvem, forneça o ID do projeto do Google Cloud e as credenciais da conta de serviço apropriadas diretamente à biblioteca do Cloud Logging para Java.

Para contas de serviço atuais, faça o seguinte:

1. Conceda à conta de serviço o papel do IAM Gravador de registros (roles/logging.logWriter). Para mais informações sobre os papéis do IAM, consulte Controle de acesso.

2. Configurar o Application Default Credentials

Se você não tiver uma conta de serviço, crie uma. Para mais informações sobre esse processo, consulte Criar contas de serviço.

Para informações gerais sobre os métodos que podem ser usados para autenticação, consulte Terminologia: contas de serviço.

Visualize os registros

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

Acessar a Análise de registros

No Explorador de registros, é preciso especificar um ou mais recursos, mas a escolha deles 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 de observabilidade legada do Google Cloud e do Kubernetes Monitoring do Google Cloud e como essas opções afetam o tipo de recurso, consulte Como migrar para o Kubernetes Monitoring de observabilidade do Google Cloud.

• Se o 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 recurso padrão.

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

  1. Se quiser alternar para o modo de consulta avançada, clique no menu (▾) na parte superior do Explorador 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, acesse Como usar a Análise de registros.