Esta página foi traduzida pela API Cloud Translation.

Configurar o Cloud Logging para Java

Pode escrever registos no Cloud Logging a partir de aplicações Java através do anexador Logback ou de um java.util.logging handler, ou usando diretamente a biblioteca Cloud Logging para Java.

Não tem de instalar o agente do Cloud Logging para usar a biblioteca do Cloud Logging para Java.

Antes de começar

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Logging API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Logging API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Anexador do Logback para o Cloud Logging

Com o appender Logback, pode usar o Cloud Logging com a fachada de registo SLF4J.

Instalar a dependência

If you are using Maven, add the following to your pom.xml file. For more information about BOMs, see The Google Cloud Platform Libraries BOM.

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

If you are using Gradle, add the following to your dependencies:

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

If you are using sbt, add the following to your dependencies:

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

Configuração do Logback

O Logback pode ser configurado programaticamente ou através de um script expresso em XML ou Groovy.

Pode personalizar o limite mínimo de gravidade, o nome do registo ou fornecer melhoramentos adicionais. Segue-se um exemplo de configuração 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 appender Logback do Cloud Logging, já pode redirecionar os registos através da API de registo SLF4J. Forneça a Google Cloud configuração se planear executar o exemplo localmente ou fora do Google Cloud. Este fragmento mostra como registar através da fachada SLF4J na sua aplicação:


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 controlador java.util.logging

processador

Instalar a dependência

If you are using Maven with a BOM, add the following to your pom.xml file:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>26.55.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>

If you are using Maven without a BOM, add this to your dependencies:

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

If you are using Gradle, add the following to your dependencies:

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

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

If you are using sbt, add the following to your dependencies:

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

If you're using Visual Studio Code, IntelliJ, or Eclipse, you can add client libraries to your project using the following IDE plugins:

The plugins provide additional functionality, such as key management for service accounts. Refer to each plugin's documentation for details.

Configuração java.util.logging

Os controladores de registo podem ser adicionados programaticamente ou através de um ficheiro de configuração. O caminho para o ficheiro de configuração tem de ser fornecido à sua aplicação como uma propriedade do sistema: -Djava.util.logging.config.file=/path/to/logging.properties

Segue-se um exemplo de um ficheiro 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 Google Cloud configuração se planear executar o exemplo localmente ou fora do Google Cloud. Este fragmento mostra como registar através de 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 secções seguintes abordam a configuração comum ao controlador java.util.logging e ao anexador Logback para o Cloud Logging.

Predefinições

O appender Logback e o controlador java.util.logging usam as seguintes predefinições para instanciar um cliente do Cloud Logging:

Nome do registo : java.log
Limite mínimo para registo : INFO
Gravidade da descarga : ERROR

A biblioteca Cloud Logging para Java agrupa as mensagens por tamanho e tempo desde a última gravação. Os lotes com pedidos de registo no nível de gravidade de descarga ou superior são escritos imediatamente.

Deteção de recursos monitorizados

Todos os registos enviados através das bibliotecas do Cloud Logging requerem um tipo de recurso monitorizado para identificar a sua aplicação.

O Appender Logback e o controlador java.util.logging fornecem a deteção automática do tipo de recurso das suas aplicações do App Engine, Compute Engine e Google Kubernetes Engine.

Um recurso monitorizado global é usado como predefinição noutros ambientes.

Pode substituir o tipo de recurso monitorizado por um tipo válido na configuração do anexo Logback ou na java.util.logging configuração do controlador.

Campos e etiquetas adicionais

Com o appender Logback e o controlador java.util.logging, pode adicionar ou atualizar campos num objeto LogEntry através de uma instância de LoggingEnhancer.

Os melhoramentos têm de ser configurados conforme mostrado na configuração do anexo Logback ou na java.util.logging configuração do controlador:


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

A utilização de etiquetas personalizadas pode não ser suportada para a sua configuração. Por exemplo, os registos do Dataflow não incluem estas etiquetas.

Para mais informações sobre a instalação, consulte a documentação da biblioteca Cloud Logging para Java. Também pode comunicar problemas através do relatório de erros.

Escreva registos com a biblioteca de cliente do Cloud Logging

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

Executar em Google Cloud

Para que uma aplicação escreva registos através da biblioteca Cloud Logging para Java, a conta de serviço do recurso subjacente tem de ter a função Logs Writer (roles/logging.logWriter) do IAM. A maioria dos Google Cloud ambientes configura automaticamente a conta de serviço predefinida para ter esta função.

App Engine

O Cloud Logging é ativado automaticamente para o App Engine, e a conta de serviço predefinida da sua app tem as autorizações de IAM predefinidas para escrever entradas de registo.

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

