Installing the IBM IIB/ACE monitoring extension

This section describes how to install the IBM IIB/ACE monitoring extension on various platforms, and includes:

Before you begin
Installing the IBM IIB/ACE monitoring extension on Windows
Installation for Remote Monitoring of Integration Servers
Installing the IBM IIB/ACE monitoring extension on UNIX
Installing the IBM IIB/ACE monitoring extension on z/OS

Note

Installation of the IBM IIB/ACE monitoring extension requires an installation of IBM Integration Bus or IBM App Connect Enterprise. It may require an installation of IBM MQ. Initialize the command line environment before installing the monitoring extension (e.g. using the IBM provided "mqsiprofile" and "setmqenv" commands), or provide command line arguments as described in the following sections.

To register an IIB Integration Node using IBM MQ, use the following command: ./agentpref.sh --set com.bmc.mmpa.wmb.monitor --pref_path ComMQSoftwareWebSphereMBBroker <INTEGRATION_NODE_NAME> WMQQMgrName <QMGR_NAME>

To register an IIB Integration Node using MQTT, use the following command: ./agentpref.sh --set com.bmc.mmpa.wmb.monitor --pref_path ComMQSoftwareWebSphereMBBroker <INTEGRATION_NODE_NAME> MQTTPort <PORT>

To register an ACE Integration Node using IBM MQ, use the following command: ./agentpref.sh --set com.bmc.mmpa.wmb.monitor --pref_path ComMQSoftwareWebSphereMBBroker <INTEGRATION_NODE_NAME> WMQQMgrName <QMGR_NAME> AdminURI http://<HOSTNAME>:<PORT>

To register an ACE Integration Node using MQTT, use the following command: ./agentpref.sh --set com.bmc.mmpa.wmb.monitor --pref_path ComMQSoftwareWebSphereMBBroker <INTEGRATION_NODE_NAME> MQTTPort <PORT> AdminURI http://<HOSTNAME>:<PORT>

See here for all preferences : https://docs.bmc.com/docs/pages/viewpage.action?pageId=928605228

Before you begin

Verify in the Supported-middleware-monitoring-technologies-for-performance-and-availability section that the intended monitored technology is supported and that all footnote prerequisites are satisfied.

Note

