Configuration de Cloud Logging pour Java

Vous pouvez écrire des journaux dans Cloud Logging depuis des applications Java grâce à l'appender Logback, à un gestionnaire java.util.logging, ou en utilisant directement la bibliothèque Cloud Logging pour Java.

Il n'est pas nécessaire d'installer l'agent Cloud Logging pour utiliser la bibliothèque Cloud Logging pour Java.

Avant de commencer

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

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

   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

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the Cloud Logging API.

   Enable the API

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

   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

6. Make sure that billing is enabled for your Google Cloud project.

7. Enable the Cloud Logging API.

   Enable the API

Appender Logback pour Cloud Logging

L'appender Logback permet d'utiliser Cloud Logging avec la façade de journalisation SLF4J.

Installer la dépendance

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"

Configuration de Logback

Logback peut être configuré par programmation ou à l'aide d'un script exprimé en XML ou Groovy.

Vous pouvez personnaliser le seuil de gravité minimal, le nom du journal ou fournir des outils d'amélioration supplémentaires. Voici un exemple de configuration de Logback au format 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>

Exemple

Une fois Logback configuré pour utiliser l'appender Cloud Logging Logback, vous pouvez rediriger les journaux à l'aide de l'API de journalisation SLF4J. Fournissez la configuration Google Cloud si vous envisagez d'exécuter l'exemple en local ou en dehors de Google Cloud. L'extrait de code ci-dessous vous montre comment effectuer la journalisation avec la façade SLF4J au sein de votre application :

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

Gestionnaire java.util.logging

Vous pouvez également utiliser l'API Cloud Logging à l'aide d'un gestionnaire d'API de journalisation Java par défaut.

Installer la dépendance

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.43.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.17.2</version>
</dependency>

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

implementation platform('com.google.cloud:libraries-bom:26.50.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.20.7"

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

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

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

Note: Cloud Java client libraries do not currently support Android.

Configurer java.util.logging

Les gestionnaires de journalisation peuvent être ajoutés de manière automatisée ou à partir d'un fichier de configuration. Le chemin d'accès au fichier de configuration doit être fourni à votre application en tant que propriété système : -Djava.util.logging.config.file=/path/to/logging.properties

Voici un exemple de fichier de configuration:

# 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

Exemple

Fournissez la configuration Google Cloud si vous envisagez d'exécuter l'exemple en local ou en dehors de Google Cloud. Cet extrait montre comment effectuer la journalisation à l'aide du gestionnaire 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");
  }
}

Configuration commune

Les sections suivantes décrivent la configuration commune au gestionnaire java.util.logging et à l'appender Logback pour Cloud Logging.

Valeurs par défaut

L'appender Logback et le gestionnaire java.util.logging instancient un client Cloud Logging en utilisant les valeurs par défaut suivantes :

• Nom du journal : java.log

• Seuil minimal à consigner : INFO

• Niveau de gravité du vidage : ERROR

La bibliothèque Cloud Logging pour Java regroupe les messages par taille et en fonction du temps écoulé depuis la dernière opération d'écriture. Les lots qui contiennent des requêtes de journalisation dont le niveau de gravité est supérieur ou égal au niveau indiqué sont immédiatement rédigés.

Remarque : Si vous utilisez directement la bibliothèque Cloud Logging pour l'API Java, il n'y a pas de nom de journal ni de seuil minimal par défaut.

Détection de ressources surveillées

Tous les journaux envoyés via les bibliothèques Cloud Logging nécessitent un type de ressource surveillée afin d'identifier votre application.

L'appender Logback et le gestionnaire java.util.logging détectent automatiquement le type de ressource de vos applications App Engine, Compute Engine et Google Kubernetes Engine.

Dans les autres environnements, une ressource surveillée de type global est utilisée par défaut.

Vous pouvez remplacer le type de ressource surveillée par un type valide dans la configuration de l'appender Logback ou dans la configuration du gestionnaire java.util.logging.

Remarque : Si vous utilisez directement l'API Cloud Logging, vous devez fournir un type de ressource surveillée valide lors de la journalisation avec l'API.

Champs et étiquettes supplémentaires

L'appender Logback et le gestionnaire java.util.logging permettent d'ajouter ou de mettre à jour des champs d'un objet LogEntry en utilisant une instance LoggingEnhancer.

Les outils d'amélioration doivent être configurés comme indiqué dans la configuration de l'appender Logback ou dans la configuration du gestionnaire 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");
  }
}

L'utilisation de libellés personnalisés peut ne pas être compatible avec votre configuration. Par exemple, les journaux Dataflow n'incluent pas ces libellés.

Pour plus d'informations sur l'installation, consultez la documentation de la bibliothèque Cloud Logging pour Java. Vous pouvez également signaler d'éventuels problèmes à l'aide de l'outil de suivi des problèmes.

Écrire des journaux avec la bibliothèque cliente Cloud Logging

Pour plus d'informations sur l'utilisation directe de la bibliothèque cliente Cloud Logging pour Java, consultez la documentation Bibliothèques clientes Cloud Logging.

Exécuter sur Google Cloud

Pour qu'une application puisse écrire des journaux à l'aide de la bibliothèque Cloud Logging pour Java, le compte de service de la ressource sous-jacente doit disposer du rôle IAM Rédacteur de journaux (roles/logging.logWriter). La plupart des environnements Google Cloud configurent automatiquement le compte de service par défaut avec ce rôle.

App Engine

Cloud Logging est automatiquement activé pour App Engine et le compte de service par défaut de votre application dispose des autorisations IAM par défaut permettant d'écrire des entrées de journal.

