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, SOAPAsyncRequest, and SOAPAsyncResponse
  • 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).

  • On *NIX, use java -jar packagename.jar. You are prompted for the target directory, which defaults to your current one.
  • On Windows, 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 AppMon Agent.

AIX and z/Linux

Create the file {$MQSI_WORKPATH}/common/profiles/dtwsmbagent.sh with the following contents and change <server-address> and <dthome> as needed to fit your environment:

# !/usr/bin/sh

export DT_SERVER=<server-address>
export DT_HOME=<dthome>
# If not set then DT_AGENTNAME defaults to "WebSphere_MB"
# export DT_AGENTNAME=<agentname-prefix>

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

if [ "$MQSI_VERSION_V" = "6" ]
then
   export MQSI_USER_EXIT_PATH=${MQSI_USER_EXIT_PATH}:${DT_HOME}/agent/lib
   export MQSI_USER_EXIT_PATH64=${MQSI_USER_EXIT_PATH64}:${DT_HOME}/agent/lib64
else
   export MQSI_USER_EXIT_PATH=${MQSI_USER_EXIT_PATH}:${DT_HOME}/agent/lib64
   export MQSI_USER_EXIT_PATH32=${MQSI_USER_EXIT_PATH32}:${DT_HOME}/agent/lib
fi

Open a terminal session as user with WebSphere MB administration privileges and ensure that the Message Broker environment was set up (mqsiprofile was executed).

Stop WebSphere MB:

mqsistop <brokername>

Activate the Agent in WebSphere MB:

mqsichangebroker <brokername> -e dtwsmbagent

Start WebSphere MB:

mqsistart <brokername>

Windows

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).