Journalisation à l'exécution client (Notes de version de Sun Java System Message Queue 4.1)

Notes de version de Sun Java System Message Queue 4.1

Journalisation à l'exécution client

Cette section décrit la prise en charge Message Queue 4.0 pour une journalisation à l'exécution client des événements de connexion et de ceux associés à la session.

JDK 1.4 (et versions supérieures) inclut la bibliothèque java.util.logging. Cette bibliothèque implémente une interface d'enregistrement standard pouvant être utilisée pour une journalisation basée sur les applications.

L'exécution client Message Queue utilise l'API de journalisation Java pour mettre en œuvre ses fonctions de journalisation. Vous pouvez utiliser tous les services de journalisation de J2SE 1.4 pour la configuration des activités de journalisation. Par exemple, une application peut utiliser les services de journalisation Java suivants pour configurer le mode d'envoi des informations de journalisation par l'exécution client Message Queue :

gestionnaires de journalisation ;
filtres de journalisation ;
formateurs de journalisation ;
niveaux de journalisation.

Pour plus d'informations sur l'API de journalisation Java, consultez la présentation relative à ce sujet à l'adresse suivante : http://java.sun.com/j2se/1.4.2/docs/guide/util/logging/overview.html

Espaces de noms, niveaux et activités de journalisation

Le fournisseur Message Queue définit un ensemble d'espaces de noms de journalisation associés aux niveaux et activités de journalisation et permettant aux clients Message Queue d'enregistrer les événements de connexion et de session avec une configuration de journalisation correctement définie.

L'espace de noms de journalisation racine pour l'exécution client Message Queue est nommé javax.jms. Tous les journaux de l'exécution client Message Queue utilisent ce nom en tant qu'espace de noms parent.

Les niveaux de journalisation utilisés pour l'exécution client Message Queue sont identiques à ceux utilisés dans la classe java.util.logging.Level. Cette classe définit sept niveaux de journalisation standard, ainsi que deux paramètres supplémentaires pouvant être utilisés pour activer et désactiver la journalisation.

OFF: Désactive la journalisation.
SEVERE: Priorité la plus haute, valeur la plus élevée. Défini par l'application.
WARNING: Défini par l'application.
INFO: Défini par l'application.
CONFIG: Défini par l'application.
FINE: Défini par l'application.
FINER: Défini par l'application.
FINEST: Priorité la plus basse, valeur la plus faible. Défini par l'application.
ALL: Permet d'enregistrer tous les messages.

En règle générale, les exceptions et les erreurs survenues à l'exécution client Message Queue sont consignées dans le journal avec l'espace de noms javax.jms.

Les exceptions levées à partir de la JVM et interceptées par l'exécution client, telles que IOException, sont consignées dans le journal avec l'espace de noms javax.jms au niveau WARNING.
Les exceptions JMS levées à partir de l'exécution client, telles que IllegalStateException , sont consignées dans le journal avec l'espace de noms javax.jms au niveau FINER.
Les erreurs levées à partir de la JVM et interceptées à l'exécution client, telles que OutOfMemoryError, sont consignées dans le journal avec l'espace de noms javax.jms au niveau SEVERE.

Les tableaux suivants répertorient les événements pouvant être consignés, ainsi que le niveau nécessaire à la journalisation d'événements pour les connexions JMS et pour les sessions.

Le tableau suivant décrit les niveaux de journal et les événements relatifs aux connexions.

Tableau 1–6 Niveaux de journal et événements pour l'espace de noms javax.jms.connection


Niveau de journal	Événements
`FINE`	Connexion créée.
`FINE`	Connexion démarrée.
`FINE`	Connexion fermée.
`FINE`	Connexion rompue.
`FINE`	Connexion rétablie.
`FINER`	Diverses activités de connexion, telles que `setClientID`.
`FINEST`	Messages, accusés de réception, messages d'action et de contrôle de Message Queue (par exemple, validation d'une transaction).

Pour les sessions, les informations suivantes sont consignées dans l'enregistrement du journal.

Chaque enregistrement de journal, associé à un message remis à un consommateur, inclut un ID de connexion, un ID de session et un ID de consommateur.
Chaque enregistrement de journal, associé à un message envoyé par un producteur, inclut un ID de connexion, un ID de session, un ID de producteur et un nom de destination.