Para mais detalhes, consulte a documentação do App Engine sobre como ler e escrever registos de aplicações.

Ambiente flexível do App Engine

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

O tempo de execução do Jetty está incluído na biblioteca do Cloud Logging para Java.

O controlador java.util.logging pode ser usado para registar diretamente no Cloud Logging, fornecendo o logging.properties no seu app.yaml conforme mostrado aqui:

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

O registo do ID de rastreio está disponível em tempos de execução do Jetty se estiver a usar o controlador java.util.logging ou o anexador Logback.

Quando executada no ambiente flexível do App Engine, uma instância de TraceLoggingEnhancer adiciona um ID de rastreio seguro para threads a cada entrada de registo através da etiqueta trace_id.

Google Kubernetes Engine (GKE)

O GKE concede automaticamente à conta de serviço predefinida a função do IAM Logs Writer (roles/logging.logWriter). Se usar a Workload Identity Federation para o GKE com esta conta de serviço predefinida para permitir que as cargas de trabalho acedam a Google Cloud APIs específicas, não é necessária nenhuma configuração adicional. No entanto, se usar a Workload Identity Federation para o GKE com uma conta de serviço do IAM personalizada, certifique-se de que a conta de serviço personalizada tem a função de escritor de registos (roles/logging.logWriter).

Se necessário, também pode usar o seguinte comando para adicionar o logging.write âmbito de acesso 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 cloud-platform âmbito de acesso a cada instância. Quando cria uma nova instância através da Google Cloud consola, pode fazê-lo na secção Identidade e acesso à API do painel Criar instância. Use a conta de serviço predefinida do Compute Engine ou outra conta de serviço à sua escolha e selecione Permitir acesso total a todas as APIs Cloud na secção Identidade e acesso à API. Qualquer que seja a conta de serviço que selecionar, certifique-se de que lhe foi concedida a função Logs Writer na secção IAM e administrador daGoogle Cloud consola.

Executar localmente e noutro local

Para usar a biblioteca 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 fornecedor de nuvem, tem de configurar as Credenciais predefinidas da aplicação (ADC) no seu ambiente local para autenticar na biblioteca Cloud Logging para Java.

Para mais informações, consulte o artigo Configure o ADC para um ambiente no local ou outro fornecedor de nuvem.

Ver os registos

Na Google Cloud consola, aceda à página Explorador de registos:

Aceda ao Explorador de registos

Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cuja legenda é Registo.

No Explorador de registos, tem de especificar um ou mais recursos, mas a seleção de recursos pode não ser óbvia. Seguem-se algumas sugestões para ajudar a começar:

Se estiver a implementar a sua aplicação no App Engine ou a usar as bibliotecas específicas do App Engine, defina o seu recurso como Aplicação GAE.
Se estiver a implementar a sua aplicação no Compute Engine, defina o recurso como GCE VM Instance.
Se estiver a implementar a sua aplicação no Google Kubernetes Engine, a configuração de registo do cluster determina o tipo de recurso das entradas de registo. Para uma discussão detalhada sobre o Google Cloud Observability antigo e as soluções de monitorização do Kubernetes do Google Cloud Observability, e como essas opções afetam o tipo de recurso, consulte o artigo Migrar para a monitorização do Kubernetes do Google Cloud Observability.
Se a sua aplicação estiver a usar a API Cloud Logging diretamente, o recurso depende da API e da sua configuração. Por exemplo, na sua aplicação, pode especificar um recurso ou usar um recurso predefinido.
Se não vir registos no Explorador de registos, para ver todas as entradas de registo, mude para o modo de consulta avançado e use uma consulta vazia.
1. Para mudar para o modo de consulta avançado, clique no menu (&blacktriangledown;) na parte superior do Explorador de registos e, em seguida, selecione Converter em filtro avançado.
2. Limpar o conteúdo apresentado na caixa de filtro.
3. Clique em Enviar filtro.
Pode examinar as entradas individuais para identificar os seus recursos.

Para mais informações, consulte o artigo Usar o Explorador de registos.

Configurar o Cloud Logging para Java Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Anexador do Logback para o Cloud Logging

Instalar a dependência

Configuração do Logback

Exemplo

O controlador java.util.logging

Instalar a dependência

Configuração java.util.logging

Exemplo

Configuração comum

Predefinições

Deteção de recursos monitorizados

Campos e etiquetas adicionais

Escreva registos com a biblioteca de cliente do Cloud Logging

Executar em Google Cloud

App Engine

Ambiente flexível do App Engine

Google Kubernetes Engine (GKE)

Compute Engine

Executar localmente e noutro local

Ver os registos

Configurar o Cloud Logging para Java