第 10 章 監視代理程式

本章描述可用來監視代理程式的工具，以及如何取得度量資料。本章包含下列各小節：

• 監視工具簡介

• 配置及使用代理程式記錄功能

• 以互動方式顯示度量

• 撰寫應用程式來監視代理程式

有關特定度量的參考資訊，請參閱第 18 章, 度量參照。

監視工具簡介

Message Queue^TM 資訊有 3 個監視介面：記錄檔、互動式指令，以及可以取得度量的用戶端 API。各有下列優點和缺點：

• 記錄檔提供長期的度量資料記錄，但是不易剖析。

• 指令可讓您快速取得符合您需求的資訊範例，但無法查看歷程資訊或有計劃的處理資料。

• 用戶端 API 可讓您擷取資訊、處理資訊、處理資料、顯示圖表或傳送警示。然而若要使用它，您必須撰寫自訂應用程式來擷取和分析資料。

表 10–1 對不同的工具進行比較。

除了表格中顯示的差異之外，每個工具所收集之代理程式產生的度量資訊也會稍有不同。如需有關各個監視工具所收集度量資料的詳細資訊，請參閱第 18 章, 度量參照。

配置及使用代理程式記錄功能

Message Queue 記錄程式會取得代理程式程式碼、除錯程式和度量產生器所產生的資訊，並且將這些資訊寫入數個輸出通道：標準輸出 (主控台)、記錄檔，以及 Solaris™ 作業系統上的 syslog 常駐程式程序。

您可以指定記錄程式收集的資訊類型，以及寫入每個輸出通道的類型。要特別注意的是，您可以指定您要寫入記錄檔的度量資訊。

本節描述代理程式的預設記錄配置，並介紹如何將記錄資訊重新導向至替代輸出通道、如何變更記錄檔自動重建準則，以及如何將度量資料傳送到記錄檔。

預設記錄配置

代理程式會自動配置為將記錄輸出儲存到一組自動重建的記錄檔中。這些記錄檔的所在目錄名稱，與相關聯代理程式之實例名稱相同 (請參閱附錄 AMessage Queue^TM 資料的特定平台位置)：

…/instances/instanceName/log

如果代理程式的生命週期由應用程式伺服器所控制，則記錄檔的位置是在啟動該代理程式所在網域的網域目錄子目錄中：

…/appServer_domainName_dir/imq/instances/imqbroker/log

記錄檔為簡單的文字檔案。其命名方式如下 (從最早建立到最新建立)：

log.txt
log_1.txt
log_2.txt
…log_9.txt

依預設，每週自動重建一次記錄檔；而系統會維護 9 個備份檔案。

• 若要變更保留記錄檔的目錄，請將特性 imq.log.file.dirpath 設定為所需的路徑。

• 若要將記錄檔的根名稱從 log 變更為其他名稱，請設定 imq.log.file.filename 特性。

代理程式支援三種記錄層級：ERROR、WARNING 、INFO。表 10–2 解釋各個層級的涵義。

設定某個記錄層級，則會收集此層級以及所有更高層級的訊息。預設記錄層級是 INFO，因此依預設，ERROR、 WARNING 和 INFO 訊息會全部記錄。

記錄訊息格式

記錄的訊息包含時間標記、訊息程式碼和訊息本身。資訊容量因您所設定的記錄層級而有所不同。以下為 INFO 訊息的範例。

[13/Sep/2000:16:13:36 PDT] [B1004]: Starting the broker service using tcp 
[25374,100] with min threads 50 and max threads of 500

若要變更時間標記的時區，請參閱表 14–8 中有關描述 imq.log.timezone 特性的資訊。

變更記錄程式配置

表 14–8 描述記錄的相關特性。

變更代理程式的記錄程式配置

1. 設定記錄層級。

2. 為一個或多個記錄種類設定輸出通道 (檔案和/或主控台)。

3. 如果您將輸出記錄至檔案，請為此檔案配置自動重建準則。

   可以透過設定記錄程式特性來完成這些步驟。您可以用以下兩種方法之一執行此作業：

   • 啟動代理程式之前，請先變更或增加代理程式之 config.properties 檔案中的記錄程式特性。

   • 在啟動代理程式的 imqbrokerd 指令中，指定記錄程式指令行選項。您也可以使用代理程式選項 -D 變更記錄程式特性 (或任何代理程式特性)。

   在指令行上傳送的選項，會置換在代理程式實例配置檔案中所指定的特性。以下的 imqbrokerd 選項會影響記錄：

   -metrics interval

   代理程式度量的記錄時間間隔 (以秒為單位)

   -loglevel level

   記錄層級 (ERROR、WARNING、 INFO 或 NONE)

   -silent

   無訊息模式 (不記錄至主控台)

   -tty

   將所有訊息記錄至主控台

   以下各節描述如何變更預設配置，以執行以下作業：

   • 變更輸出通道 (記錄訊息的目標)

   • 變更自動重建準則

