Configura Cloud Logging para Java

Puedes escribir registros en Cloud Logging desde aplicaciones de Java mediante el adjuntador de Logback o un java.util.logging handler, o directamente mediante la biblioteca de Cloud Logging para Java.

No es necesario que el agente de Cloud Logging esté instalado a fin de usar la biblioteca de Cloud Logging para Java.

Antes de comenzar

Accede a tu Google Cloud cuenta de. Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

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 role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

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 role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

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

Adjuntador de Logback para Cloud Logging

Mediante el adjuntador de Logback, puedes usar Cloud Logging con la fachada de registro SLF4J.

Instala la dependencia

Si usas Maven, agrega lo siguiente al archivo pom.xml. Para obtener más información sobre las BOM, consulta Las bibliotecas de BOM de Google Cloud Platform.

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

Si usas Gradle, agrega lo siguiente a las dependencias:

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

Si usas sbt, agrega lo siguiente a las dependencias:

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

Configuración de Logback

Logback se puede configurar de manera programática o con una secuencia de comandos expresada en XML o Groovy.

Puedes personalizar el umbral de gravedad mínimo y el nombre de registro o proporcionar mejoras adicionales. Este es un ejemplo de configuración de Logback en 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>

Ejemplo

Después de configurar Logback para que use el adjuntador de Logback de Cloud Logging, puedes redireccionar los registros mediante la API de registro SLF4J. Proporciona Google Cloud configuración si planeas ejecutar el ejemplo de forma local o fuera de Google Cloud. En este fragmento, se muestra cómo realizar registros mediante la fachada SLF4J en tu aplicación:

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

El controlador java.util.logging

También puedes usar la API de Cloud Logging mediante un controlador predeterminado de la API de Logging para Java.

Instala la dependencia

Si usas Maven con una BOM, agrega lo siguiente a tu pom.xml archivo:

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

Si usas Maven sin una BOM, agrega esto a las dependencias:

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

Si usas Gradle, agrega lo siguiente a las dependencias:

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

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

Si usas sbt, agrega lo siguiente a las dependencias:

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

Si usas Visual Studio Code o IntelliJ, puedes agregar bibliotecas cliente a tu proyecto con los siguientes complementos IDE:

• Cloud Code para VS Code
• Cloud Code para IntelliJ

Los complementos brindan funcionalidades adicionales, como administración de claves para las cuentas de servicio. Consulta la documentación de cada complemento para obtener más detalles.

Nota: En este momento, las bibliotecas cliente de Cloud para Java no son compatibles con Android.

Configuración de java.util.logging

Los controladores de Logging se pueden agregar de manera programática o mediante un archivo de configuración. La ruta de acceso al archivo de configuración se debe proporcionar a tu aplicación como una propiedad del sistema:

  -Djava.util.logging.config.file=/path/to/logging.properties

A continuación, se muestra un ejemplo de un archivo de configuración:

# 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

Ejemplo

Proporciona Google Cloud configuración si planeas ejecutar el ejemplo de forma local o fuera de Google Cloud. En este fragmento, se muestra cómo realizar registros con 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");
  }
}

Configuración común

En las siguientes secciones, se describe la configuración que se suele usar en el controlador java.util.logging y el adjuntador de Logback para Cloud Logging.

Valores predeterminados

El adjuntador de Logback y el controlador java.util.logging usan los siguientes valores predeterminados para crear una instancia de un cliente de Cloud Logging:

• Nombre del registro: java.log

• Umbral mínimo para registrar: INFO

• Gravedad de limpieza: ERROR

La biblioteca de Cloud Logging para Java agrupa los mensajes en lotes por tamaño y hora desde la última escritura. Los lotes con solicitudes de registro que alcanzan o superan la gravedad de limpieza se escriben de inmediato.

Nota: Si usas directamente la API de la biblioteca de Cloud Logging para Java, no hay un nombre de registro predeterminado ni un límite mínimo.

Detección de recursos supervisados

Todos los registros enviados a través de las bibliotecas de Cloud Logging requieren un tipo de recurso supervisado para identificar tu aplicación.

El adjuntador de Logback y el controlador java.util.logging proporcionan detección automática del tipo de recurso de tus aplicaciones de App Engine, Compute Engine y Google Kubernetes Engine.

Un recurso supervisado global se usa como predeterminado en otros entornos.

Puedes reemplazar el tipo de recurso supervisado por un tipo válido en la Configuración del adjuntador de Logback o la java.util.logging Configuración del controlador.

**Nota:** Si usas directamente la API de Cloud Logging, debes proporcionar un tipo de recurso supervisado válido cuando realices registros mediante la API.

Campos y etiquetas adicionales

Con el adjuntador de Logback y el controlador java.util.logging, puedes agregar o actualizar campos en un objeto LogEntry con una instancia de LoggingEnhancer.

Los optimizadores deben configurarse como se muestra en la configuración del appender de Logback o en la java.util.logging configuración del handler:

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

Es posible que no se admita el uso de etiquetas personalizadas para tu configuración. Por ejemplo, los registros de Dataflow no incluyen estas etiquetas.

Si deseas obtener más información sobre la instalación, consulta la documentación de la biblioteca de Cloud Logging para Java. También puedes informar problemas con la Herramienta de seguimiento de errores.

Escribe registros con la biblioteca cliente de Cloud Logging