If you are using a customized installation of IBM Integration Bus where paths (especially the Integration Node's registry paths) differ from the defaults documented by IBM, status monitoring through the IBM IIB CMP-API might not work without modifying the extension's runtime environment. In this case, providing the path to the Integration Node's registry through the MQSI_REGISTRY environment variable to the extension at runtime can solve those problems. Be aware that using individual registry paths for Integration Nodes running on the same machine can prevent the IBM IIB/ACE monitoring extension from being able to monitor multiple Integration Nodes simultaneously through one instance. In this case you might need to install and set up one instance of the extension per Integration Node to be monitored.

Installing the IBM IIB/ACE monitoring extension on Windows

To prepare the environment

Make sure you have Windows Administrator privileges when installing and running the IBM IIB/ACE monitoring extension as a Windows System Service and make sure you have the proper privileges to adjust the extension's runtime environment (see the following sections for further information).

Installation of the qpwmb monitoring extension requires a Java Runtime Environment. It will use either the agent JRE, when one is installed as a subdirectory under the <AGENT_INSTALL> directory, or the IBM IIB/ACE JRE, when defined by either the MQSI_JREPATH environment variable or -wmbjrepath provided as an argument to the extension installer.
If you are running IIB version 10 or higher in a non-MQ configuration, you can skip the following IBM MQ related steps.
- To monitor message flow and resource statistics, the extension uses the IBM MQ Java API in 32-bit bindings mode on 32-bit Integration Nodes and 64-bit bindings mode on 64-bit Integration Nodes. This requires the IBM MQ environment to be set up properly at runtime. The IBM MQ product documentation contains detailed information about how to configure the environment for applications using IBM MQ Java in bindings mode.
- Ensure that the IBM MQ 64-bit libraries occur prior to the IBM MQ 32-bit libraries in the System Path Environment Variable. It is also necessary to set the correct ordering in the wrapper.conf file (see Configuration Property files ). Note that failure to do this results in an MQRC 2495 error in the qpwmb.log and failure of the extension.
- Make sure IBM MQ is installed on the system running the extension and that its version matches the requirements and recommendations for the installed version of IBM IIB/ACE. See the IBM product documentation for further information.
  - Make sure you have the permission to inquire and administer the queue managers and IBM MQ resources involved. The extension must have the permission to connect to and to inquire the Integration Node's queue manager.
  - The extension must have the permission to put messages to the SYSTEM.BROKER.CONTROL.QUEUE to successfully subscribe to statistics messages published by the Integration Node.
  - Set the queue manager's pub/sub mode (PSMODE) to enabled for every Integration Node that is monitored.
  - Create a model queue on each Integration Node's queue manager for the extension to receive statistics messages published by the Integration Node. By default the extension assumes a model queue named QPWMB.SUBSCRIBER.MODEL.QUEUE exists. This queue must be have deftype=TEMPDYN.
  - Make sure that the following MQ environment variables are set before running the install.bat file: MQ_JAVA_INSTALL_PATH and MQ_JAVA_LIB_PATH
  - These environment variables might already be set if you have a Primary Installation of IBM MQ. If they are not set, you can set them by running the setmqenv command from bin directory of the queue manager used by the Integration Node. For example:
    
    C:\Program Files\IBM\WebSphere MQ\bin\setmqenv –n MyMQInstallationName
    
    See the related IBM IBM IIB/ACE documentation for more details on the IBM MQ setup.

To prepare the IBM Integration Bus environment

For monitoring the status and configuration of an Integration Node and its components, the extension uses the IBM Integration API (aka Configuration Manager Proxy or CMP API). The extension needs to gather these Java libraries as part of its installation process and tries detecting all the resources required from the environment.
Make sure that the account used to run the extension has the authority to access the Integration Node through the IIB CMP API, and has read access to the monitored Integration Nodes' registries.
Make sure you run IIB commands with the proper environment. Usually this means you are working from within an IIB command console or have mqsiprofile applied to your environment.
If you prefer to not run the mqsiprofile command, the environment variables can be set manually using command line options.
The install script specifically uses the following environment variables:
- MQSI_FILEPATH
- MQSI_JREPATH
- MQSI_REGISTRY
- MQSI_VERSION
In order to monitor message flow statistics or Integration server statistics, statistics collection and publishing must be turned on for every Integration Node or Integration Node component monitored.
This can be done in two ways:
- Run the mqsichangeflowstats command to enable statistics for all the components you want to monitor.
  - Examples:
  - To enable message flow statistics to be published for all message flows and all Integration Servers on an Integration Node, run:
    mqsichangeflowstats <intergrationNodeName> -s -g -j -c active -t none -n basic -o xml
  - To enable message flow statistics to be published for a specific message flow and a specific Integration Server on an Integration Node, run:
    
    mqsichangeflowstats <intergrationNodeName> -s -e <integrationServerName> -f <message_flow_name> -c active -t none -n basic -o xml
  - To disable message flow statistics, run the appropriate command from the three options above and replace -c active with -c inactive. The following command would turn off statistics for all message flows in all Integration Servers on a Integration Node:
    mqsichangeflowstats <intergrationNodeName> -s -g -j -c inactive
- Set the MessageFlowStatistics extension preference. Note that if you are upgrading from TrueSight Middleware and Transaction Monitor version 8.0.00 and you have set the com.bmc.mmpa.wmb.monitor.MessageFlowStatistics property in the com.bmc.mmpa.wmb.monitor property file, this is automatically migrated to this extension preference.
  - Examples:
  - To enable message flow statistics to be published for all message flows and all Integration Servers on an Integration Node, run:
    agentpref --set "com.bmc.mmpa.wmb.monitor" --pref_path ComMQSoftwareWebSphereMBBroker <intergrationNodeName> WMQQMgrName <qmgrname> MessageFlowStatistics 1
  - To disable message flow statistics, run the appropriate command from the three options above and replace -c active with -c inactive. The following command would turn off statistics for all message flows in all Integration Servers on a broker:
    
    agentpref –-remove-agent "com.bmc.mmpa.wmb.monitor" --pref_path ComMQSoftwareWebSphereMBBroker <intergrationNodeName> WMQQMgrName <qmgrname> MessageFlowStatistics

In order to monitor resource statistics, statistics collection and publishing must be turned on for every component monitored. This can be done in two ways:
- Run the mqsichangeresourcestats command to enable statistics for all the Integration Node components you want to monitor.
  - Examples:
  - To enable resource statistics to be published for all Integration Servers on a Integration Node, run:
    mqsichangeresourcestats <intergrationNodeName> -c active
  - To enable resource statistics to be published for a specific Integration Server on an Integration Node, run:
    
    mqsichangeresourcestats <intergrationNodeName> –e <integrationServerName> -c active
  - To disable resource statistics, run the appropriate command from the options above and replace -c active with -c inactive. The following command turns off statistics for all Integration Servers on a Integration Node:
    
    mqsichangeresourcestats <intergrationNodeName> -c inactive
- Set the MessageResourceStatistics extension preference. Note that if you are upgrading from TrueSight Middleware and Transaction Monitor version 8.0.00 and you have set the com.bmc.mmpa.wmb.monitor.MessageResourceStatistics property in the com.bmc.mmpa.wmb.monitor property file, this is automatically migrated to this extension preference.
  - Examples:
  - To enable resource statistics to be published for all Integration Servers on an Integration Node, run:
    agentpref --set "com.bmc.mmpa.wmb.monitor" --pref_path ComMQSoftwareWebSphereMBBroker <intergrationNodeName> WMQQMgrName <qmgrname> ResourceStatistics true
  - To disable resource statistics, run:
    
    agentpref --set "com.bmc.mmpa.wmb.monitor" --pref_path ComMQSoftwareWebSphereMBBroker <intergrationNodeName> WMQQMgrName <qmgrname> ResourceStatistics false
See the IBM IBM IIB/ACE documentation for more information.

To prepare the IBM App Connect Enterprise environment

For monitoring the status and configuration of an Integration Node and its components, the extension uses the IBM App Connect Enterprise Administrative REST API.
The extension needs to gather Java libraries as part of its installation process and tries detecting all the resources required from the environment.
Make sure you run ACE commands with the proper environment. Usually this means you are working from within a ACE command console or have mqsiprofile applied to your environment.
If you prefer to not run the mqsiprofile command, the environment variables can be set manually using command line options.
The install script specifically uses the following environment variables:
- MQSI_FILEPATH
- MQSI_JREPATH
- MQSI_REGISTRY
- MQSI_VERSION
An Integration Node or Integration Servers can be configured to publish statistics to either a IBM MQ queue manager or an MQTT Integration Node.
To monitor Message Flow statistics or Integration Servers statistics, statistics collection and publishing must be turned on for every component to be monitored.
Either configure the Message Flow statistics on an Integration Node using the mqsichangeflowstats command to enable statistics for all components you want to monitor. For example:
- To enable message flow statistics to be published for all message flows in all Integration Servers on an Integration Node, run:
  
  mqsichangeflowstats <node_name> -s --all-integration-servers --all-applications --all-libraries --all-flows -c active
- To enable message flow statistics to be published for a specific message flow and a specific Integration Servers on an integration node, run:
  
  mqsichangeflowstats <node_name> -s --integration-server <server_name> --application <app_name> --flow <message_flow_name> -c active
- To turn off statistics for all message flows, run:
  
  mqsichangeflowstats <node_name> -s --all-integration-servers --all-applications --all-libraries --all-flows -c inactive
Or configure the Message Flow statistics on an Integration Node in node.conf.yaml or an Integration Servers in server.conf.yaml:
- Integration Node configuration files are in the MQSI_REGISTRY\components\<node_name> directory.
- Integration Servers configuration files are in the Integration Servers work directory.
- Configuration can be applied as a sparsely populated override yaml file.
- For example, the following override enables snapshot statistics collection to the default MQ queue manager:
  
  Events:
    OperationalEvents:
      MQ:
        enabled: true
  Statistics:
    Snapshot:
      publicationOn: 'active'
      outputFormat: ‘xml’
See the IBM App Connect Enterprise documentation for more information.

To install the IBM IIB/ACE monitoring extension on Windows

Obtain the pkg_windows_qpwmb.zip file either from the AGENT_DIST directory on the MVMM Server (see Organization-of-the-AGENT_DIST-directory-on-the-server-machine) or through the Package Distribution mechanism, as described in Distributing-the-agent-and-extensions-packages-via-the-launch-page.
Extract the files from pkg_windows_qpwmb.zip into a sub-directory of the <AGENT_INSTALL> directory. The following steps assume a directory named "qpwmb" is being used.
Open a command window with the privileges to install a Windows System Service and the proper IBM MQ and IBM IIB/ACE environment set up to install the extension (see related sections above on how to prepare the IBM MQ and IBM IIB/ACE environment).
If you are running IIB version 10 or higher in an MQ configuration, make sure the Integration Node's queue manager is running and available to the extension.
Change directories to the qpwmb directory from Step 2.
To install with the defaults determined automatically from your environment run:

bin\install.bat

If you prefer to provide environment information manually, run:

bin\install.bat -mqjavainstallpath MQJAVAINSTALLPATH -wmbfilepath MQSIFILEPATH –wmbjrepath MQSIJREPATH –wmbregistrypath MQSIREGISTRYPATH –wmbversion MQSIVERSION

Note the following:
- MQJAVAVERSION is the IBM MQ version number (e.g., 7.0.1.2). This option is not required to monitor Integration Nodes that publish statistics using the MQTT transport only.
- MQJAVAINSTALLPATH is the path to the IBM MQ Java installation. This option is not required to monitor Integration Nodes that publish statistics using the MQTT transport only.
To install qpwmb as a Windows system service run:

bin\qpwmb.bat --install
Continue to the Configure the monitoring extension section.
After upgrading IBM MQ, IBM Integration Bus or IBM App Connect Enterprise you must rerun the install.sh command, as described in the following steps.

Stop the IBM IIB/ACE Monitoring Extension if it is running.
Open a command window with the proper IBM MQ and IBM IIB/ACE environment setup (see related sections above on how to prepare your environment).
Change to the qpwmb directory where the monitoring extension was installed.
Run: bin\install.bat
Start the extension.

Installation for Remote Monitoring of Integration Servers

Installation of the monitoring extension always requires a local installation of the monitored product (either IBM Integration Brokers (IIB) or IBM App Connect Enterprise (ACE)) in order to gather resources for required APIs.

In monitoring configurations using IBM MQ, a local installation of IBM MQ is also required.

When a local installation of IIB or ACE is available, monitoring of Integration Nodes is supported through extension preferences. See the extension preference documentation for details.

To monitor from an agent host where the monitored product (IIB or ACE) is not installed, first install the monitoring extension on a host where the monitored product is installed (to gather the required resources), and then move the extension to the agent host.

After installation the monitoring extension can be moved to an agent host where the monitored product is not installed. The extension install script must be run again on the monitoring agent host to configure a Java JRE location (using -wmbjrepath) and, for configurations using IBM MQ, the location of IBM MQ (using -mqjavainstallpath).

Monitoring Restrictions

The Java JRE and IBM MQ must be compatible with the Integration Nodes being monitored. Refer to IBM documentation for compatibility details. The installation and monitoring platforms must be of similar flavours (e.g. both Windows, or both Linux). Monitoring extensions must be reinstalled if IIB or ACE fixes or maintainence are applied.

Example

In the following example, "agent host" is a host with an MVMM Agent installed. "Integration Node host" is a host with either IIB or ACE installed, but no MVMM Agent.

Sample commands shown are intentionally simplified. Variations may be required for different platforms, product versions and specific configuration requirements.

The MVMM Monitoring Extension for IBM IIB/ACE should have already been distributed to the agent host using the preferred package distribution mechanism.

Transfer the monitoring extension package (For example, "pkg_windows_qpwmb.zip") from the agent host to the Integration Node host. Ensure transfers are done as binary files, if that is relevant to the transfer mechanism used.

Example

If you have installed Fix Pack 9.0.00.A or later
If you have not installed Fix Pack 9.0.00.A or later

On the Integration Node host, first setup the command line environment ...

> setmqenv -s
> \path\to\IIB\server\bin\mqsiprofile

Note that "setmqenv" is only required for monitoring configurations that require IBM MQ.

Then extract and install the monitoring into a convenient directory on the Integration Node host ...

> mkdir qpwmb
> cd qpwmb
> unzip pkg_qpwmb_windows.zip
> bin\install.sh
> cd ..
> zip -r qpwmb_installed_windows.zip qpwmb

Transfer the installed monitoring extension package (e.g. "qpwmb_installed_windows.zip") from the Integration Node host to the agent
host. Ensure transfers are done as binary files, if that is relevant to the transfer mechanism used.

On the agent host, extract the monitoring extension ...

> unzip qpwmb_installed_windows.zip
> cd qpwmb

run the extension installer to relocate the JRE and the MQ java path ...

> bin\install.sh -wmbjrepath \path\to\compatibile\JRE -mqjavainstallpath \path\to\ibm\mq\java

Note that "mqjavainstallpath" is only required for monitoring configurations that require IBM MQ.

The monitoring extension can now be started and configured to monitor a remote Integration Node using extension preferences.

The following examples show minimal preferences that should be set to monitor IIB or ACE in various configurations.

To monitor an IIB Integration Node that published monitoring information via MQTT ...

> agentpref --set com.bmc.mmpa.wmb.monitor --pref_path ComMQSoftwareWebSphereMBBroker IIB_MQ_REMOTE CMPAPIHostName broker-host-name CMPAPIPort 4414 MQTTHostName mqtt-host-name MQTTPort 11886

To monitor an IIB Integration Node that publishes monitoring information via IBM MQ...

> agentpref --set com.bmc.mmpa.wmb.monitor --pref_path ComMQSoftwareWebSphereMBBroker IIB_MQTT_REMOTE CMPAPIHostName broker-host-name CMPAPIPort 4414 WMQHostName mq-host-name WMQPort 1234 WMQQMgrName REMOTE
WMQChannelName channel

To monitor an ACE Intergration Node that published monitoring information via MQTT ...

> agentpref --set com.bmc.mmpa.wmb.monitor --pref_path ComMQSoftwareWebSphereMBBroker ACE_MQ_REMOTE AdminURI http://broker-host-name:4414 MQTTHostName mqtt-host-name MQTTPort 11886

To monitor an ACE Intergration Node that publishes monitoring information via IBM MQ...

> agentpref --set com.bmc.mmpa.wmb.monitor --pref_path ComMQSoftwareWebSphereMBBroker ACE_MQTT_REMOTE AdminURI http://broker-host-name:4414 WMQHostName mq-host-name WMQPort 1234 WMQQMgrName REMOTE
WMQChannelName channel

On the Integration Node host, first setup the command line environment ...

> setmqenv -s
> \path\to\IIB\server\bin\mqsiprofile

Note that "setmqenv" is only required for monitoring configurations that require IBM MQ.

Then extract and install the monitoring into a convenient directory on the Integration Node host ...

> mkdir qpwmb
> cd qpwmb
> unzip pkg_qpwmb_windows.zip
> bin\install.sh
> cd ..
> zip -r qpwmb_installed_windows.zip qpwmb

On the agent host, extract the monitoring extension ...

> unzip qpwmb_installed_windows.zip
> cd qpwmb

... make a copy of the existing bundles ...

> cp -r bundles bundles_backup

... and run the extension installer to relocate the JRE and the MQ java path ...

> bin\install.sh -wmbjrepath \path\to\compatibile\JRE -mqjavainstallpath \path\to\ibm\mq\java

Note that "mqjavainstallpath" is only required for monitoring configurations that require IBM MQ.

Finally, restore one of the original bundles ...

> cp bundles_backup/com.bmc.com.ibm.wmb.jar bundles