變更輸出通道

依預設，錯誤和警告訊息可顯示在終端機上，也可記錄至記錄檔中。(在 Solaris 上，錯誤訊息也可寫入至系統的 syslog 常駐程式。)

您可以用以下方法變更記錄訊息的輸出通道：

• 若要使所有記錄種類 (對於指定的層級) 輸出顯示在畫面上，請使用 imqbrokerd 指令的 -tty 選項。

• 若要避免記錄輸出顯示在畫面上，請使用 imqbrokerd 指令的 -silent 選項。

• 使用 imq.log.file.output 特性，指定應寫入至記錄檔的記錄資訊種類。例如：

  imq.log.file.output=ERROR

• 使用 imq.log.console.output 特性，指定應寫入至主控台的記錄資訊種類。例如：

  imq.log.console.output=INFO

• 在 Solaris 上，使用 imq.log.syslog.output 特性，指定應寫入至 Solaris syslog 的記錄資訊種類。例如：

  imq.log.syslog.output=NONE

變更記錄程式輸出通道前，您必須確定所設定的記錄層級，支援要對映到輸出通道的資訊。例如，如果您將記錄層級設定為 ERROR，並且將 imq.log.console.output 特性設定為 WARNING，則不會記錄任何訊息，因為您未啟用 WARNING 訊息的記錄。

變更記錄檔自動重建準則

有兩個記錄檔自動重建準則：時間和容量。預設為使用時間準則，每七天自動重建一次檔案。

• 若要變更時間間隔，您需要變更特性 imq.log.file.rolloversecs。例如，以下特性定義將時間間隔變更為十天：

  imq.log.file.rolloversecs=864000

• 若要將自動重建準則變更為取決於檔案容量，您需要設定 imq.log.file.rolloverbytes 特性。例如，以下定義會讓代理程式在檔案達到 500,000 個位元組的限制時，就自動重建檔案。

  imq.log.file.rolloverbytes=500000

如果同時設定與時間相關的自動重建特性以及與容量相關的自動重建特性，則先達到的限制將觸發自動重建作業。如上所述，代理程式最多可保留九個自動重建檔案。

代理程式執行時，您可以設定或變更記錄檔自動重建特性。若要設定這些特性，請使用 imqcmd update bkr 指令。

將度量資料傳送到記錄檔

本節描述使用代理程式記錄檔報告度量資訊的程序。如需有關配置記錄程式的一般資訊，請參閱配置及使用代理程式記錄功能。

使用記錄檔報告度量資訊

1. 配置代理程式的度量產生功能：

   1. 確定 imq.metrics.enabled=true

      依預設，會開啟用於記錄的度量產生功能。

   2. 設定度量產生的合適秒數時間間隔。

      imq.metrics.interval=interval

      您可以在 config.properties 檔案中設定此值，或在啟動代理程式時，使用 -metrics interval 指令行選項設定此值。

2. 確定記錄程式已收集度量資訊：

   imq.log.level=INFO

   這是預設值。啟動代理程式時，您可以在 config.properties 檔案中設定此值，或使用 -loglevel level 指令行選項設定此值。

3. 確定已設定記錄程式，將度量資訊寫入記錄檔：

   imq.log.file.output=INFO

   這是預設值。您可以在 config.properties 檔案中進行設定。

4. 啟動代理程式。

   以下所示為代理程式度量輸出到記錄檔的範例：

   [21/Jul/2004:11:21:18 PDT] Connections: 0 JVM Heap: 8323072 bytes (7226576 free) Threads: 0 (14-1010) In: 0 msgs (0bytes) 0 pkts (0 bytes) Out: 0 msgs (0bytes) 0 pkts (0 bytes) Rate In: 0 msgs/sec (0 bytes/sec) 0 pkts/sec (0 bytes/sec) Rate Out: 0 msgs/sec (0 bytes/sec) 0 pkts/sec (0 bytes/sec)

   如需有關度量資料的參考資訊，請參閱第 18 章, 度量參照。

記錄停用的訊息

您可以啟用代理程式停用的訊息之記錄功能來監視實體目標。無論您有沒有使用此停用的訊息佇列，都可以記錄這些停用的訊息。

啟用此停用的訊息之記錄功能後，代理程式會記錄下列類型的事件：

• 實體目標超出最大容量。

• 代理程式移除實體目標的訊息，原因可能如下：

  • 已達目標容量限制。

  • 訊息的時限已到。

  • 訊息太大。

  • 代理程式處理訊息時發生錯誤。

