Protokollierung zur Client-Laufzeit

In diesem Abschnitt wird die Message Queue 4.0-Unterstützung für die Protokollierung von verbindungs- und sitzungsbezogenen Ereignissen zur Client-Laufzeit beschrieben.

JDK 1.4 (und höher) enthält die java.util.logging-Bibliothek. Diese Bibliothek implementiert eine standardmäßige Protokollschnittstelle, die zur anwendungsspezifischen Protokollierung verwendet werden kann.

Die Message Queue-Client-Laufzeit nutzt die Java-Protokoll-API, um deren Protokollierungsfunktionen zu implementieren. Sie können sämtliche J2SE 1.4-Protokolloptionen zum Konfigurieren der Protokollierungsaktivitäten verwenden. Beispielsweise können von einer Anwendung die folgenden Java-Protokolloptionen verwendet werden, um festzulegen, wie die Protokollinformationen von der Message Queue-Client-Laufzeit ausgegeben werden:

• Protokoll-Handler

• Protokollfilter

• Protokollformatierungen

• Protokollebene

Weitere Informationen zur Java-Protokoll-API finden Sie in der Übersicht über die Java-Protokollierung unter http://java.sun.com/j2se/1.4.2/docs/guide/util/logging/overview.html

Protokollnamensräume, -ebenen und -aktivitäten

Der Message Queue-Anbieter definiert mehrere Protokollnamensräume, die mit Protokollebenen und Protokollaktivitäten verknüpft sind, über die Message Queue-Clients Verbindungs- und Sitzungsereignisse protokollieren können, sofern die Protkollkonfiguration entsprechend festgelegt wurde.

Der Root-Protokollnamensraum für die Message Queue-Client-Laufzeit ist als javax.jms definiert. Für alle Protokolle in der Message Queue-Client-Laufzeit wird dieser Name als übergeordneter Namensraum verwendet.

Die für die Message Queue-Client-Laufzeit verwendeten Protokollebenen stimmen mit denen überein, die in der java.util.logging.Level-Klasse definiert sind. Diese Klasse definiert sieben Standardprotokollebenen und zwei zusätzliche Einstellungen, über die Sie die Protokollierung aktivieren bzw. deaktivieren können.

OFF

Deaktiviert die Protokollierung.

SEVERE

Höchste Priorität, höchster Wert. Anwendungsdefiniert.

WARNING

Anwendungsdefiniert.

INFO

Anwendungsdefiniert.

CONFIG

Anwendungsdefiniert.

FINE

Anwendungsdefiniert.

FINER

Anwendungsdefiniert.

FINEST

Niedrigste Priorität, niedrigster Wert. Anwendungsdefiniert.

ALL

Aktiviert die Protokollierung aller Nachrichten.

Im Allgemeinen werden Ausnahmen und Fehler, die zur Message Queue-Client-Laufzeit auftreten, im Protokoll mit dem javax.jms-Namensraum erfasst.

• Ausnahmefehler, die von der JVM ausgelöst und von der Client-Laufzeit abgefangen werden, z. B. IOException, werden bei der Protokollierung mit dem Protokollnamensraum javax.jms auf der Ebene WARNING erfasst.

• JMS-Ausnahmen, die von der Client-Laufzeit ausgelöst werden, z. B. IllegalStateException , werden bei der Protokollierung mit dem Protokollnamensraum javax.jms auf der Ebene FINER erfasst.

• Fehler, die von der JVM zurückgegeben und von der Client-Laufzeit abgefangen werden, z. B. OutOfMemoryError, werden bei der Protokollierung mit dem Protokollnamensraum javax.jms auf der Ebene SEVERE erfasst.

In den folgenden Tabellen sind die Ereignisse aufgelistet, die protokolliert werden können, sowie die Protokollebene, die festgelegt werden muss, um Ereignisse für JMS-Verbindungen und für Sitzungen zu protokollieren.

Die folgende Tabelle enthält Beschreibungen der Protokollebenen und Ereignisse für Verbindungen.

Tabelle 1–6 Protokollebenen und Ereignisse für den javax.jms.connection -Namensraum

Protokollebene	Ereignisse
FINE	Verbindung erstellt
FINE	Verbindung geöffnet
FINE	Verbindung geschlossen
FINE	Verbindung unterbrochen
FINE	Verbindung wiederhergestellt
FINER	Diverse Verbindungsaktivitäten wie z. B. setClientID
FINEST	Nachrichten, Bestätigungen, Message Queue-Aktion und Steuerungsmeldungen (wie das Durchführen einer Transaktion)

Für Sitzungen werden die folgenden Informationen im Protokolleintrag erfasst.

• Jeder Protokolleintrag für eine an den Konsumenten übermittelte Nachricht umfasst ConnectionID, SessionID und ConsumerID.

