IBM Integration Bus Agent

The enterprise service bus IBM Integration Bus (version 9 going forward) was formerly known as WebSphere Message Broker (up to version 8).

The IBM Integration Bus Agent is integrated using a user exit library (.lel) file that must be registered in the IBM Integration Bus installation.

IBM Integration Bus PurePath

When looking at a IBM Integration Bus PurePath, the PurePath nodes reflect the following information:

  • Node Type = Class Name
  • Node Name = Method Name
  • Message Flow = API

The default Agent name is Websphere_MB[<qmgr>-<broker>-< execgrp>]. To change the prefix to something other than Websphere_MB, set the environment variable DT_AGENTNAME.

Supported protocols

Tagging requests is supported for the following protocols / node types:

  • HTTP: on the node types HTTPInput, HTTPReply, HTTPRequest, SOAPInput, SOAPReply, SOAPRequest
  • JMS: on the node types JMSInput, JMSOutput, JMSReply, MQInput, and MQOutput
  • MQ: on the node types MQInput and MQOutput. Currently MQ tagging is only supported within the IBM Integration Bus Agent. Only MQ messages that are put into a queue by IBM Integration Bus and are read by IBM Integration Bus are tagged.

Installation

Install the AppMon Agent package using the appropriate command (based on your OS) to the machine running the System under Diagnosis (SUD).

Select the installation type WebSphere MB to install only the WebSphere Message Broker Agent. With the full Windows installation package, choose installation type Custom and ensure that the installation of the WebSphere Message Broker Agent is enabled.

Make sure that the AppMon Server is running before deploying the Agent.

Create the file %MQSI_WORKPATH%\common\profiles\dtwsmbagent.cmd with the following contents and change <server-address> and <dthome> for your environment:

@echo off
set DT_SERVER=<server-address>
set DT_HOME=<dthome>
rem If not set, DT_AGENTNAME defaults to "WebSphere_MB"
rem SET DT_AGENTNAME=<agentname-prefix>

rem Per default, store the PurePath id in variables/dynaTrace-tag
rem To store it in the Message Broker's environment, set variable name/path. For example:
rem set DT_WSMBTAGPATH=dynaTrace/pathId

set MQSI_USER_EXIT_PATH=%MQSI_USER_EXIT_PATH%;%DT_HOME%\agent\lib

Open the WebSphere MB Command Console (Start > Programs > IBM WebSphere Message Broker 2017 May > Command Console).

Stop WebSphere MB:

mqsistop <brokername>

Activate the Agent in WebSphere MB:

mqsichangebroker <brokername> -e dtwsmbagent

Start WebSphere MB:

mqsistart <brokername>

Instrumenting a specific Execution Group only

If you want to implement the Agent on just the execution group and not the broker, use the following syntax.

Note

Follow the previous steps and only use this if you want to instrument the execution group only.

Postscript: set broker active on a certain execution group by using mqsichangeflowuserexits:

mqsichangebroker <broker> [-x <path to libdtagent.lel>]
mqsichangeflowuserexits <broker> -e <ExecutionGroup> -a dtwsmbagent

Removing the Agent

To remove the Agent from a Message Broker installation, first disable the dtwsmbagent user exit. This can be done by setting a list of active user exits that does not contain dtwsmbagent.
To disable all user exits, specify an empty list as follows (it has to be executed while the broker is not running):

mqsichangebroker <brokername> -e ""

After disabling the user exit, the Agent is not used anymore but is still loaded by the Message Broker. To avoid this, remove the Agent from the user exit path by removing the dtwsmbagent.sh script (on *NIX) or .cmd script (on Windows).