WebSphere MQ mapping

The WebSphere MQ mapping is not a sensor, but closely related to the WebSphere MQ (MQSeries) SensorMQ mapping is required under the below conditions to make sure that the AppMon Server can identify which PUTs and GETs belong together.

  • Your WebSphere MQ setup has alias, remote, or cluster queues.
  • The queue name and queue manager name are included in the MQ tagging configuration.

The MQ mapping contains information about the infrastructure. For example, if there is a queue QUEUE1 and an alias queue ALIASTOQUEUE1, the MQ mapping tells the server that messages put into ALIASTOQUEUE1 can be read from QUEUE1.

You can generate MQ mapping by using a tool that obtains the required information from the queue managers and sends it to the AppMon Server. This tool is provided in the tools/createmqmappings directory of the AppMon Server installation. To use this tool, copy it to the machine that has the MQ client library installation and can query information from the queue manager. JRE 1.6 is required to run the tool.

To determine whether MQ mapping is necessary:

  1. Instrument all processes of your application and run your tests.
  2. Open the Messaging dashlet that displays all queues that are used by your application.

If any queues are missing, you did not successfully instrument all layers of your application. In this situation, MQ mapping won't help.

You can safely ignore queues that have the same PUT and GET counts. No mapping is needed for them.

Some queues might appear to have only PUTs or only GETs:

  • If the number of PUTs and GETs is not symmetric, that's another indicator that you did not instrument all layers of your application. In this situation, MQ mapping won't help.
  • If you see a queue with GETs and a corresponding queue with the same number of PUTs, select these two queues and drill down into the PurePath dashlet. If you verify that these Paths should be linked together, set up MQ mapping.

Using the MQ mappings tool

To use the createmqmappings tool, execute the createmqmappings.cmd (Windows) or createmqmappings.sh (Unix) script. The script code is provided below.

Usage: createmqmappings (-m <mq-qmgrname> | -h <mq-hostname> [-p <mq-port>] [-c <mq-channelname>] [-m <mq-qmgrname>] [-mquser <mq-user> [-mqpass <mq-pass>]])
                        -s <dt-hostname> [-ssl] [-port <dt-port>] [-user <dt-user>] [-pass <dt-pass>]

Specify <mq-qmgrname> to connect to a local queue manager.
Specify <mq-hostname> (and optionally <mq-port>, <mq-channelname>, <mq-qmgrname>) to connect to a remote queue manager.
Optionally an <mq-user> and <mq-pass> can be specified for connecting to MQ.
A password is required if a <mq-user> but no <mq-pass> is specified in the command line.
A password is required if a <dt-user> but no <dt-pass> is specified in the command line.
<dt-user> only has to have the "Web Service Interface Access" permission

Default values:
  <mq-port>         1414
  <mq-channelname>  SYSTEM.ADMIN.SVRCONN
  <dt-port>         8020 (or 8021 if "-ssl" is specified)
  <dt-user>         admin
  <dt-pass>         admin

The createmqmappings tool uses the IBM PCFAgent to send the commands listed in the following table.

Command Description
MQCMD_INQUIRE_Q_MGR Get the queue manager name and ID.
MQCMD_INQUIRE_Q Get queue attributes.
MQCMD_INQUIRE_CLUSTER_Q_MGR Get names and IDs of other queue managers in the cluster.

These commands only read from the queue manager and don't change any configuration. They are sent to the default command input queue of the queue manager, which is usually SYSTEM.ADMIN.COMMAND.QUEUE. By default, it also uses SYSTEM.DEFAULT.MODEL.QUEUE to receive replies. Those are the only two queues used.

Since the createmqmappings tool only inquires data from the queue manager, you can create a SVRCONN channel for a user that is restricted to only the minimum set of permissions.

Perform the following steps to grant the required permissions:

Create a new user that is not a member of the mqm group.

Define a server connection channel for this user by using the runmqsc command.

DEFINE CHANNEL(DYNATRACE.SVRCONN) CHLTYPE(SVRCONN) MCAUSER('<username>')

Grant the user the connect, inquire, and display permissions for the queue manager.

setmqaut -m <queuemanager-name> -t qmgr -p <username> +connect +inq +dsp

Grant the put permission for the SYSTEM.ADMIN.COMMAND.QUEUE queue. This queue is used to send the inquire commands to the queue manager.

setmqaut -m <queuemanager-name> -t q -n SYSTEM.ADMIN.COMMAND.QUEUE -p <username> +put

Grant the display and get permissions for the SYSTEM.DEFAULT.MODEL.QUEUE queue. This queue is used to receive the replies from the queue manager.

setmqaut -m <queuemanager-name> -t q -n SYSTEM.DEFAULT.MODEL.QUEUE -p <username> +dsp +get

Grant the display permissions for the ** queue wildcard. This permission allows the createmqmappings tool to read the queue definitions.

setmqaut -m <queuemanager-name> -t q -n '**' -p <username> +dsp