• Jeder Protokolleintrag für eine Nachricht, die von einem Produzenten gesendet wurde, umfasst ConnectionID, SessionID, ProducerID und Zielname.

Die folgende Tabelle enthält Beschreibungen der Protokollebenen und Ereignisse für Sitzungen.

Tabelle 1–7 Protokollebenen und Ereignisse für den javax.jms.session -Namensraum

Protokollebene	Ereignis
FINE	Sitzung erstellt
FINE	Sitzung geschlossen
FINE	Produzent erstellt
FINE	Konsument erstellt
FINE	Ziel erstellt
FINER	Diverse Sitzungaktivitäten wie z. B. das Durchführen einer Sitzung.
FINEST	Produzierte und konsumierte Nachrichten. (Nachrichteneigenschaften und -texte werden in den Protokolleinträgen nicht erfasst.)

Die Ausgabeprotokollebene wird standardmäßig aus der JRE übernommen, in der die Anwendung ausgeführt wird. Überprüfen Sie die Datei JRE_DIRECTORY/lib/logging.properties , um diese Ebene zu bestimmen.

Sie haben die Möglichkeit, die Protokollierung programmatisch oder mithilfe von Konfigurationsdateien zu konfigurieren. Zudem können Sie den Umfang der Protokollierung steuern. In den folgenden Abschnitten werden diese Möglichkeiten erläutert.

Verwenden der Konfigurationsdatei für das JRE-Protokoll

Das folgende Beispiel zeigt, wie Protokollnamensräume und -ebenen in der Datei JRE_DIRECTORY/lib/logging.properties angegeben werden, die verwendet wird, um die Protokollebene für die Java Runtime Environment festzulegen. Sämtliche Anwendungen, die diese JRE verwenden, verfügen über dieselbe Protokollkonfiguration. In der nachstehenden Beispielkonfiguration wird die Protokollebene für den javax.jms.connection -Namensraum auf INFO gesetzt, und angegeben, dass die Ausgabe in java.util.logging.ConsoleHandler geschrieben werden soll.

#logging.properties file.
# "Handler" geben eine durch Kommas getrennte Liste der Protokoll-Handler-Klassen 
# an. Diese Handler werden während des VM-Starts installiert.
# Beachten Sie, dass sich diese Klassen im selben Systemklassenpfad befinden müssen.
# Standardmäßig wird nur ein ConsoleHandler konfiguriert, der
# nur Meldungen auf INFO-Ebene und höheren Ebenen anzeigt.

	handlers= java.util.logging.ConsoleHandler

# Standardmäßige globale Protokollebene.
# Dies gibt an, welche Ereignisse in allen Protokollen
# erfasst werden. Für jede vorgegebene Funktion kann diese allgemene Ebene
# von einer funktionsspezifischen Ebene überschrieben werden.
# Beachten Sie, dass der ConsoleHandler ebenfalls über eine separate Ebeneneinstellung verfügt,
# über die in der Konsole gedruckten Meldungen eingeschänkt werden können.

    .level= INFO

# Grenzen Sie die Meldungen ein, die auf der Konsole für INFO und höher gedruckt werden.

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

# Bei der Protokollierung mit javax.jms.connection-Namensraum
# werden Level.INFO-Nachrichten für die entsprechenden Ausgabe-Handler geschrieben.
# In dieser Konfiguration ist der Ausgabe-Handler auf java.util.logging.ConsoleHandler gesetzt.

    javax.jms.connection.level = INFO

Verwenden einer Protokollierungskonfigurationsdatei für eine bestimmte Anwendung

Sie können zudem eine Protokollierungskonfigurationsdatei über die Java-Befehlszeile definieren, die Sie verwenden, um eine Anwendung auszuführen. Die Anwendung wird dann die Konfiguration in der angegebenen Protokolldatei verwenden. Im folgenden Beispiel verwendet configFile dasselbe Format, das in der Datei JRE_DIRECTORY/lib/logging.properties definiert ist.

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

Programmatisches Festlegen der Protokollkonfiguration

Im folgenden Code wird die java.util.logging-API zum Protokollieren von Verbindungsereignissen verwendet, indem die Protokollebene für den javax.jms.connection-Namensraum auf FINE geändert wird. Sie können einen solchen Code in die Anwendung einfügen, um die Protokollkonfiguration programmatisch festzulegen.

import java.util.logging.*;
//einen Datei-Handler erzeugen und in der mq.log-Datei 
//im Temp-Verzeichnis des Systems ausgeben.

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

//Protokoll für Domäne "javax.jms.connection" abrufen.

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

//javax.jms.connection-Protokollierung würde Aktivitäten 
//der Ebene FINE und höher erfassen.

    logger.setLevel (Level.FINE);