用戶端執行階段記錄 (Sun Java System Message Queue 4.1 版本說明)

Sun Java System Message Queue 4.1 版本說明

用戶端執行階段記錄

本節說明 Message Queue 4.0 如何針對連線和階段作業相關事件，支援用戶端執行階段的記錄功能。

JDK 1.4 (及以上版本) 包含 java.util.logging 程式庫。此程式庫會實作可用於應用程式特定記錄的標準記錄程式介面。

Message Queue 用戶端執行階段使用 Java 記錄 API 實作其記錄功能。您可以使用所有 J2SE 1.4 記錄功能來配置記錄作業。例如，應用程式可使用下列 Java 記錄功能，配置 Message Queue 用戶端執行階段輸出其記錄資訊的方式：

記錄處理程式
記錄篩選器
記錄格式化程式
記錄層級

如需有關 Java 記錄 API 的更多資訊，請參閱「Java Logging Overview」，網址為 http://java.sun.com/j2se/1.4.2/docs/guide/util/logging/overview.html

記錄名稱空間、層級和作業

Message Queue 提供者會定義一組與記錄層級和記錄作業相關的記錄名稱空間，可在適當設定記錄配置時，讓 Message Queue 用戶端記錄連線與階段作業事件。

Message Queue 用戶端執行階段的根記錄名稱空間定義為 javax.jms。Message Queue 用戶端執行階段的所有記錄程式皆使用此名稱做為父系名稱空間。

Message Queue 用戶端執行階段使用的記錄層級與 java.util.logging.Level 類別中所定義的記錄層級相同。此類別會定義七個標準記錄層級，以及可用於啟動與關閉記錄的兩個其他設定。

OFF: 關閉記錄。
SEVERE: 最高優先權、最高值。由應用程式定義。
WARNING: 由應用程式定義。
INFO: 由應用程式定義。
CONFIG: 由應用程式定義。
FINE: 由應用程式定義。
FINER: 由應用程式定義。
FINEST: 最低優先權、最低值。由應用程式定義。
ALL: 啟用所有訊息的記錄。

一般來說，Message Queue 用戶端執行階段中發生的異常與錯誤，皆由記錄程式使用 javax.jms 名稱空間所記錄。

從 JVM 丟出且由用戶端執行階段截獲的異常 (例如 IOException)，是由記錄程式使用記錄名稱空間 javax.jms 記錄在 WARNING 層級。
從用戶端執行階段丟出的 JMS 異常 (例如 IllegalStateException)，是由記錄程式使用記錄名稱空間 javax.jms 記錄在 FINER 層級。
從 JVM 丟出且由用戶端執行階段截獲的錯誤 (例如 OutOfMemoryError)，是由記錄程式使用記錄名稱空間 javax.jms 記錄在 SEVERE 層級。

下表列出可記錄的事件，以及必須設定的記錄層級以記錄 JMS 連線與階段作業事件。

下表說明連線的記錄層級與事件。

表 1–6 javax.jms.connection 名稱空間的記錄層級與事件


記錄層級	事件
`FINE`	已建立連線
`FINE`	已啟動連線
`FINE`	已關閉連線
`FINE`	已中斷連線
`FINE`	已重新連線
`FINER`	其他連線作業，例如 `setClientID`
`FINEST`	訊息、確認、Message Queue 動作與控制訊息 (如正在確定作業事件)

下列階段作業資訊會記錄在記錄中。

傳送給用戶的每筆訊息記錄包含 ConnectionID、SessionID 和 ConsumerID。
由產生器傳送的每筆訊息記錄包含 ConnectionID、SessionID、ProducerID 和目標名稱。

下表說明階段作業的記錄層級與事件。

表 1–7 javax.jms.session 名稱空間的記錄層級與事件


記錄層級	事件
`FINE`	已建立階段作業
`FINE`	已關閉階段作業
`FINE`	已建立產生器
`FINE`	已建立用戶
`FINE`	已建立目標
`FINER`	其他階段作業，例如正在確定階段作業。
`FINEST`	已產生並使用訊息。(訊息特性與內文不會記錄在記錄中)

根據預設，會從應用程式執行所在的 JRE 繼承輸出記錄層級。請檢查 JRE_DIRECTORY/lib/logging.properties 檔案以判斷該層級為何。

您可以程式化方式或藉由使用配置檔案來配置記錄功能，且可控制記錄發生的範圍。以下小節說明這些可能的作業。

使用 JRE 記錄配置檔案

下列範例說明如何在 JRE_DIRECTORY/lib/logging.properties 檔案中設定記錄名稱空間與層級，該檔案將用以設定 Java 執行階段環境的記錄層級。使用此 JRE 的所有應用程式會有相同的記錄配置。以下的配置範例會將 javax.jms.connection 名稱空間的記錄層級設定為 INFO，並指定將輸出寫入 java.util.logging.ConsoleHandler。

#logging.properties file.
# "handlers" specifies a comma separated list of log Handler 
# classes. These handlers will be installed during VM startup.
# Note that these classes must be on the system classpath.
# By default we only configure a ConsoleHandler, which will only
# show messages at the INFO and above levels.

	handlers= java.util.logging.ConsoleHandler

# Default global logging level.
# This specifies which kinds of events are logged across
# all loggers. For any given facility this global level
# can be overriden by a facility-specific level.
# Note that the ConsoleHandler also has a separate level
# setting to limit messages printed to the console.

    .level= INFO

# Limit the messages that are printed on the console to INFO and above.

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

# The logger with javax.jms.connection name space will write
# Level.INFO messages to its output handler(s). In this configuration 
# the ouput handler is set to java.util.logging.ConsoleHandler.

    javax.jms.connection.level = INFO

使用特定應用程式的記錄配置檔案

您也可以從用於執行應用程式的 Java 指令行來定義記錄配置檔案。應用程式會使用指定的記錄檔中所定義之配置。在下列範例中，configFile 使用 JRE_DIRECTORY/lib/logging.properties 檔案中所定義的相同格式。

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

以程式化方式設定記錄配置

下列程式碼使用 java.util.logging API，將 javax.jms.connection 名稱空間記錄層級變更為 FINE，以記錄連線事件。您可以在應用程式中包含這類程式碼，從而以程式化方式設定記錄配置。

import java.util.logging.*;
//construct a file handler and output to the mq.log file 
//in the system's temp directory.

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

//Get Logger for "javax.jms.connection" domain.

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

//javax.jms.connection logger would log activities   
//with level FINE and above.

    logger.setLevel (Level.FINE);