こんにちは。日本アイ・ビー・エム Automation テクニカル・セールスの岩品です。
Instana Advent Calendar ３日目は、IBM MQの分散トレーシングについて記載したいと思います。
Javaのアプリケーションであれば、Instanaエージェントを導入するだけで、自動的にInstrumentation（計装）されますが、MQでは少し設定が必要です。それほど手間な手順ではないので、順を追って見ていきたいと思います。
検証環境の準備
今回の環境には RHEL8.9 と IBM MQ 9.3.4.0 が導入されいてます。
[root@itz-3100008gyq-smfw ~]# cat /etc/redhat-release
Red Hat Enterprise Linux release 8.9 (Ootpa)
[root@itz-3100008gyq-smfw bin]# /opt/mqm/bin/dspmqver
Name: IBM MQ
Version: 9.3.4.0
Level: p934-L230927
BuildType: IKAP - (Production)
Platform: IBM MQ for Linux (x86-64 platform)
Mode: 64-bit
O/S: Linux 4.18.0-477.27.1.el8_8.x86_64
O/S Details: Red Hat Enterprise Linux 8.9 (Ootpa)
InstName: Installation1
InstDesc:
Primary: No
InstPath: /opt/mqm
DataPath: /var/mqm
MaxCmdLevel: 934
LicenseType: Production
ReleaseType: Continuous Delivery (CD)
mqmユーザーにsuし、IBM MQにおいて Queue Managerを作成します
[mqm@itz-3100008gyq-smfw ~]$ /opt/mqm/bin/crtmqm TESTQM
IBM MQ queue manager 'TESTQM' created.
Directory '/var/mqm/qmgrs/TESTQM' created.
The queue manager is associated with installation 'Installation1'.
Creating or replacing default objects for queue manager 'TESTQM'.
Default objects statistics : 83 created. 0 replaced. 0 failed.
Completing setup.
Setup completed.
Queue Manager を起動し、テスト用のキューを作成します
[mqm@itz-3100008gyq-smfw ~]$ /opt/mqm/bin/strmqm TESTQM
The system resource RLIMIT_NOFILE is set at an unusually low level for IBM MQ.
IBM MQ queue manager 'TESTQM' starting.
The queue manager is associated with installation 'Installation1'.
6 log records accessed on queue manager 'TESTQM' during the log replay phase.
Log replay for queue manager 'TESTQM' complete.
Transaction manager state recovered for queue manager 'TESTQM'.
Plain text communication is enabled.
IBM MQ queue manager 'TESTQM' started using V9.3.4.0.
[mqm@itz-3100008gyq-smfw ~]$
[mqm@itz-3100008gyq-smfw ~]$ /opt/mqm/bin/runmqsc TESTQM
5724-H72 (C) Copyright IBM Corp. 1994, 2023.
Starting MQSC for queue manager TESTQM.
DEFINE QLOCAL(TESTQ)
1 : DEFINE QLOCAL(TESTQ)
AMQ8006I: IBM MQ queue created.
end
2 : end
1 MQSC commands read.
No commands have a syntax error.
All valid MQSC commands were processed.
Instana Agentの導入
Instana エージェントを導入します。
１行インストールができるので、数分で導入完了します。
[root@itz-3100008gyq-smfw ~]# curl -o setup_agent.sh https://setup.instana.io/agent && chmod 700 ./setup_agent.sh && sudo ./setup_agent.sh -a xxxxxxxxxxxxxxxxx -d xxxxxxxxxxxxx-t dynamic -e ingress-orange-saas.instana.io:443
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 24158 100 24158 0 0 17921 0 0:00:01 0:00:01 --:--:-- 17921
Setting up the dynamic Instana agent for Linux
Are you sure? [y/N] y
Setting up Instana RPM repository
Updating YUM metadata
Installing Instana agent
GPG 鍵 0x31933E68 をインポート中:
Userid : "stan@instana.com <stan@instana.com>"
Fingerprint: 386F 852E 8B64 01EB 34FD 86E8 6AA7 718D 3193 3E68
From : https://packages.instana.io/Instana.gpg
Instana agent service is active and agent is reinstalled. Service will be restarted
[root@itz-3100008gyq-smfw ~]#
[root@itz-3100008gyq-smfw ~]# systemctl status instana-agent
● instana-agent.service - "Instana(tm) agent."
Loaded: loaded (/usr/lib/systemd/system/instana-agent.service; enabled; vendor preset: disabled)
Drop-In: /etc/systemd/system/instana-agent.service.d
└─agent-custom-start.conf, custom-environment.conf
Active: active (running) since Thu 2023-11-30 19:02:44 CST; 20min ago
...
Instana の画面を開いて確認してみます。このタイミングでは、また プロセスとしては認識されていますが、MQとしては検知されていません。必要な設定をしていきましょう。
Instana による Queue Managerのメトリック監視
ここでは、Instanaエージェントと Queue Managerが 同じノードで稼働しているので、MQのバインディング・モードで Queue Manager に接続して監視を行います。このためには、Instanaの稼働ユーザー(root）が、mqmグループに所属している必要があります。
Instana 稼働ユーザーの mqmグループへの登録
以下のコマンドで、rootを mqmグループに追加します
[root@itz-3100008gyq-smfw ~]# usermod -G mqm root
Queue Manager を再起動します
[mqm@itz-3100008gyq-smfw ~]$ /opt/mqm/bin/endmqm TESTQM
Quiesce request accepted. The queue manager will stop when all outstanding work
is complete.
[mqm@itz-3100008gyq-smfw ~]$ /opt/mqm/bin/strmqm TESTQM
The system resource RLIMIT_NOFILE is set at an unusually low level for IBM MQ.
IBM MQ queue manager 'TESTQM' starting.
The queue manager is associated with installation 'Installation1'.
6 log records accessed on queue manager 'TESTQM' during the log replay phase.
Log replay for queue manager 'TESTQM' complete.
Transaction manager state recovered for queue manager 'TESTQM'.
Plain text communication is enabled.
IBM MQ queue manager 'TESTQM' started using V9.3.4.0.
Instanaの agent.log を確認してみます。ローカル・バインディングモードでQueue Managerに接続していることが確認できます。
[mqm@itz-3100008gyq-smfw ~]$ tail -f /opt/instana/agent/data/log/agent.log
・・・
2023-11-30T20:41:20.893-06:00 | INFO | e95-c863-4e8c-ace8-24a45a915ed3) | IbmMq | com.instana.sensor-ibmmq - 1.1.14 | Activated Sensor for local queue manager TESTQM-itz-3100008gyq-smfw.dte.demo.ibmcloud.com with pid: 60665, libPath: /opt/mqm/java/lib64
2023-11-30T20:41:20.976-06:00 | INFO | e95-c863-4e8c-ace8-24a45a915ed3) | IbmMqClient | com.instana.sensor-ibmmq - 1.1.14 | Running env: VM
2023-11-30T20:41:21.055-06:00 | INFO | e95-c863-4e8c-ace8-24a45a915ed3) | IbmMqClient | com.instana.sensor-ibmmq - 1.1.14 | Connected to TESTQM in local binding mode.
2023-11-30T20:41:21.267-06:00 | INFO | 443-3151-4ab2-b2d3-dd28e408df15) | Process | com.instana.sensor-process - 1.1.48 | Activated Sensor for PID 60665
2023-11-30T20:41:21.467-06:00 | INFO | instana-scheduler-thread-3-4 | IbmMqClient | com.instana.sensor-ibmmq - 1.1.14 | Connected to TESTQM in local binding mode.
Instanaのコンソールからも IBM MQのメトリックが確認できます。
Instanaで取得される IBM MQのメトリックの一覧はこちらをご参照ください。
Instana による Queue Managerの分散トレーシングによるサービス監視
次に Queue Managerで PUT/GETされたメッセージが確認できるように、分散トレーシングの設定を行っていきます。
Instanaでは、IBM MQのUser Exitを用いて、この分散トレーシングを実現しています。これを有効化するためには、
１） UserExitパッケージの取得と配置
２） UserExitパッケージの有効化
の２つが必要となります。
1) UserExitパッケージの取得と配置
製品ドキュメント上に記載されたリンクから、UserExitパッケージをダウンロードします。この取得には、Instanaの有効なライセンスキーが必要となります。
ダウンロードしてきた、UserExitパッケージを解凍します。
[root@itz-3100008gyq-smfw mq_userexit]# ls
instana-ibmmq-tracing-userexit-3.1.7-bin.tar.gz
[root@itz-3100008gyq-smfw mq_userexit]# gunzip instana-ibmmq-tracing-userexit-3.1.7-bin.tar.gz
[root@itz-3100008gyq-smfw mq_userexit]# tar -xvf instana-ibmmq-tracing-userexit-3.1.7-bin.tar
ibm-mq-tracing-exits-2023.4.0/
ibm-mq-tracing-exits-2023.4.0/ibm-mq-tracing-exits_pLinuxle_64bit.tar.gz
ibm-mq-tracing-exits-2023.4.0/ibm-mq-tracing-exits_win_64bit.zip
ibm-mq-tracing-exits-2023.4.0/ibm-mq-tracing-exits_aix_64bit.tar.gz
ibm-mq-tracing-exits-2023.4.0/ibm-mq-tracing-exits_zLinux_64bit.tar.gz
ibm-mq-tracing-exits-2023.4.0/ibm-mq-tracing-exits_xLinux_64bit.tar.gz
今回はIA環境ですのでxLiux用のUserExitモジュールを /var/mqm/exits64/に配置し、mqmユーザーにownerを変更します
[root@itz-3100008gyq-smfw ibm-mq-tracing-exits-2023.4.0]# cp ibm-mq-tracing-exits_xLinux_64bit.tar /var/mqm/exits64/
[root@itz-3100008gyq-smfw ibm-mq-tracing-exits-2023.4.0]# chown mqm:mqm /var/mqm/exits64/ibm-mq-tracing-exits_xLinux_64bit.tar
[root@itz-3100008gyq-smfw ibm-mq-tracing-exits-2023.4.0]# su - mqm
最終ログイン: 2023/11/30 (木) 22:32:04 CST日時 pts/0
[mqm@itz-3100008gyq-smfw ~]$ cd /var/mqm/exits64/
[mqm@itz-3100008gyq-smfw exits64]$ ls -ltr
total 8276
drwxrwsr-x. 2 mqm mqm 4096 Nov 30 19:29 Installation1
-rw-r-----. 1 mqm mqm 8468480 Nov 30 22:33 ibm-mq-tracing-exits_xLinux_64bit.tar
[mqm@itz-3100008gyq-smfw exits64]$ tar -xvf ibm-mq-tracing-exits_xLinux_64bit.tar
mqtracingexit.conf
mqtracingexit_r
tracelibrary.so
[mqm@itz-3100008gyq-smfw exits64]$ rm ibm-mq-tracing-exits_xLinux_64bit.tar
[mqm@itz-3100008gyq-smfw exits64]$ ls -ltr
total 16548
-rwxr-xr-x. 1 mqm mqm 787024 Oct 17 19:54 mqtracingexit_r
-rwxr-xr-x. 1 mqm mqm 7672560 Oct 17 20:12 tracelibrary.so
-rw-rw-r--. 1 mqm mqm 2054 Oct 17 20:12 mqtracingexit.conf
drwxrwsr-x. 2 mqm mqm 4096 Nov 30 19:29 Installation1
[mqm@itz-3100008gyq-smfw exits64]$ cat mqtracingexit.conf
# IBM MQ Tracing user exit build 202310180053
# The configuration items for IBM MQ Tracing user exit 2023.4.0
LOG_LEVEL="info" # The log level of the tracing user exit, which can be set to info, warn, error, or debug. The default value is info.
SPAN_FORMAT="instana" # The trace system to which the span data is sent. The default value is instana. No need to change.
MONITOR_LEVEL="normal" # The tracing level of the queue manager(s), which can be set to off, quiet, normal, or debug. The default value is normal.
#IBMMQ_DEST_MONITOR_LEVEL_OFF = "" # The regex for message destinations with MONITOR_LEVEL(tracing level) off, for example: "^TMPQ.*". An example for multiple conditions: "^SYSTEM\\.AUTH\\..*|^TEMP\\.QUEUE\\..*".
#IBMMQ_DEST_MONITOR_LEVEL_QUIET = "" # The regex for message destinations with MONITOR_LEVEL(tracing level) quiet.
#IBMMQ_DEST_MONITOR_LEVEL_NORMAL = "" # The regex for message destinations with MONITOR_LEVEL(tracing level) normal.
#IBMMQ_DEST_MONITOR_LEVEL_DEBUG = "" # The regex for message destinations with MONITOR_LEVEL(tracing level) debug.
#IBMMQ_PUBSUB_SUPPORT = "off" # The switch for the pubsub support, which can be set to on or off. The default value is off.
#IBMMQ_RFH2_HEADERS_TO_EXPOSE = "" # A list of message headers that should be included in the span payload, with each header separated by commas.
#INSTANA_AGENT_HOST = "localhost" # The Instana agent host, localhost will be used by default.
#INSTANA_AGENT_PORT = 42699 # The Instana agent port, 42699 will be used by default.
#INSTANA_AGENT_PROTO = "http" # The connection type between mq tracing exit and instana agent; http and https are supported; http will be used by default.
#HOST_ALIAS="<YOUR-HOST-NAME>" # The host name to match with instana agent configuration.yaml.
#LOCAL_SOURCE_ADDRESS = "" # The local source ip address for outgoing traffic; if not specified, a local address will be automatically allocated by default.
2) UserExitパッケージの有効化
MQの初期化ファイルで UserExitを有効化します。
今回は、すべてのQueue Managerに対して有効化することも、特定のQueue Managerに対してのみ有効化することもいずれも可能です。
ここでは、 すべての Queue Managerに対して有効化するため、 /var/mqm/mqs.ini を編集していきます。
[mqm@itz-3100008gyq-smfw exits64]$ cd /var/mqm
[mqm@itz-3100008gyq-smfw ~]$ ls
config conv errors exits exits64 log mqclient.ini mqft mqs.ini qmgrs service.env shared sockets trace web
[mqm@itz-3100008gyq-smfw ~]$ cp -p mqs.ini mqs.ini.backup
[mqm@itz-3100008gyq-smfw ~]$ vi mqs.ini
[mqm@itz-3100008gyq-smfw ~]$ cat mqs.ini
#********************************************************************#
#* *#
#* <copyright *#
#* notice="lm-source-program" *#
#* pids="" *#
#* years="1994,2016" *#
#* crc="3878781346" > *#
#* Licensed Materials - Property of IBM *#
#* *#
#* *#
#* *#
#* (C) Copyright IBM Corp. 1994, 2016 All Rights Reserved. *#
#* *#
#* US Government Users Restricted Rights - Use, duplication or *#
#* disclosure restricted by GSA ADP Schedule Contract with *#
#* IBM Corp. *#
#* </copyright> *#
#* *#
#********************************************************************#
#***********************************************************************#
#* Module Name: mqs.ini *#
#* Type : IBM MQ Machine-wide Configuration File *#
#* Function : Define IBM MQ resources for an entire machine *#
#* *#
#***********************************************************************#
#* Notes : *#
#* 1) This is the installation time default configuration *#
#* *#
#***********************************************************************#
AllQueueManagers:
#********************************************************************#
#* The path to the qmgrs directory, below which queue manager data *#
#* is stored *#
#********************************************************************#
DefaultPrefix=/var/mqm
LogDefaults:
LogDefaultPath=/var/mqm/log
QueueManager:
Name=TESTQM
Prefix=/var/mqm
Directory=TESTQM
InstallationName=Installation1
ApiExitCommon:
Sequence=100
Function=EntryPoint
Module=/var/mqm/exits64/mqtracingexit
Name=TracingApiExit
[mqm@itz-3100008gyq-smfw ~]$
以上で設定は終了です。Queue Managerを起動します。
[mqm@itz-3100008gyq-smfw ~]$ /opt/mqm/bin/strmqm TESTQM
The system resource RLIMIT_NOFILE is set at an unusually low level for IBM MQ.
IBM MQ queue manager 'TESTQM' starting.
The queue manager is associated with installation 'Installation1'.
6 log records accessed on queue manager 'TESTQM' during the log replay phase.
Log replay for queue manager 'TESTQM' complete.
Transaction manager state recovered for queue manager 'TESTQM'.
Plain text communication is enabled.
IBM MQ queue manager 'TESTQM' started using V9.3.4.0.
IBM MQ 分散トレーシングの確認
IBM MQに同梱されているサンプルプログラム amqsput/amqsget を使って、TESTQMのTESTQにメッセージをPUT/GETして、分散トレーシングの挙動を確認したいと思います。
[mqm@itz-3100008gyq-smfw ~]$ /opt/mqm/samp/bin/amqsput TESTQ TESTQM
Sample AMQSPUT0 start
target queue is TESTQ
message1
Sample AMQSPUT0 end
[mqm@itz-3100008gyq-smfw ~]$ /opt/mqm/samp/bin/amqsget TESTQ TESTQM
Sample AMQSGET0 start
message <message1>
^C
[mqm@itz-3100008gyq-smfw ~]$
メッセージのPUTとGETができました。Instanaのコンソールで確認してみます。
以下の通り、要求が２件確認できます。エンドポイントとしてキューが表示されています。
この 要求を選択し、「分析で表示」してみます。PUT/GET それぞれの要求が確認できます
さらに詳細を確認してみます。amqsputコマンドでメッセージをPUTしてから、amqsputコマンドでGETするまでに8.49秒掛かっている状況がはあくできます。またメッセージにフォーカスをあわせると、MQMヘッダーの情報を確認することができます。
まとめ
以上で、Instana によるIBM MQの監視のための設定と挙動確認は終了です。
いかがでしたでしょうか。IBM MQに関しても思ったよりも簡単な設定で 可視化が可能となることが確認できたと思います。実際に処理されるメッセージの個々の応答性能や、各種Queue ManagerやQueueの各種メトリックがリアルタイムで把握できることで、IBM MQ環境の運用がより容易になるイメージを掴んでいただけていれば幸いです。