L'environnement standard App Engine utilise par défaut l'API java.util.logging.Logger, qui écrit directement dans Cloud Logging et est facile à configurer.

Pour en savoir plus, reportez-vous à la documentation App Engine sur la lecture et l'écriture de journaux d'application.

Environnement flexible App Engine

Dans l'environnement flexible App Engine, java.util.logging utilise ConsoleHandler par défaut et envoie les journaux à stdout et stderr.

L'environnement d'exécution Jetty comprend la bibliothèque Cloud Logging pour Java.

Le gestionnaire java.util.logging peut être utilisé pour envoyer directement les journaux dans Cloud Logging en fournissant le champ logging.properties dans votre fichier app.yaml, comme illustré ci-dessous :

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

Le gestionnaire java.util.logging et l'appender Logback permettent la journalisation de l'ID de trace dans les environnements d'exécution Jetty.

En cas d'exécution dans l'environnement flexible App Engine, une instance TraceLoggingEnhancer ajoute un ID de trace sécurisé à chaque entrée de journal avec le libellé trace_id.

Google Kubernetes Engine (GKE)

GKE attribue automatiquement au compte de service par défaut le rôle IAM Rédacteur de journaux (roles/logging.logWriter). Si vous utilisez Workload Identity Federation for GKE avec ce compte de service par défaut pour autoriser les charges de travail à accéder à des API Google Cloud spécifiques, aucune configuration supplémentaire n'est requise. Toutefois, si vous utilisez la fédération d'identité de charge de travail pour GKE avec un compte de service IAM personnalisé, assurez-vous que le compte de service personnalisé dispose du rôle Écrivain de journaux (roles/logging.logWriter).

Si nécessaire, vous pouvez également utiliser la commande suivante pour ajouter le niveau d'accès logging.write lors de la création du cluster :

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

Compute Engine

Remarque : Pour utiliser la bibliothèque Cloud Logging pour Java sur une instance de VM Compute Engine, il n'est pas nécessaire d'installer l'agent Cloud Logging.

Lorsque vous utilisez des instances de VM Compute Engine, ajoutez le niveau d'accès cloud-platform à chaque instance. Lorsque vous créez une instance via la console Google Cloud, vous pouvez le faire dans la section Identité et accès à l'API du panneau Créer une instance. Utilisez le compte de service par défaut de Compute Engine ou un autre compte de service de votre choix, puis sélectionnez Autoriser l'accès complet à l'ensemble des API Cloud dans la section Identité et accès à l'API. Quel que soit le compte de service sélectionné, vérifiez qu'il dispose du rôle Rédacteur de journaux dans la section IAM et administration de la console Google Cloud.

Exécuter en local et depuis un autre emplacement

Pour utiliser la bibliothèque Cloud Logging pour Java en dehors de Google Cloud, y compris pour exécuter la bibliothèque sur votre propre poste de travail, sur les ordinateurs de votre centre de données ou sur les instances de VM d'un autre fournisseur de cloud, vous devez fournir l'ID de votre projet Google Cloud et les identifiants appropriés du compte de service directement dans la bibliothèque Cloud Logging pour Java.

Pour les comptes de service existants, procédez comme suit:

1. Attribuez au compte de service le rôle IAM Rédacteur de journaux (roles/logging.logWriter). Pour en savoir plus sur les rôles IAM, consultez la section Contrôle des accès.

2. Configurez les identifiants par défaut de l'application.

Si vous ne disposez pas d'un compte de service, créez-en un. Pour en savoir plus sur ce processus, consultez la section Créer des comptes de service.

Pour obtenir des informations générales sur les méthodes que vous pouvez utiliser pour vous authentifier, consultez la section Terminologie: comptes de service.

Afficher les journaux

Dans la console Google Cloud, accédez à la page Explorateur de journaux.

Accéder à l'explorateur de journaux

Si vous utilisez la barre de recherche pour trouver cette page, sélectionnez le résultat dont le sous-titre est Logging.

Dans l'explorateur de journaux, vous devez spécifier une ou plusieurs ressources, mais leur sélection peut ne pas être évidente. Voici quelques conseils pour vous aider à faire vos premiers pas :

• Si vous déployez votre application sur App Engine ou utilisez les bibliothèques propres à App Engine, définissez votre ressource sur Application GAE.

• Si vous déployez votre application sur Compute Engine, définissez la ressource sur Instance de VM GCE.

• Si vous déployez votre application sur Google Kubernetes Engine, la configuration de la journalisation de votre cluster détermine le type de ressource des entrées de journal. Pour en savoir plus sur l'ancienne solution Google Cloud Observability et sur les solutions Kubernetes Monitoring de Google Cloud Observability, ainsi que sur l'incidence de ces options sur le type de ressource, consultez la page Migrer vers Kubernetes Monitoring de Google Cloud Observability.

• Si votre application utilise directement l'API Cloud Logging, la ressource dépend de l'API et de votre configuration. Par exemple, dans votre application, vous pouvez spécifier une ressource ou utiliser une ressource par défaut.

• Si aucun journal ne s'affiche dans l'explorateur de journaux, passez en mode de requête avancée et utilisez une requête vide pour voir toutes les entrées de journal.

  1. Pour passer en mode de requête avancée, cliquez sur le menu (▾) en haut de l'explorateur de journaux, puis sélectionnez Convertir en filtre avancé.
  2. Effacez le contenu qui apparaît dans le champ de filtre.
  3. Cliquez sur Envoyer le filtre.

  Vous pouvez examiner les entrées individuelles pour identifier vos ressources.

Pour en savoir plus, consultez la page Utiliser l'explorateur de journaux.