Le tableau ci-dessous décrit les niveaux de journal et les événements relatifs aux sessions.

Tableau 1–7 Niveaux de journal et événements pour l'espace de noms javax.jms.session


Niveau de journal	Événement
`FINE`	Session créée.
`FINE`	Session fermée.
`FINE`	Producteur créé.
`FINE`	Consommateur créé.
`FINE`	Destination créée.
`FINER`	Diverses activités de session, telles que la validation d'une session.
`FINEST`	Messages produits et consommés. (Les propriétés et le corps de message ne sont pas consignés dans les enregistrements du journal.)

Par défaut, le niveau du journal de sortie est hérité du JRE dans lequel l'application est exécutée. Consultez le fichier JRE_DIRECTORY/lib/logging.properties pour vérifier de quel niveau il s'agit.

Vous pouvez configurer la journalisation à l'aide de programmes ou en utilisant des fichiers de configuration. En outre, vous pouvez contrôler l'étendue de ce processus. Ces possibilités sont décrites dans les sections suivantes.

Utilisation du fichier de configuration de journalisation du JRE

L'exemple suivant présente le mode de définition des espaces de noms et des niveaux de journalisation dans le fichier JRE_DIRECTORY/lib/logging.properties, utilisé pour définir le niveau de journal de l'environnement d'exécution Java. Toutes les applications utilisant ce JRE présenteront la même configuration de journalisation. L'exemple de configuration ci-dessous définit le niveau de journalisation sur INFO pour l'espace de noms javax.jms.connection et indique que la sortie doit être écrite dans java.util.logging.ConsoleHandler .

#logging.properties file.
# « handlers » spécifie une liste des classes de gestionnaire de journaux,
# séparées par une virgule. Ces gestionnaires seront installés au 
# démarrage de la VM. Notez que ces classes doivent être comprises      
# dans le chemin de classe système.
# Par défaut, seul un ConsoleHandler (gestionnaire de consoles) est       
# configuré, affichant ainsi uniquement des messages aux niveaux INFO 
# et supérieurs.

	handlers= java.util.logging.ConsoleHandler

# Niveau de journalisation global par défaut.
# Celui-ci permet de spécifier quels types d'événements sont consignés
# dans l'ensemble des journaux. Pour tout service donné, ce niveau global
# peut être remplacé par un niveau spécifique au service.
# Notez que le ConsoleHandler dispose également d'un paramètre de
# niveau distinct pour limiter les messages imprimés dans la console.

    .level= INFO

# Seuls les messages de niveaux INFO et supérieurs sont imprimés dans la console.

    java.util.logging.ConsoleHandler.level = INFO
    java.util.logging.ConsoleHandler.formatter = 
                                    java.util.logging.SimpleFormatter

# Le journal, dont l'espace de noms est javax.jms.connection, écrira les messages
# Level.INFO dans son ou ses gestionnaires de sortie. Dans cette configuration, 
# le gestionnaire de sortie est défini sur java.util.logging.ConsoleHandler.

    javax.jms.connection.level = INFO

Utilisation d'un fichier de configuration de journalisation pour une application spécifique

Vous avez également la possibilité de définir un fichier de configuration de journalisation à partir de la ligne de commande Java utilisée pour exécuter une application. L'application utilisera alors la configuration définie dans le fichier de journalisation spécifié. Dans l'exemple ci-dessous, configFile utilise le même format que celui défini dans le fichier JRE_DIRECTORY/lib/logging.properties .

java -Djava.util.logging.config.file=configFile MQApplication

Définition de la configuration de journalisation à l'aide de programmes

Le code suivant utilise l'API java.util.logging pour consigner les événements de connexion en modifiant le niveau de journal de l'espace de noms javax.jms.connection sur FINE. Vous pouvez inclure ce type de code dans votre application pour définir la configuration de la journalisation via des programmes.

import java.util.logging.*;
//créer un gestionnaire de fichiers et l'envoyer vers le fichier mq.log
//dans le répertoire temporaire du système.

    Handler fh = new FileHandler("%t/mq.log");
    fh.setLevel (Level.FINE);

//Obtenir un journal pour le domaine « javax.jms.connection ».

    Logger logger = Logger.getLogger("javax.jms.connection");
    logger.addHandler (fh);

//le journal javax.jms.connection consigne les activités
//de niveaux FINE et supérieurs.

    logger.setLevel (Level.FINE);