簡介
本文使用多個場景來展示 IBMWebSphereMQ Application Activity Trace 的 潛在用途，包括問題確定和維護 WebSphere MQ 消息的審計跟蹤。在各個場景中 將使用兩個工具來格式化用於分析的 Application Activity Trace 記錄：
命令行工具 amqsact，它作為一個示例隨 WebSphere MQ 提供。
在 SupportPac MS0P 中包括的事件和統計數據查看器：WebSphere MQ Explorer – Extended Management Plug-ins。下載 SupportPac MS0P。
打開 Application Activity Trace
Application Activity Trace 激活由一個名為 ACTVTRC 的隊列管理器屬性控 制。如需打開跟蹤，需使用 runmqsc 命令 ALTER QMGR ACTVTRC(ON)。如需關閉 跟蹤，則要使用 runmqsc 命令 ALTER QMGR ACTVTRC(OFF)。啟動或停止 Application Activity Trace 並不需要重新啟動隊列管理器。
在 WebSphere MQ Explorer 中，也可以在隊列管理器屬性的在線監視部分中 打開或關閉 Application Activity Trace，如圖 1 所示：
圖 1. 使用 WebSphere MQ Explorer 啟用 Application Activity Trace
也可以在 MQCONNX 調用中打開 Application Activity Trace。如需了解更多 信息，請參閱 WebSphere MQ 信息中心的 MQCONNX 選項。
配置 Application Activity Trace
配置文件 mqat.ini 讓您可以控制 Application Activity Trace 的頻率和詳 細級別。mqat.ini 文件位於隊列管理器數據目錄中：
在 Linux和 UNIX上：/var/mqm/qmgrs/<qm_name>
在 MicrosoftWindows上：C:\Program Files\IBM\WebSphere MQ\qmgrs\<qm_name>
其中的 <qm_name> 是隊列管理器的名稱。
可以動態修改 ini 文件，無需重新啟動隊列管理器。您只需要關閉 Application Activity Trace，並重新打開它，變更就會生效。
選擇 Application Activity Trace 級別
配置 Application Activity Trace 輸出中的詳細級別可以有很多種選擇。 mqat.ini 文件中的配置選項包括：
能夠限制針對其運行跟蹤的應用程序。例如，通過在 ApplicationTrace 節中 指定 ApplName，您可以指定要跟蹤的應用程序。由於 WebSphere MQ V7.5 Java 客戶端目前包含真實的應用程序名稱，而不是面向 Java 的通用 WebSphere MQ 客戶端，所以現在跟蹤 Java 應用程序也有了更大的靈活性。
選擇在 Application Activity Trace 消息中包含消息數據。
能夠配置跟蹤消息之間的時間間隔，以及將多個跟蹤記錄批處理為一個單一消 息。在需要優先考慮性能的情況下，此功能讓您可以修改由 Application Activity Trace 生成的消息數量。默認是為連接到隊列管理器的每一個 Message Queue Interface (MQI) 調用生成一條 Application Activity Trace 記錄。每 個 Application Activity Trace 消息包含 100 條跟蹤記錄。
能夠配置 Application Activity Trace 中包含的詳細信息級別，如下一節中 所述。
根據您所需要的粒度，通過 Application Activity Trace 配置文件 mqat.ini 中的 TraceLevel 參數，可以將跟蹤級別設置為 LOW、MEDIUM 或 HIGH 。例如，mqat.ini 的以下摘錄顯示 TraceLevel 被設置為 MEDIUM（這是默認設 置）：
AllActivityTrace: # Global settings stanza
ActivityInterval=1 # Time interval between trace messages
# Values:0-99999999 (0=off)
# Default:0
ActivityCount=100 # Number of operations between trace msgs
# Values:0-99999999 (0=off)
# Default:0
TraceLevel=MEDIUM # Amount of data traced for each operation
# Values:LOW | MEDIUM | HIGH
# Default:MEDIUM
TraceMessageData=0 # Amount of message data traced
# Values:0-104857600
# Default:0
StopOnGetTraceMsg=ON # Stop trace on get of activity trace
message
# Values:ON | OFF
# Default:ON
作為使用不同跟蹤級別生成的輸出示例，下面的圖 2 顯示了 MQPUT 調用的輸 出參數。此數據取自 WebSphere MQ 客戶端應用程序（amqsputc 示例）的 Application Activity Trace，該應用程序連接到隊列管理器，並將一個消息放 在本地隊列上：
圖 2. 使用不同跟蹤級別記錄的 MQPut 參數
適當的跟蹤級別取決於打開 Application Activity Trace 的原因。如果您要 故障排除代碼頁轉換問題，並且需要檢查 CCSID 消息，那麼需要至少將跟蹤詳細 級別設置為 MEDIUM。另一方面，如果只關心某個隊列的成功 MQPUT 的數量，那 麼 LOW 詳細級別可能就足夠了。要想根據您的要求確定相應的跟蹤詳細級別，打 開 Application Activity Trace 較短一段時間，並以嘗試不同的跟蹤詳細級別 ，以確定哪個級別提供所需要的詳細信息量。
Application Activity Trace 的性能影響
Application Activity Trace 的性能影響取決於您指定的詳細級別、被跟蹤 的應用程序數量，以及生成活動消息的頻率。選擇為您提供所需信息的最低詳細 級別和頻率，在重視性能的情況下尤其如此。確保讀取活動跟蹤消息的監控應用 程序能與跟蹤生成保持同步，這樣活動跟蹤消息的排隊就不會產生瓶頸。
格式化 Application Activity Trace 輸出
您可以編寫自己的應用程序來讀取和格式化 Application Activity Trace 消 息。
本文中的場景使用 amqsact 樣例程序及 WebSphere MQ Explorer 中的 Application Activity Trace 查看器來格式化跟蹤消息。
amqsact 樣例程序
amqsact 幫助您格式化 Application Activity Trace 消息，它是隨 WebSphere MQ 一起提供的。同時還提供了源代碼，讓您可以很容易就看到它如何 工作，並且可以擴展和修改其行為來滿足您的要求。編譯的程序位於樣例目錄中 ：
在 Linux 和 UNIX 上：MQ_INSTALLATION_PATH?samp?bin
在 Windows 上：MQ_INSTALLATION_PATH\tools\c\Samples\Bin;
amqsact 選項
amqsact [-m QMgrName]
[-q QName] # Override default queue name
[-t TopicString] # Subscribe to event topic
[-b] # Only browse records
[-v] # Verbose output
[-d <depth>] # Number of records to display
[-w <timeout>] # Time to wait (in seconds)
[-s <startTime>] # Start time of record to process
[-e <endTime>] # End time of record to
process
示例輸出
下面是 MQCONN API 調用的輸出示例，使用以下命令進行格式化：amqsact – m TESTQM -v：
MonitoringType:MQI Activity Trace Correl_id: 00000000:414D 5143 5445 5354 514D 2020 2020 2020 'AMQCTESTQM ' 00000010:B5F6 4251 2000 E601 '.BQ .. ' QueueManager:'TESTQM' Host Name:'ADMINIB-1VTJ6N1' IntervalStartDate:'2013-03-15' IntervalStartTime:'12:08:10' IntervalEndDate:'2013-03-15' IntervalEndTime:'12:08:10' CommandLevel:710 SeqNumber:0 ApplicationName:'WebSphere MQ_1\bin\amqsput.exe' Application Type:MQAT_WINDOWS_NT ApplicationPid:14076 UserId:'Emma_Bushby' API Caller Type:MQXACT_EXTERNAL API Environment:MQXE_OTHER Application Function:'' Appl Function Type:MQFUN_TYPE_UNKNOWN Trace Detail Level:2 Trace Data Length:0 Pointer size:4 Platform:MQPL_WINDOWS_NT MQI Operation:0 Operation Id:MQXF_CONN ApplicationTid:1 OperationDate:'2013-03-15' OperationTime:'12:08:10' ConnectionId: 00000000:414D 5143 5445 5354 514D 2020 2020 2020 'AMQCTESTQM ' 00000010:FFFFFFB5FFFFFFF6 4251 2000 FFFFFFE601 '.BQ .. ' QueueManager:'TESTQM' Completion Code:MQCC_OK Reason Code:0 Connect Options:256
WebSphere MQ Explorer Application Activity Trace 查看器
SupportPac MSOP:WebSphere MQ Explorer – Extended Management Plug-ins 提供一個 Application Activity Trace 查看器，格式化 Application Activity Trace 消息，並且按應用程序對跟蹤消息進行排序，這讓您可以輕松地 按應用程序查看消息流。
安裝 Extended Management Plug-in for MQ Explorer 之後，您可以格式化 Application Activity Trace 消息，只需在內容窗格中右鍵單擊 SYSTEM.ADMIN.TRACE.ACTIVITY.QUEUE，並單擊 Format Activity Records。下圖所示的窗口已打開，讓您可以指定格式化 Application Activity Trace 消息的多個選項：
圖 3. 顯示 Application Activity Trace 的選項
Merge Activity選項指定，嘗試將報告消息鏈關聯為同一 應用程序的一部分。本文中的場景都使用此選項。格式化的消息在事件和統計查 看器中顯示，如下所示：
圖 4. 事件和統計查看器
使用 Application Activity Trace 對應用程序行為進行故障排除
Application Activity Trace 可以幫助您對 WebSphere MQ 應用程序行為的 問題進行故障排除，因為它為您提供了應用程序可以執行 MQI 調用的詳細視圖。 本節中的三個場景向您演示了如何使用 Application Activity Trace 對應用程 序行為的問題進行故障排除。本節中的場景以 X 公司的 WebSphere MQ 環境為基 礎，如下面的圖 5 所示。一些 WebSphere MQ 客戶端應用程序連接到隊列管理器 CLUSQM_1，它是 WebSphere MQ 集群 TESTSCLUSTER 的成員，而且此集群中包含 另外兩個隊列管理器，CLUSQM_2 和 CLUSQM_3。
圖 5. X 公司的 WebSphere MQ 環境
本欄目
場景 1. 集群隊列之間的消息沒有實現工作負載均衡
在場景 1 中，X 公司的 WebSphere MQ 管理員注意到，目的地為其中一個集 群隊列的消息沒有均勻分布在整個集群內的所有隊列實例上。該場景中的消息流 起源於 WebSphere MQ 集群外部的一些客戶端應用程序。消息從應用程序發送到 隊列 CLUS_Q，通過隊列管理器 CLUSQM_1 托管在集群中的兩個隊列管理器 CLUSQM_2 和 CLUSQM_3 上。
X 公司的開發標准指定，當放到集群隊列中時，應使用 MQOPEN 選項 MQOO_BIND_NOT_FIXED，實現在一個集群隊列的所有實例的消息工作負載均衡。管 理員沒有應用程序代碼的訪問權限，無法驗證是否 MQOPEN 選項是否正確，或者 其中一個應用程序是否錯誤地使用了 MQOO_BIND_ON_OPEN 選項，這會造成對 CLUS_Q 的消息分布不均。
為了驗證 MQ_BIND_NOT_FIXED 是否由所有連接的應用程序使用，管理員在 CLUSQM_1 上打開 Application Activity Trace，並使用 MQ Explorer 中的 Events and Statistics Viewer 來格式化消息。圖 6 摘自 Events and Statistics Viewer，可以清楚地表明，其中一個應用程序正在使用 MQOO_BIND_ON_OPEN 選項，這使管理員能夠快速識別導致意外行為的應用程序。
圖 6. 使用 BIND_ON_OPEN 的應用程序
場景 2. 隊列管理器到達 maxchannels 限制
X 公司的管理員將隊列管理器 CLUSQM_1 的 maxchannels 值配置為 500，這 意味著在同一時間可以連接到隊列管理器的通道不超過 500 個。該設置已經使用 多年，一直沒有出現問題，但在最近幾周，管理員收到警報，表示已達到 maxchannels 值，所以管理員已臨時增大隊列管理器的 maxchannels 值來容納所 有連接。
為了確定連接數是否合理地增加，或者應用程序在完成處理時，是否無法與隊 列管理器斷開連接而保持與隊列管理器的連接打開，管理員在 CLUSQM_1 上打開 了應用程序活動跟蹤。因為 Activity Trace Viewer 將每個應用程序的記錄合並 在一起，所以清楚地顯示了哪些應用程序從隊列管理器斷開，哪些保持連接打開 。
下面來自 Events and Statistics 查看器的圖 7 顯示一個應用程序針對其與 隊列管理器的每一個連接都發出了斷開連接，而圖 8 顯示的應用程序還沒有發出 斷開連接。運行 Application Activity Trace 較長的時間，使管理員可以確認 是否發出過斷開連接。
圖 7. 關閉一個隊列後從隊列管理器斷開連接的應用程序
圖 8. 無法從隊列管理器斷開連接的應用程序
場景 3. 使用 Application Activity Trace 保存消息的審計跟蹤
Application Activity Trace 的另一個用途是保存關鍵消息的審計跟蹤。由 於審計跟蹤需要永久開啟 Application Activity Trace，所以盡可能如果將跟蹤 級別設置為低 LOW，以盡量減少對性能的影響。您可以在 mqat.ini 文件中調整 ActivityInterval 和 ActivityCount 參數，從而減少通過網絡發送的 Application Activity Trace 消息的數量。每個 MQI 操作產生一個活動記錄， 而且這些參數讓您可以基於時間或記錄計數阈值來配置有多少這些記錄被捆綁成 一個活動跟蹤消息。
在場景 3 中，X 公司的管理員使用 Application Activity Trace 來維護在 WebSphere MQ 集群 TESTCLUSTER 中跨三個隊列管理器的消息傳輸的審計跟蹤。 為了集中化 WebSphere MQ 集群中所有隊列管理器的 Application Activity Trace 消息的收集，您可以將 SYSTEM.ADMIN.ACTIVITY.TRACE.QUEUE 重新定義為 一個集群主題對象，從而將所有消息從 SYSTEM.ADMIN.ACTIVITY.TRACE.QUEUE 重 新路由到一個發布 / 訂閱主題。然後，所有 Application Activity Trace 記錄 將被重新路由到新定義的主題，您就可以將格式化應用程序配置為訂閱該主題， 這樣就可以集中監控它們。下面是重新路由 Activity Trace 記錄的步驟：
在 CLUSQM_1 上，定義一個集群主題來發送 Application Activity Trace 消息，如本示例中 runmqsc 命令所示：
DEFINE TOPIC(TRACETOPIC)+ TOPICSTR ('/Application/Activity/Trace')+
CLUSTER(TESTCLUSTER)
刪除 SYSTEM.ADMIN.TRACE.ACTIVITY.QUEUE 隊列，並將其重新 定義為一個別名隊列，解析為步驟 1 中所定義的新主題，如本示例中 runmqsc 所示：
DELETE QLOCAL(SYSTEM.ADMIN.TRACE.ACTIVITY.QUEUE)
DEFINE QALIAS(SYSTEM.ADMIN.TRACE.ACTIVITY.QUEUE)+
TARGTYPE(TOPIC) TARGET(TRACETOPIC)
在 CLUSQM_2 和 CLUSQM_3 上，刪除 SYSTEM.ADMIN.TRACE.ACTIVITY.QUEUE 隊列，並將其重新定義為一個別名隊列， 解析為步驟 1 中所定義的新主題，如本示例中 runmqsc 所示：
DELETE QLOCAL(SYSTEM.ADMIN.TRACE.ACTIVITY.QUEUE
DEFINE QALIAS(SYSTEM.ADMIN.TRACE.ACTIVITY.QUEUE)+
TARGTYPE(TOPIC) TARGET(TRACETOPIC)
另一種選擇是分區主題樹，在主題字符串中包括隊列管理器名稱，然後使用通 配符訂閱事件。例如，可以分別在 CLUSQM_1、CLUSQM_2 和 CLUSQM_3 上發布到 以下主題字符串：
/Application/Activity/Trace/CLUSQM_1
/Application/Activity/Trace/CLUSQM_2
/Application/Activity/Trace/CLUSQM_3
然後，訂閱應用程序就可以訂閱 /Application/Activity/Trace/* 來獲得所 有隊列管理器的 Application Activity Trace 消息，它也可以訂閱 /Application/Activity/Trace/CLUSQM_1 來只獲得 CLUSQM_1 的消息。由於已把 所有 Application Activity Trace 消息都發布到了一個中央位置，所以就更容 易跟蹤整個環境中的消息。例如，應用程序團隊通過 CLUSQM_1 將具有以下消息 ID 的消息發送到 CLUS_Q：
00000000:414D 5120 434C 5553 514D 5F31 2020 2020 'AMQ CLUSQM_1 '
00000010:FFFFFFE5FFFFFFD7 FFFFFF9951 2006 1303 '.Q ... '
他們要求確認消息已發送到哪個隊列管理器的，以及它是否已被成功放到隊列 CLUS_Q 上。使用 amqsact 格式化 Application Activity Trace 輸出，管理員 可以通過在輸出中搜索消息 ID 來驗證此信息。要想收集和格式化主題 /Application/Activity/Trace 的消息，可以使用下面的命令：
amqsact – m CLUSQM_1 – t /Application/Activity/Trace – w 30 > output_file.txt
首先，根據以下 MQPUT 記錄，管理員可以確認該消息被成功放到 CLUSQM_1 上：
MQI Operation:1 Operation Id:MQXF_PUT ApplicationTid:28 OperationDate:'2013-05-21' OperationTime:'17:05:14' High Res Time:1369152314903178 Completion Code:MQCC_OK Reason Code:0 Hobj:13676096 Put Options:8260 Msg length:1 Known_dest_count:0 Unknown_dest_count:1 Invalid_dest_count:0 Object_type:MQOT_Q Object_name:'CLUS_Q' Object_Q_mgr_name:'' Resolved_Q_Name:'CLUS_Q' Resolved_Q_mgr:'CLUSQM_3' Resolved_local_Q_name:'CLUS_Q' Resolved_local_Q_mgr:'CLUSQM_1' Resolved_type:MQOT_Q Report Options:0 Msg_type:MQMT_DATAGRAM Expiry:-1 Format_name:'MQSTR' Priority:-1 Persistence:2 Msg_id: 00000000:414D 5120 434C 5553 514D 5F31 2020 2020 'AMQ CLUSQM_1 ' 00000010:FFFFFFE5FFFFFFD7 FFFFFF9951 2006 1303 '.Q ... ' Correl_id: 00000000:0000 0000 0000 0000 0000 0000 0000 0000 '................' 00000010:0000 0000 0000 0000 '........ ' Reply_to_Q :'' Reply_to_Q_Mgr:'' Coded_char_set_id:437 Encoding:546 Put_date:'20130521' Put_time:'16051491'
您可以看到，解析所得的隊列管理器是 CLUSQM_3，所以管理員檢查消息是否 已到達 CLUSQM_3 上的 CLUS_Q。下面的跟蹤記錄證實它已到達：
MQI Operation:1 Operation Id:MQXF_PUT ApplicationTid:6 OperationDate:'2013-05-21' OperationTime:'17:05:14' High Res Time:1369152314985842 Completion Code:MQCC_OK Reason Code:0 Hobj:14459304 Put Options:272388 Msg length:1 Recs_present:0 Known_dest_count:1 Unknown_dest_count:0 Invalid_dest_count:0 Object_type:MQOT_Q Object_name:'CLUS_Q' Object_Q_mgr_name:'CLUSQM_3' Resolved_Q_Name:'CLUS_Q' Resolved_Q_mgr:'CLUSQM_3' Resolved_local_Q_name:'CLUS_Q' Resolved_local_Q_mgr:'CLUSQM_3' Resolved_type:MQOT_Q Report Options:0 Msg_type:MQMT_DATAGRAM Expiry:-1 Format_name:'MQSTR' Priority:0 Persistence:0 Msg_id: 00000000:414D 5120 434C 5553 514D 5F31 2020 2020 'AMQ CLUSQM_1 ' 00000010:FFFFFFE5FFFFFFD7 FFFFFF9951 2006 1303 '.Q ... ' Correl_id: 00000000:0000 0000 0000 0000 0000 0000 0000 0000 '................' 00000010:0000 0000 0000 0000 '........ ' Reply_to_Q :' ' Reply_to_Q_Mgr:'CLUSQM_1' Coded_char_set_id:437 Encoding:546 Put_date:'20130521' Put_time:'16051491'
這個時候，解析所得的隊列管理器和解析所得的本地隊列管理器是相同的，這 意味著，這是預期的消息最終目的地。如果將一條消息作為一個工作單元的一部 分放置，那麼在工作單元被提交之前，消息對於檢索應用程序將不可用。 Application Activity Trace 也將為提交或撤銷編寫一條消息，其操作 ID 分別 是 MQXF_CMIT 或 MQXF_BACK。要想確認放在同步點下的消息是否到達最終目的地 ，使用 Application Activity Trace 輸出來確認該消息是否已被提交或撤銷。
結束語
Application Activity Trace 特性為您提供了在隊列管理器上的 MQI 調用的詳細視圖。本文演示 Application Activity Trace 的一些用法和配置選 項，以及如何格式化和解釋 Application Activity Trace 輸出的一些示例。
致謝
作者衷心感謝 IBM 的同事 Jonathan Rumsey（高級軟件工程師，WebSphere MQ 開發）和 Mark E. Taylor（軟件開發人員，WebSphere MQ 技術戰略），感謝 他們在完成本文過程中的協助和指導。
