Configurer Stackdriver Logging pour Java

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

Vous n'avez pas besoin d'installer l'agent Stackdriver Logging pour utiliser la bibliothèque Stackdriver Logging pour Java.

Avant de commencer

1. Connectez-vous à votre compte Google.

   Si vous n'en possédez pas déjà un, vous devez en créer un.

2. Sélectionnez ou créez un projet Google Cloud Platform.

   Remarque : Si vous ne prévoyez pas de conserver les ressources créées au cours de cette procédure, créez un projet au lieu de sélectionner un projet existant. Après avoir suivi ces étapes, vous pouvez supprimer le projet en supprimant toutes les ressources qui lui sont associées.

   Accéder à la page "Gérer les ressources"

3. Assurez-vous que la facturation est activée pour votre projet Google Cloud Platform.

   Découvrir comment activer la facturation

4. Activez API Stackdriver Logging.

   Activer l'API.

Appender Logback pour Stackdriver Logging

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

Installer la dépendance

Si vous utilisez Maven, ajoutez les lignes suivantes à votre fichier pom.xml :

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

Si vous utilisez Gradle, ajoutez les lignes suivantes à vos dépendances :

compile 'com.google.cloud:google-cloud-logging-logback:0.79.0-alpha'

Si vous utilisez SBT, ajoutez les lignes suivantes à vos dépendances :

libraryDependencies += "com.google.cloud" % "google-cloud-logging-logback" % "0.79.0-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 :

Afficher sur GitHub Commentaires

<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 Stackdriver Logging Logback, vous pouvez rediriger les journaux à l'aide de l'API de journalisation SLF4J. Cet extrait vous montre comment effectuer la journalisation à l'aide de la façade SLF4J dans votre application :

Afficher sur GitHub Commentaires

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 Stackdriver Logging à l'aide d'un gestionnaire d'API de journalisation Java par défaut.

Installer la dépendance

Si vous utilisez Maven, ajoutez les lignes suivantes à votre fichier pom.xml :

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

Si vous utilisez Gradle, ajoutez les lignes suivantes à vos dépendances :

compile 'com.google.cloud:google-cloud-logging:1.61.0'

Si vous utilisez SBT, ajoutez les lignes suivantes à vos dépendances :

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

Si vous utilisez IntelliJ ou Eclipse, vous pouvez ajouter des bibliothèques clientes à votre projet à l'aide des plug-ins IDE suivants :

• Cloud Tools for IntelliJ
• Cloud Tools for Eclipse

Les plug-ins offrent des fonctionnalités supplémentaires, telles que la gestion des clés pour les comptes de service. Reportez-vous à la documentation de chaque plug-in pour plus de détails.

Remarque : Les bibliothèques clientes Java de Google Cloud ne sont actuellement pas compatibles avec 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 :

Afficher sur GitHub Commentaires

# 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

Exemple

Cet extrait montre comment effectuer la journalisation à l'aide du gestionnaire java.util.logging :

Afficher sur GitHub Commentaires

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 Stackdriver Logging.

Valeurs par défaut

L'appender Logback et le gestionnaire java.util.logging instancient un client Stackdriver 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 Stackdriver 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 Stackdriver Logging pour l'API Java, il n'existe 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 Stackdriver Logging nécessitent un type de ressource surveillée afin d'identifier votre application.

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

Une ressource surveillée global est utilisée par défaut dans d'autres environnements.

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 Stackdriver 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 les champs d'un objet LogEntry grâce à 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 :

Afficher sur GitHub Commentaires

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

Pour en savoir plus, consultez la documentation relative à la bibliothèque Stackdriver Logging pour Java. Vous pouvez également signaler d'éventuels problèmes à l'aide de l'outil de suivi des problèmes.

Utiliser directement la bibliothèque cliente cloud

Pour savoir comment utiliser directement la bibliothèque cliente cloud Stackdriver Logging pour Java, consultez la section Bibliothèques clientes Stackdriver Logging.

Exécuter sur Google Cloud Platform

Pour utiliser la bibliothèque Stackdriver Logging pour Java, vous devez détenir le rôle Cloud IAM Rédacteur de journaux sur GCP. La plupart des environnements GCP fournissent ce rôle par défaut.

App Engine

App Engine attribue par défaut le rôle Rédacteur de journaux.

La bibliothèque Stackdriver Logging pour Java peut être utilisée sans fournir explicitement des identifiants.

Stackdriver Logging est automatiquement activé sur les applications App Engine. Aucune configuration supplémentaire n'est requise.

Remarque : Les journaux écrits dans stdout et stderr sont automatiquement envoyés à Stackdriver Logging. Vous n'avez pas besoin d'utiliser la bibliothèque Stackdriver Logging pour Java.

L'environnement standard App Engine utilise par défaut l'API java.util.logging.Logger, qui écrit directement dans Stackdriver 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 Stackdriver Logging pour Java.

Vous pouvez vous connecter directement à Stackdriver Logging à l'aide du gestionnaire java.util.logging en fournissant le champ logging.properties dans votre fichier app.yaml, comme indiqué ici :

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

La journalisation de l'ID de trace est disponible dans les environnements d'exécution Jetty si vous utilisez le gestionnaire java.util.logging ou l'appender Logback.

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 à l'aide de l'étiquette trace_id.

Google Kubernetes Engine

Sur Google Kubernetes Engine, vous devez 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

Instance

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

Lorsque vous utilisez des instances de VM Compute Engine, ajoutez le niveau d'accès cloud-platform à chaque instance. Si vous souhaitez créer une instance via la console Google Cloud Platform, vous pouvez le faire depuis 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 GCP.

Exécuter en local et depuis un autre emplacement

Pour utiliser la bibliothèque Stackdriver Logging pour Java en dehors de GCP, vous devez fournir l'ID de votre projet GCP et les identifiants appropriés du compte de service, directement dans la bibliothèque Stackdriver Logging pour Java. Cela s'applique à l'exécution de l'agent sur votre poste de travail, sur les ordinateurs de vos centres de données ou sur les instances de VM d'un autre fournisseur cloud. Pour en savoir plus, consultez la section Obtenir et fournir manuellement les identifiants du compte de service.

Afficher les journaux

Après le déploiement, vous pouvez afficher les journaux dans la visionneuse de journaux de la console GCP.

Accéder à la visionneuse de journaux

Dans la visionneuse de journaux, vous devez spécifier une ou plusieurs ressources, mais la sélection de ces dernières 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 les solutions Stackdriver Kubernetes Monitoring et de l'ancien Stackdriver, ainsi que sur l'incidence de ces options sur le type de ressource, consultez la section Migrer vers Stackdriver Kubernetes Monitoring.

• Si votre application utilise directement l'API Stackdriver 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 la visionneuse de journaux, pour voir toutes les entrées de journal, passez en mode de filtre avancé et utilisez un filtre vide.

  1. Pour passer en mode de filtre avancé, cliquez sur le menu (▾) en haut de la visionneuse 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 les pages Afficher les journaux et Filtres de journaux avancés.