如果停用的訊息佇列在使用中，還會記錄下列類型的事件：

• 代理程式將訊息移動到停用的訊息佇列。

• 代理程式將停用的訊息佇列中的訊息移除並且捨棄。

以下為停用的訊息之記錄格式範例：

[29/Mar/2006:15:35:39 PST] [B1147]: Message 8-129.145.180.87(e7:6b:dd:5d:98:aa)-
35251-1143675279400 from destination Q:q0 has been placed on the DMQ because 
[B0053]: Message on destination Q:q0 Expired: expiration time 1143675279402, 
arrival time 1143675279401, JMSTimestamp 1143675279400

依預設，不記錄停用的訊息。若要記錄，請設定代理程式屬性 imq.destination.logDeadMsgs。

以互動方式顯示度量

Message Queue 代理程式可以報告下列類型的度量：

• Java 虛擬機器 (JVM) 度量。有關 JVM 堆疊容量的資訊。

• 代理程式通用度量。有關儲存於代理程式中的訊息、輸入和輸出代理程式的訊息流量，以及記憶體用途的資訊。追蹤訊息的數量和位元組數。

• 連線服務度量。有關連線和連線執行緒資源的資訊，以及有關特定連線服務訊息流量的資訊。

• 目標度量。有關傳入和傳出特定實體目標之訊息流量的資訊，以及有關實體目標用戶、記憶體和磁碟空間使用率的資訊。

imqcmd 指令可以取得整個代理程式、個別連線服務和個別實體目標的度量資訊。若要取得度量資料，通常可使用 imqcmd 的子指令 metrics。度量資料會依您指定的時間間隔或次數寫入主控台畫面。

您也可以使用 query 子指令，檢視也包含配置資訊的類似資料。如需更多資訊，請參閱imqcmd query。

imqcmd metrics

imqcmd metrics 的語法和選項分別顯示於表 10–3 和表 10–4 中。

metrics bkr
   [-b hostName:portNumber]
   [-m metricType]
   [-int interval]
   [-msp numSamples]

metrics svc -n serviceName
   [-b hostName:portNumber]
   [-m metricType]
   [-int interval]
   [-msp numSamples]

metrics dst -t destType
   -n destName
   [-b hostName:portNumber]
   [-m metricType]
   [-int interval]
   [-msp numSamples]

-b hostName: portNumber

-int interval

-m metricType

-msp numSamples

-n destName

-n serviceName

-t destType

使用顯示度量資料的 metrics 子指令

本小節描述使用 metrics 子指令報告度量資訊的程序。

使用 metrics 子指令

1. 啟動需要度量資訊的代理程式。

   請參閱啟動代理程式。

2. 發出適當的 imqcmd metrics 子指令和選項，如表 10–3 和表 10–4 中所示。

度量輸出：imqcmd 度量

本小節包含 imqcmd metrics 子指令的輸出範例。這些範例顯示代理程式範圍、連線服務和實體目標度量。

代理程式通用度量

若要取得訊息和封裝每隔 10 秒傳入和傳出代理程式的速率，請使用 metrics bkr 子指令：

imqcmd metrics bkr -m rts -int 10 -u admin

此指令會產生與以下相類似的輸出 (請參閱表 18–2 中的資料說明)：

--------------------------------------------------------
 Msgs/sec   Msg Bytes/sec   Pkts/sec    Pkt Bytes/sec   
 In   Out     In      Out     In   Out     In      Out  
--------------------------------------------------------
 0     0      27      56      0     0      38      66   
 10    0     7365     56      10    10    7457    1132  
 0     0      27      56      0     0      38      73   
 0     10     27     7402     10    20    1400    8459  
 0     0      27      56      0     0      38      73   

連線服務度量

若要取得 jms 連線服務所處理的訊息和資料封包等累積總數，請使用 metrics svc 子指令：

imqcmd metrics svc -n jms -m ttl -u admin

此指令會產生與以下相類似的輸出 (請參閱表 18–3 中的資料說明)：

-------------------------------------------------
  Msgs      Msg Bytes      Pkts      Pkt Bytes     
In   Out    In     Out   In   Out    In     Out  
-------------------------------------------------
164  100  120704  73600  282  383  135967  102127
657  100  483552  73600  775  876  498815  149948

實體目標度量

若要取得有關實體目標的度量資訊，請使用 metrics dst 子指令：

imqcmd metrics dst -t q -n XQueue -m ttl -u admin

此指令會產生與以下相類似的輸出 (請參閱表 18–4 中的資料說明)：

-----------------------------------------------------------------------------
  Msgs      Msg Bytes         Msg Count         Total Msg Bytes (k)     Largest