Si quieres obtener información sobre cómo usar la biblioteca cliente de Cloud Logging para Java directamente, consulta Bibliotecas cliente de Cloud Logging.

Ejecuta en Google Cloud

Para que una aplicación escriba registros con la biblioteca de Cloud Logging para Java, la cuenta de servicio del recurso subyacente debe tener la función de escritor de registros (roles/logging.logWriter) IAM. La mayoría de los Google Cloud entornos configuran automáticamente la cuenta de servicio predeterminada para que tenga esta función.

App Engine

Cloud Logging se habilita automáticamente para App Engine, y la cuenta de servicio predeterminada de tu app tiene los permisos de IAM de forma predeterminada para escribir entradas de registro.

De forma predeterminada, el entorno estándar de App Engine usa la API de java.util.logging.Logger, que escribe directamente en Cloud Logging y es fácil de configurar.

Para obtener más información, consulta la documentación de App Engine sobre cómo leer y escribir registros de aplicaciones.

Entorno flexible de App Engine

En el entorno flexible de App Engine, java.util.logging usa ConsoleHandler de forma predeterminada y envía registros a stdout y stderr.

El entorno de ejecución de Jetty se incluye en la biblioteca de Cloud Logging para Java.

El controlador java.util.logging se puede usar a fin de realizar registros directamente en Cloud Logging, para ello, proporciona logging.properties en tu app.yaml, como se muestra a continuación:

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

El registro de ID de seguimiento está disponible en los entornos de ejecución de Jetty si usas el controlador java.util.logging o el adjuntador de Logback.

Cuando se ejecuta en el entorno flexible de App Engine, una instancia de TraceLoggingEnhancer agrega un ID de seguimiento seguro para subprocesos a todas las entradas de registro con la etiqueta trace_id.

Google Kubernetes Engine (GKE)

GKE otorga automáticamente a la cuenta de servicio predeterminada la función de escritor de registros (roles/logging.logWriter) de IAM. Si usas Workload Identity Federation for GKE con esta cuenta de servicio predeterminada para permitir que las cargas de trabajo accedan a Google Cloud APIs específicas, no se requiere configuración adicional. Sin embargo, si usas Workload Identity Federation for GKE con una cuenta de servicio de IAM personalizada, asegúrate de que la cuenta de servicio personalizada tenga la función de escritor de registros (roles/logging.logWriter).

Si es necesario, también puedes usar el siguiente comando para agregar el permiso de acceso logging.write cuando creas el clúster:

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

Compute Engine

Nota: Si deseas usar la biblioteca de Cloud Logging para Java en una instancia de VM de Compute Engine, no es necesario que instales el agente de Cloud Logging.

Cuando uses las instancias de VM de Compute Engine, agrega el cloud-platform permiso de acceso a cada instancia. Si creas una instancia nueva a través de la Google Cloud consola, puedes hacerlo en la sección Identidad y acceso a la API del panel Crear Instancia. Usa la cuenta de servicio predeterminada de Compute Engine o una cuenta de servicio diferente y selecciona Permitir acceso total a las API de Cloud en la sección Identidad y acceso a la API. Asegúrate de que la cuenta de servicio que selecciones tenga la función de escritor de registros en la sección IAM y administración de la Google Cloud consola.

Ejecuta de forma local y en otros lugares

Si deseas usar la biblioteca de Cloud Logging para Java fuera de Google Cloud, incluida su ejecución en tu propia estación de trabajo, en las computadoras de tu centro de datos o en las instancias de VM de otro proveedor de servicios en la nube, debes configurar las credenciales predeterminadas de la aplicación (ADC) en tu entorno local para autenticarte en la biblioteca de Cloud Logging para Java.

Para obtener más información, consulta Configura ADC para un entorno local o con otro proveedor de servicios en la nube.

Consulta los registros

En la Google Cloud consola de, ve a la página Explorador de registros del segmento:

Ir al Explorador de registros

Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Logging.

En el Explorador de registros, debes especificar uno o más recursos, aunque la selección de recursos puede no ser obvia. Aquí encontrarás algunas sugerencias que te ayudarán a comenzar:

• Si implementas tu aplicación en App Engine o utilizas las bibliotecas específicas de App Engine, configura tu recurso como Aplicación de GAE.

• Si implementas tu aplicación en Compute Engine, configura el recurso como Instancia de VM de GCE.

• Si implementas tu aplicación en Google Kubernetes Engine, la configuración de registro de tu clúster determina el tipo de recurso de las entradas de registro. Para obtener información detallada sobre Google Cloud Observability heredado, las soluciones de Kubernetes Monitoring de Google Cloud Observability y cómo estas dos opciones afectan el tipo de recurso, consulta Migra a Kubernetes Monitoring de Google Cloud Observability.

• Si la aplicación usa la API de Cloud Logging directamente, el recurso depende de la API y de tu configuración. Por ejemplo, en la aplicación, puedes especificar un recurso o usar un recurso predeterminado.

• Si no ves ningún registro en el Explorador de registros, cambia al modo de consulta avanzada y usa una consulta vacía para ver todas las entradas de registro.

  1. Para cambiar al modo de consulta avanzada, haz clic en menú (▾) en la parte superior del visor de registros y selecciona Convertir a filtro avanzado.
  2. Borra el contenido que aparece en el cuadro de filtro.
  3. Haz clic en Enviar filtro.

  Puedes examinar las entradas individuales para identificar tus recursos.

Para obtener más información, consulta Usa el Explorador de registros.