The WebSphere MQ mapping is not a sensor, but closely related to the WebSphere MQ (MQSeries) Sensor. MQ 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:
- Instrument all processes of your application and run your tests.
- 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
createmqmappings tool uses the IBM PCFAgent to send the commands listed in the following table.
||Get the queue manager name and ID.|
||Get queue attributes.|
||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.
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
DEFINE CHANNEL(DYNATRACE.SVRCONN) CHLTYPE(SVRCONN) MCAUSER('<username>')
Grant the user the
display permissions for the queue manager.
setmqaut -m <queuemanager-name> -t qmgr -p <username> +connect +inq +dsp
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
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
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