In   Out    In     Out    Current  Peak  Avg  Current  Peak     Avg    Msg (k)
-----------------------------------------------------------------------------
200  200  147200  147200     0     200    0      0      143      71        0  
300  200  220800  147200    100    200   10     71      143      64        0  
300  300  220800  220800     0     200    0      0      143      59        0  

若要取得有關實體目標的用戶資訊，請使用以下 metrics dst 子指令：

imqcmd metrics dst -t q -n SimpleQueue -m con -u admin

此指令會產生與以下相類似的輸出 (請參閱表 18–4 中的資料說明)：

------------------------------------------------------------------
  Active Consumers         Backup Consumers         Msg Count
Current  Peak  Avg      Current  Peak    Avg    Current  Peak  Avg
------------------------------------------------------------------
   1       1      0        0       0      0       944    1000  525

imqcmd query

表 10–5 中顯示 imqcmd query 的語法和選項，以及該指令所提供之度量資料的說明。

query bkr
   [-b hostName: portNumber]

query svc -n serviceName
  [-b  hostName:portNumber]

query dst -t destType
  -n destName
  [-b hostName:portNumber]

由於 imqcmd query 提供的度量資料有限，因此未在第 18 章, 度量參照的表格中列出此工具。

撰寫應用程式來監視代理程式

Message Queue 提供度量監視功能，此功能可讓代理程式將度量資料寫入 JMS 訊息，然後根據訊息中包含的度量資訊類型，將資料傳送到其中一個度量主題目標。

您可以藉由寫入訂閱度量主題目標、使用目標中的訊息並處理訊息中度量資訊的用戶端應用程式，來存取此度量資訊。

總共有 5 個度量主題目標，表 10–6 中顯示這些目標的名稱，以及應傳送到每個目標的度量訊息類型。

設定訊息型監視

本小節描述使用訊息型監視功能以收集度量資訊的程序。程序包括用戶端部署和管理作業。

若要設定訊息型監視

1. 寫入度量監視用戶端。

   請參閱「Message Queue Developer's Guide for Java Clients」，瞭解如何以程式設計方式讓用戶端訂閱度量主題目標、使用度量訊息，以及從這些訊息擷取度量資料。

2. 設定 config.properties 檔案中的代理程式特性值，以配置代理程式的度量訊息產生者：

   1. 啟用度量訊息產生。

      設定 imq.metrics.topic.enabled=true

      預設為 true。

   2. 設定產生度量訊息的時間間隔 (以秒為單位)。

      設定 imq.metrics.topic.interval=interval。

      預設為 60 秒。

   3. 指定度量訊息是否為永久性訊息 (即訊息是否在代理程式故障後仍然存留)。

      設定 imq.metrics.topic.persist。

      預設為 false。

   4. 指定度量訊息刪除前，保留在其個別目標中的時間長短。

      設定 imq.metrics.topic.timetolive。

      預設值為 300 秒。

3. 設定任何您要在度量主題目標上的存取控制。

   請參閱以下安全性與存取注意事項中的說明。

4. 啟動度量監視用戶端。

   用戶訂閱度量主題時，即會自動建立度量主題目標。建立度量主題之後，代理程式度量訊息產生者就會開始傳送度量訊息到度量主題。

安全性與存取注意事項

有兩個限制度量主題目標存取的原因：

• 度量資料可能包含有關代理程式及其資源的機密資訊。

• 度量主題目標的訂閱數過量，可能會增加代理程式的經常性耗用時間，因此會對效能產生不良影響。

由於這些考量，所以建議您限制度量主題目標的存取。

監視用戶端必須遵守與其他用戶端相同的認證和授權控制。只有 Message Queue 使用者儲存庫中的使用者可以連線到代理程式。

您可以使用存取控制特性檔案來限制對於特定度量主題目標的存取，以提供額外保護，如使用者授權：存取控制特性檔案中所述。

例如，以下 accesscontrol.properties 檔案中的項目會拒絕任何使用者存取 mq.metrics.broker 度量主題，但 user1 和 user 2 除外。

topic.mq.metrics.broker.consume.deny.user=*
topic.mq.metrics.broker.consume.allow.user=user1,user2

以下項目僅允許使用者 user3 監視主題 t1。

topic.mq.metrics.destination.topic.t1.consume.deny.user=*
topic.mq.metrics.destination.topic.t1.consume.allow.user=user3

您也可以根據度量資料的機密程度，使用加密連線將度量監視用戶端連線到代理程式。如需有關使用加密連線的資訊，請參閱訊息加密。

度量輸出：度量訊息

使用訊息型監視 API 取得度量資料輸出，是您編寫度量監視用戶端需具備的功能之一。您僅受限於代理程式中度量產生器提供的資料。如需此資料的完整清單，請參閱第 18 章, 度量參照。