AppDynamics Monitoring Extension for use with IBM WebSphere MQ

Use case

Websphere MQ, formerly known as MQ (message queue) series, is an IBM standard for program-to-program messaging across multiple platforms.

The WebSphere MQ monitoring extension can monitor multiple queues managers and their resources, namely queues, topics, channels and listeners The metrics are extracted out using the PCF command messages.

The metrics for queue manager, queue, topic, channel and listener can be configured.

The MQ Monitor currently supports IBM Websphere MQ version 7.x, 8.x and 9.x.

Prerequisites

Before the extension is installed, the prerequisites mentioned here need to be met. Please do not proceed with the extension installation if the specified prerequisites are not met.
Download and install Apache Maven which is configured with Java 8 to build the extension artifact from source. You can check the java version used in maven using command mvn -v or mvn --version. If your maven is using some other java version then please download java 8 for your platform and set JAVA_HOME parameter before starting maven.

If this extension is configured for CLIENT transport type

Please make sure the MQ's host and port is accessible.
Credentials of user with correct access rights would be needed in config.yml (Access Permissions section).
If the hosting OS for IBM MQ is Windows, Windows user credentials will be needed.

Dependencies

The extension has a dependency on the following jar's depending on IBM MQ version:

v8.0.0 and above

com.ibm.mq.allclient.jar

For other versions

com.ibm.mq.commonservices.jar
com.ibm.mq.jar
com.ibm.mq.jmqi.jar
com.ibm.mq.headers.jar
com.ibm.mq.pcf.jar
dhbcore.jar
connector.jar

These jar files are typically found in /opt/mqm/java/lib on a UNIX server but may be found in an alternate location depending upon your environment.

In case of CLIENT transport type, IBM MQ Client must be installed to get the MQ jars. To download IBM MQ Client jars, see here

Installation

To build from source, clone this repository using git clone <repoUrl> command.
Create a lib folder in "websphere-mq-monitoring-extension" and copy the following jars in the websphere-mq-monitoring-extension/lib folder. (These jars are shipped with your Websphere MQ product itself)

For MQ v8.0.0 and above

com.ibm.mq.allclient.jar

For other versions, please comment the "com.ibm.mq.allclient" dependency in pom.xml and uncomment the following dependencies. Then add these dependencies in websphere-mq-monitoring-extension/lib folder

com.ibm.mq.commonservices.jar
com.ibm.mq.jar
com.ibm.mq.jmqi.jar
com.ibm.mq.headers.jar
com.ibm.mq.pcf.jar
dhbcore.jar
connector.jar

Run mvn clean install from websphere-mq-monitoring-extension directory. This will produce a WMQMonitor-<version>.zip in target directory.
Unzip contents of WMQMonitor-<version>.zip file and copy to "<MachineAgentHome_Dir>/monitors" directory.
Please place the extension in the Please place the extension in the "monitors" directory of your Machine Agent installation directory. Do not place the extension in the "extensions" directory of your Machine Agent installation directory.
There are two transport modes in which this extension can be run
- Binding : Requires WMQ Extension to be deployed in machine agent on the same machine where WMQ server is installed.
- Client : In this mode, the WMQ extension is installed on a different host than the IBM MQ server. Please install the IBM MQ Client for this mode to get the necessary jars as mentioned previously.

Edit the classpath element in WMQMonitor/monitor.xml with the path to the required jar files.

 <classpath>websphere-mq-monitoring-extension.jar;/opt/mqm/java/lib/com.ibm.mq.allclient.jar</classpath>

OR

 <classpath>websphere-mq-monitoring-extension.jar;/opt/mqm/java/lib/com.ibm.mq.jar;/opt/mqm/java/lib/com.ibm.mq.jmqi.jar;/opt/mqm/java/lib/com.ibm.mq.commonservices.jar;/opt/mqm/java/lib/com.ibm.mq.headers.jar;/opt/mqm/java/lib/com.ibm.mq.pcf.jar;/opt/mqm/java/lib/connector.jar;/opt/mqm/java/lib/dhbcore.jar</classpath>

If you plan to use Client transport type, create a channel of type server connection in each of the queue manager you wish to query.
Edit the config.yml file. An example config.yml file follows these installation instructions.
Restart the Machine Agent.

Configuration

Note : Please make sure to not use tab (\t) while editing yaml files. You may want to validate the yaml file using a yaml validator Configure the monitor by editing the config.yml file in /monitors/WMQMonitor/.

Configure the metricPrefix with the <TIER_ID under which this extension metrics need to be reported. For example
```
 metricPrefix: "Server|Component:100|Custom Metrics|WebsphereMQ|"
```

More details around metric prefix can be found here.

Each queueManager requires 9 threads to fetch its metrics concurrently and 1 main thread to run the extension. So if for example, there are 2 queueManagers configured, please set the numberOfThreads to be 19 (2*9+1)
```
 numberOfThreads: 20
```

Configure the queueManages with appropriate fields and filters. Below sample consists of 2 queueManagers.

 queueManagers:
   - displayName: ""
     # displayName (optional). This will be your QM name that will show up in AppD metric path. If empty, name (below) will show up.
     host: "192.168.57.104"
     port: 1414
     #Actual name of the queue manager
     name: "TEST_QM_1"
     #Channel name of the queue manager
     channelName: "SYSTEM.ADMIN.SVRCONN"
     #The transport type for the queue manager connection, the default is "Bindings" for a binding type connection
     #For bindings type connection WMQ extension (i.e machine agent) need to be on the same machine on which WebbsphereMQ server is running
     #for client type connection change it to "Client".
     transportType: "Client"
     ##for user access level, please check "Access Permissions" section on the extensions page, no need to provide credentials in case of bindings transport type, it is only applicable for client type
     username: "hello"
     password: "hello"

     #This is the timeout on queue metrics threads.Default value is 20 seconds. No need to change the default
     #Unless you know what you are doing.
     #queueMetricsCollectionTimeoutInSeconds: 20
     #channelMetricsCollectionTimeoutInSeconds: 20
     #topicsMetricsCollectionTimeoutInSeconds: 20
     
     queueFilters:
         #An asterisk on its own matches all possible names.
         include: ["*"]
         #exclude all queues that starts with SYSTEM or AMQ.
         exclude:
            - type: "STARTSWITH"
              values: ["SYSTEM","AMQ"]

     channelFilters:
         #An asterisk on its own matches all possible names.
         include: ["*"]
         #exclude all queues that starts with SYSTEM.
         exclude:
            - type: "STARTSWITH"
              values: ["SYSTEM"]
     listenerFilters:
         #Can provide complete channel name or generic names. A generic name is a character string followed by an asterisk (*),
         #for example ABC*, and it selects all objects having names that start with the selected character string.
         #An asterisk on its own matches all possible names.
         include: ["*"]
         exclude:
            #type value: STARTSWITH, EQUALS, ENDSWITH, CONTAINS
            - type: "STARTSWITH"
            #The name of the queue or queue name pattern as per queue filter, comma separated values
              values: ["SYSTEM"]
 
     topicFilters:
         # For topics, IBM MQ uses the topic wildcard characters ('#' and '+') and does not treat a trailing asterisk as a wildcard
         # https://www.ibm.com/support/knowledgecenter/en/SSFKSJ_7.5.0/com.ibm.mq.pla.doc/q005020_.htm
         include: ["#"]
         exclude:
              #type value: STARTSWITH, EQUALS, ENDSWITH, CONTAINS
            - type: "STARTSWITH"
              #The name of the queue or queue name pattern as per queue filter, comma separated values
              values: ["SYSTEM","$SYS"]

   - host: "102.138.37.105"
     port: 1414
     #Actual name of the queue manager
     name: "TEST_QM_2"
     #Channel name of the queue manager
     channelName: "SYSTEM.ADMIN.SVRCONN"
     #The transport type for the queue manager connection, the default is "Bindings" for a binding type connection
     #For bindings type connection WMQ extension (i.e machine agent) need to be on the same machine on which WebbsphereMQ server is running
     #for client type connection change it to "Client".
     transportType: "Client"
     ##for user access level, please check "Access Permissions" section on the extensions page, no need to provide credentials in case of bindings transport type, it is only applicable for client type
     username: "hello"
     password: "hello"
     #This is the timeout on queue metrics threads.Default value is 20 seconds. No need to change the default
     #Unless you know what you are doing.
     queueMetricsCollectionTimeoutInSeconds: 20

     queueFilters:
         #Matches all queues  that starts with TACA..
         include: ["TACA*"]
         #exclude all queues that starts with SYSTEM or AMQ.
         exclude:
            - type: "STARTSWITH"
              values: ["SYSTEM","AMQ"]

     channelFilters:
         #An asterisk on its own matches all possible names.
         include: ["*"]
         #exclude all queues that starts with SYSTEM.
         exclude:
            - type: "STARTSWITH"
              values: ["SYSTEM"]

The below metrics are configured by default. Metrics that are not required can be commented out or deleted.

mqMetrics:
  # This Object will extract queue manager metrics
  - metricsType: "queueMgrMetrics"
    metrics:
      include:
        - Status:
            alias: "Status"
            ibmConstant: "com.ibm.mq.constants.CMQCFC.MQIACF_Q_MGR_STATUS"
        - ConnectionCount:
            alias: "ConnectionCount"
            ibmConstant: "com.ibm.mq.constants.CMQCFC.MQIACF_CONNECTION_COUNT"
      
  # This Object will extract queue metrics
  - metricsType: "queueMetrics"
    metrics:
      include:
        - MaxQueueDepth:
            alias: "Max Queue Depth"
            ibmConstant: "com.ibm.mq.constants.CMQC.MQIA_MAX_Q_DEPTH"
            ibmCommand: "MQCMD_INQUIRE_Q"
          
        - CurrentQueueDepth:
            alias: "Current Queue Depth"
            ibmConstant: "com.ibm.mq.constants.CMQC.MQIA_CURRENT_Q_DEPTH"
            ibmCommand: "MQCMD_INQUIRE_Q"
          
        - OpenInputCount:
            alias: "Open Input Count"
            ibmConstant: "com.ibm.mq.constants.CMQC.MQIA_OPEN_INPUT_COUNT"
            ibmCommand: "MQCMD_INQUIRE_Q"
          
        - OpenOutputCount:
            alias: "Open Output Count"
            ibmConstant: "com.ibm.mq.constants.CMQC.MQIA_OPEN_OUTPUT_COUNT"
            ibmCommand: "MQCMD_INQUIRE_Q"

        - OldestMsgAge:
            alias: "OldestMsgAge"
            ibmConstant: "com.ibm.mq.constants.CMQCFC.MQIACF_OLDEST_MSG_AGE"
            ibmCommand: "MQCMD_INQUIRE_Q_STATUS"
            aggregationType: "OBSERVATION"
            timeRollUpType: "CURRENT"
            clusterRollUpType: "INDIVIDUAL"

        - OnQTime:
            alias: "OnQTime"
            ibmConstant: "com.ibm.mq.constants.CMQCFC.MQIACF_Q_TIME_INDICATOR"
            ibmCommand: "MQCMD_INQUIRE_Q_STATUS"
            aggregationType: "OBSERVATION"
            timeRollUpType: "CURRENT"
            clusterRollUpType: "INDIVIDUAL"

        - UncommittedMsgs:
            alias: "UncommittedMsgs"
            ibmConstant: "com.ibm.mq.constants.CMQCFC.MQIACF_UNCOMMITTED_MSGS"
            ibmCommand: "MQCMD_INQUIRE_Q_STATUS"

        - HighQDepth:
            alias: "HighQDepth"
            ibmConstant: "com.ibm.mq.constants.CMQC.MQIA_HIGH_Q_DEPTH"
            ibmCommand: "MQCMD_RESET_Q_STATS"

        - MsgDeqCount:
            alias: "MsgDeqCount"
            ibmConstant: "com.ibm.mq.constants.CMQC.MQIA_MSG_DEQ_COUNT"
            ibmCommand: "MQCMD_RESET_Q_STATS"

        - MsgEnqCount:
            alias: "MsgEnqCount"
            ibmConstant: "com.ibm.mq.constants.CMQC.MQIA_MSG_ENQ_COUNT"
            ibmCommand: "MQCMD_RESET_Q_STATS"

      
  # This Object will extract channel metrics
  - metricsType: "channelMetrics"
    metrics:
      include:
        - Messages:
            alias: "Messages"
            ibmConstant: "com.ibm.mq.constants.CMQCFC.MQIACH_MSGS"
          
        - Status:
            alias: "Status"
            ibmConstant: "com.ibm.mq.constants.CMQCFC.MQIACH_CHANNEL_STATUS"  #http://www.ibm.com/support/knowledgecenter/SSFKSJ_7.5.0/com.ibm.mq.ref.dev.doc/q090880_.htm
          
        - ByteSent:
            alias: "Byte Sent"
            ibmConstant: "com.ibm.mq.constants.CMQCFC.MQIACH_BYTES_SENT"
          
        - ByteReceived:
            alias: "Byte Received"
            ibmConstant: "com.ibm.mq.constants.CMQCFC.MQIACH_BYTES_RECEIVED"
          
        - BuffersSent:
            alias: "Buffers Sent"
            ibmConstant: "com.ibm.mq.constants.CMQCFC.MQIACH_BUFFERS_SENT"
          
        - BuffersReceived:
            alias: "Buffers Received"
            ibmConstant: "com.ibm.mq.constants.CMQCFC.MQIACH_BUFFERS_RECEIVED"


  - metricsType: "listenerMetrics"
    metrics:
      include:
        - Status:
            alias: "Status"
            ibmConstant: "com.ibm.mq.constants.CMQCFC.MQIACH_LISTENER_STATUS"

  # This Object will extract topic metrics
  - metricsType: "topicMetrics"
    metrics:
      include:
        - PublishCount:
            alias: "Publish Count"
            ibmConstant: "com.ibm.mq.constants.CMQC.MQIA_PUB_COUNT"
            ibmCommand: "MQCMD_INQUIRE_TOPIC_STATUS"
        - SubscriptionCount:
            alias: "Subscription Count"
            ibmConstant: "com.ibm.mq.constants.CMQC.MQIA_SUB_COUNT"
            ibmCommand: "MQCMD_INQUIRE_TOPIC_STATUS"

To run the extension at a frequency > 1 minute, please configure the taskSchedule section. Refer to the Task Schedule doc for details.

Extension Working - Internals

This extension extracts metrics through PCF framework. A complete list of PCF commands are listed here Each queue manager has an administration queue with a standard queue name and the extension sends PCF command messages to that queue. On Windows and Unix platforms, the PCF commands are sent is always sent to the SYSTEM.ADMIN.COMMAND.QUEUE queue. More details about that is mentioned here

By default, the PCF responses are sent to the SYSTEM.DEFAULT.MODEL.QUEUE. Using this queue causes a temporary dynamic queue to be created. You can override the default here by using the modelQueueName and replyQueuePrefix fields in the config.yml. More details mentioned here

Access Permissions

If you are in Bindings mode, please make sure to start the MA process under a user which has the following permissions on the broker. Similarly, for Client mode, please provide the user credentials in config.yml which have permissions listed below.

The user connecting to the queueManager should have the inquire, get, put (since PCF responses cause dynamic queues to be created) permissions. For metrics that execute MQCMD_RESET_Q_STATS command, chg permission is needed.

SSL Support

Configure the IBM SSL Cipher Suite in the config.yml. Note that, to use some CipherSuites the unrestricted policy needs to be configured in JRE. Please visit this link for more details. For Oracle JRE, please update with JCE Unlimited Strength Jurisdiction Policy. The download includes a readme file with instructions on how to apply these files to JRE
Please add the following JVM arguments to the MA start up command or script.

-Dcom.ibm.mq.cfg.useIBMCipherMappings=false (If you are using IBM Cipher Suites, set the flag to true. Please visit this link for more details. )
To configure SSL, the MA's trust store and keystore needs to be setup with the JKS filepath. They can be passed either as Machine Agent JVM arguments or configured in config.yml (sslConnection)

a. Machine Agent JVM arguments as follows:

-Djavax.net.ssl.trustStore=<PATH_TO_JKS_FILE>
-Djavax.net.ssl.trustStorePassword=<PASS>
-Djavax.net.ssl.keyStore=<PATH_TO_JKS_FILE>
-Djavax.net.ssl.keyStorePassword=<PASS>

b. sslConnection in config.yml, configure the trustStorePassword or trustStoreEncryptedPassword based on Credentials Encryption. Same holds for keyStore configuration as well.
```
sslConnection:
  trustStorePath: ""
  trustStorePassword: ""
  trustStoreEncryptedPassword: ""

  keyStorePath: ""
  keyStorePassword: ""
  keyStoreEncryptedPassword: ""
```

Metrics

The metrics will be reported under the tree Application Infrastructure Performance|$TIER|Custom Metrics|WebsphereMQ

Understanding metric values (string vs. integer)

The AppDynamics controller accepts only numeric (integer) values for metrics. It cannot store or display string values as the metric value. This extension therefore converts any non-numeric values as follows:

Situation	How it is reported	How to read it in the controller
Numeric metrics (counts, depths, status codes)	The integer is sent as the metric value.	Use the metric value as-is (e.g., `Current Queue Depth` = 42).
Status/code metrics (e.g., Queue Manager Status, Channel Status, Listener Status)	The IBM MQ integer constant is sent as the metric value.	See the mapping tables below for each status metric (e.g., 1 = starting, 2 = running).
String-like values (e.g., Platform name, queue name in a dimension, description text)	The string is embedded in the metric name (or path), and the value sent to the controller is always `1`.	The meaning is in the metric name/path (e.g., metric name `Platform: Windows` with value `1`). Do not treat `1` as a count; it is a placeholder so the controller can display the metric.
Date/time strings	Converted to integers (e.g., YYYYMMDD or HHMMSS) when possible and sent as the metric value.	Use the value as a numeric date/time (e.g., 20250218, 143052).

So when you see a metric whose value is 1 and the name contains a colon and text (e.g., Platform: Windows, ChannelType: SVRCONN), the meaningful information is the text in the name, not the number 1.

The tables below list each reported metric, its description, and—for status or string-derived metrics—what integer values mean or how the value is represented. You can extend or correct these lists to match exactly what your extension reports.

Quick reference: metric value types

Category	Metrics reported (value type)
Queue Manager	Status (int: 1/2/3), ConnectionCount (int), Platform (string→1), MQManagerName (string→1), Channel Monitoring Level, Character Set ID, Command Level, HeartBeat, Max Handles, Max Message Length, Max Priority, Max Uncommited Messages, Queue Monitoring Level (all int). Other definition/status attributes: int or string→1 or parsed date/time.
Queue	MaxQueueDepth, CurrentQueueDepth, OpenInputCount, OpenOutputCount (int). OldestMsgAge, OnQTime, UncommittedMsgs (int). HighQDepth, MsgDeqCount, MsgEnqCount (int). QFull% (int). String attributes (e.g. queue name in path): value 1 with name in path.
Channel	Messages, Status (int: 0–9, see Channel Status table below), ByteSent, ByteReceived, BuffersSent, BuffersReceived (int). ActiveChannelsCount (int). Last Message Date = YYYYMMDD int, Last Message Time = HHMMSS int. String attributes (ChannelName, ChannelType, etc.): value 1 with string in metric name.
Listener	Status (int: 1 = starting, 2 = running, 3 = stopping).
Topic	PublishCount, SubscriptionCount (int).

Queue Manager metrics — value in controller

Metric Name	Description	Value in controller
Status	Queue manager status	Integer: 1 = starting, 2 = running, 3 = quiescing
MQManagerName / QueueManagerName	Name of the queue manager	Always 1; name appears in metric name/path (string-derived)
Channel Monitoring Level	Queue manager default channel monitoring level	Integer (use as-is)
Character Set ID	Default CCSID configured on the queue manager	Integer (use as-is)
Command Level	MQ command level supported by the queue manager	Integer (use as-is)
Connection Count	Current number of active connections	Integer (use as-is)
HeartBeat	Queue manager heartbeat interval	Integer (use as-is)
Max Handles	Maximum number of handles allowed	Integer (use as-is)
Max Message Length	Maximum message length allowed	Integer (use as-is)
Max Priority	Maximum message priority supported	Integer (use as-is)
Max Uncommited Messages	Maximum uncommitted messages limit	Integer (use as-is)
Platform	Platform type (e.g., UNIX, Windows, AIX)	Always 1; platform name in metric name (e.g. `Platform: Windows`) (string-derived)
Queue Monitoring Level	Queue manager default queue monitoring level	Integer (use as-is)

QueueManagerMetrics — reference

Metric Name	Description
Status	1 - starting, 2 - running, 3 - quiescing
QueueManagerName (MQManagerName)	Name of the queue manager. Value in controller: always 1; name appears in metric name/path (string-derived).
Channel Monitoring Level	Queue manager default channel monitoring level
Character Set ID	Default CCSID configured on the queue manager
Command Level	MQ command level supported by the queue manager
Connection Count	Current number of active connections
HeartBeat	Queue manager heartbeat interval
Max Handles	Maximum number of handles allowed
Max Message Length	Maximum message length allowed
Max Priority	Maximum message priority supported
Max Uncommited Messages	Maximum uncommitted messages limit
Platform	Platform type (e.g., UNIX, Windows, AIX) — reported as value 1 with name in metric name
Queue Monitoring Level	Queue manager default queue monitoring level

QueueMetrics

This metrics below are only for the local queues, as these metrics are irrelevant for other queues.

Value in controller: Counts, depths, and percentages are sent as integers. Any attribute that is a string (e.g., QueueName, QueueDescription, LastGetDate_Time, LastPutDate_Time) is reported as value 1 with the string in the metric name or path.

Metric Name	Description
MaxQueueDepth	Maximum queue depth
CurrentQueueDepth	Current queue depth
OpenInputCount	Number of MQOPEN calls that have the queue open for input
OpenOutputCount	Number of MQOPEN calls that have the queue open for output
QueueName	Name of the queue. Value in controller: the queue name appears in the metric path (e.g. ...\|Queues\|DEV.QUEUE.1\|CurrentQueueDepth). If reported as a separate metric, value is always 1 with the name in the metric name.
MaxQDepth	Maximum depth configured for the queue
Depth	Current number of messages on the queue
Trigger Interval	Interval for trigger monitoring (if enabled)
QFull%	Percentage of queue usage relative to max depth
OldestMsgAge	Age of the oldest message
UncommittedMsgs	Number of uncommitted changes pending
GetStatus (Get Status)	Inhibit Get: 0 = GET allowed, 1 = GET inhibited (MQIA_INHIBIT_GET)
PutStatus (Put Status)	Inhibit Put: 0 = PUT allowed, 1 = PUT inhibited (MQIA_INHIBIT_PUT)
InputOpens	Number of times queue opened for input
OutputOpens	Number of times queue opened for output
LastGetDate / LastGetTime (Last Get Date / Last Get Time)	Timestamp of last GET. Often reported as value 1 with the date/time string in the metric name (controller cannot store strings). If the PCF value parses to digits, Last Get Date is sent as YYYYMMDD (int) and Last Get Time as HHMMSS (int); otherwise value 1 and the raw string appear in the metric name.
LastPutDate / LastPutTime (Last Put Date / Last Put Time)	Timestamp of last PUT. Often reported as value 1 with the date/time string in the metric name (controller cannot store strings). If the PCF value parses to digits, Last Put Date is sent as YYYYMMDD (int) and Last Put Time as HHMMSS (int); otherwise value 1 and the raw string appear in the metric name.
QueueMonitoring	Queue-level monitoring setting
Queue Depth High Limit	High depth threshold configured for the queue
Queue Depth Low Limit	Low depth threshold configured for the queue
QueueDescription	Description text of the queue. Value in controller: always 1; the text appears in the metric name.

QueueStatusMetrics

Metric Name	Description
OldestMsgAge	Age of the oldest message
OnQTime	Indicator of the time that messages remain on the queue
UncommittedMsgs	The number of uncommitted changes (puts and gets) pending for the queue

ResetQueueStatistics

The following metrics are extracted using the MQCMD_RESET_Q_STATS command which would reset the stats on the QM for that queue.

Metric Name	Description
HighQDepth	Maximum number of messages on a queue
MsgDeqCount	Number of messages dequeued
MsgEnqCount	Number of messages enqueued

ChannelMetrics

Value in controller: Counts and bytes (Messages, ByteSent, ByteReceived, BuffersSent, BuffersReceived) are integers. Status is an integer; see the Channel Status table below. Values 11, 12, 15–20 are not in the current IBM MQ 9.4 MQCHS reference; if the queue manager returns them, the extension reports them as-is (they may be version-specific or reserved). String attributes (e.g., ChannelName, ChannelInstType, ChannelType, SSLShortPeerName, RemoteQmgrName, XmitQName, ConnectionName, MCAUserID) are reported as value 1 with the string in the metric name or path.

Channel Status (integer → meaning):

Integer	Constant	Meaning
0	MQCHS_INACTIVE	Inactive
1	MQCHS_BINDING	Binding
2	MQCHS_STARTING	Starting
3	MQCHS_RUNNING	Running
4	MQCHS_STOPPING	Stopping
5	MQCHS_RETRYING	Retrying
6	MQCHS_STOPPED	Stopped
7	MQCHS_REQUESTING	Requesting
8	MQCHS_PAUSED	Paused
9	MQCHS_DISCONNECTED	Disconnected
10	MQCHS_DOUBT	In-doubt (Stopped and Indoubt — channel uncertain about message delivery after communication loss)
13	MQCHS_INITIALIZING	Initializing (channel initiator attempting to start the channel)
14	MQCHS_SWITCHING	Switching (channel is switching transmission queues)

Values 11, 12, 15–20 are not defined in the current IBM MQ 9.4 MQCHS constants table; the extension reports whatever integer MQ returns for Status.

ChannelName: The controller cannot store the channel name as a metric value. The name is sent in two ways: (1) as part of the metric path (e.g. ...|Channels|DEV.ADMIN.SVRCONN|Status), and (2) if "Channel Name" is included in your channel metrics config, as a separate metric whose name is Channel Name: <name> and whose value is always 1 (e.g. Channel Name: DEV.ADMIN.SVRCONN = 1). Use the metric name or path to see the channel name; do not treat 1 as a count.
Last Message Date and Last Message Time: The controller cannot store date/time strings. The extension converts them to integers: Last Message Date → YYYYMMDD (e.g. 20250218), Last Message Time → HHMMSS (e.g. 205312 = 20:53:12). So a value in the 20k range (e.g. 205000) is a valid time (20:50:00). When you see value 1, the PCF value from MQ could not be parsed (e.g. empty, blank, or fewer than 6 digits after stripping non-numeric characters). That often happens for channels with no recent message activity or for some channel types (e.g. sender SDR). In that case the raw string is in the metric name (e.g. Last Message Time: or Last Message Time: 0)—use the metric name to see what MQ returned; do not treat 1 as a time.
MCAUserID: The MCA (Message Channel Agent) user ID is a string from MQ. The controller cannot store it as a metric value. It is reported as value 1 with the user ID in the metric name (e.g. MCAUserID: mqm = 1). Use the metric name to see the actual user ID; do not treat 1 as a count.
SSLShortPeerName: The short name of the SSL peer (e.g. certificate CN) is a string from MQ. The controller cannot store it as a metric value. It is reported as value 1 with the peer name in the metric name (e.g. SSLShortPeerName: myhost.example.com = 1). Use the metric name to see the actual SSL peer name; do not treat 1 as a count. Empty or blank when the channel is not using SSL.

Metric Name	Description
Messages	Number of messages sent or received, or number of MQI calls handled
Status	Channel status. Integer value in controller: 0–10, 13, 14 documented in Channel Status table above (MQCHS_*). Values 11, 12, 15–20 not in current IBM MQ 9.4 reference; reported as-is if returned.
ByteSent	Number of bytes sent
ByteReceived	Number of bytes received
BuffersSent	Number of buffers sent
BuffersReceived	Number of buffers received
ActiveChannelsCount	Number of active channel instances (aggregate per queue manager)
ChannelName	Name of the channel instance. Value in controller: always 1; name appears in metric path and, if configured, in metric name (e.g. "Channel Name: DEV.ADMIN.SVRCONN").
ChannelInstType	Channel instance type (e.g., SVRCONN, SDR, RCVR)
ChannelType	Configured channel type
CurrentActionState	Current action state of the channel
Channel Substate (ChannelSubstate)	Channel substate (MQ integer constant, MQIACH_CHANNEL_SUBSTATE)
SSLShortPeerName	Short name of SSL peer (e.g. certificate CN). Value in controller: always 1; the peer name appears in the metric name (e.g. "SSLShortPeerName: myhost.example.com"). Empty when the channel is not using SSL.
HeartbeatInterval	Channel heartbeat interval (seconds)
Last Message Date / Last Message Time (LastMessageDate_Time)	Timestamp of last message. Value in controller: date and time are converted to integers—Last Message Date = YYYYMMDD (e.g. 20250218), Last Message Time = HHMMSS (e.g. 205312 = 20:53:12). A value in the 20k range is a valid time. If the PCF value cannot be parsed (e.g. empty or < 6 digits), value is 1 and the raw string is in the metric name—common for inactive channels or some types (e.g. SDR).
LocalAddress	Local IP address and port. Value in controller: always 1; the address appears in the metric name (e.g. "LocalAddress: 192.168.1.10(1414)").
MCAUserID	MCA user ID. Value in controller: always 1; the user ID appears in the metric name (e.g. "MCAUserID: mqm").
MCAStatus	MCA status
RemoteQmgrName	Remote queue manager name. Value in controller: always 1; the name appears in the metric name (e.g. "RemoteQmgrName: REMOTE.QM").
XmitQName	Transmission queue name. Value in controller: always 1; the queue name appears in the metric name (e.g. "XmitQName: SYSTEM.CHANNEL.XMITQ").
ConnectionName	Remote connection name (host/port)
ShortRetriesLeft	Remaining short retry attempts
LongRetriesLeft	Remaining long retry attempts
KeepAliveInterval	TCP keepalive interval (seconds)

ListenerMetrics

Value in controller: Status is an integer: 1 = starting, 2 = running, 3 = stopping.

Metric Name	Description
Status	1 - starting, 2 - running, 3 - stopping

TopicMetrics

Value in controller: PublishCount and SubscriptionCount are integers (use as-is).

Metric Name	Description
PublishCount	The number of applications currently publishing to the topic.
SubscriptionCount	The number of subscribers for this topic string, including durable subscribers who are not currently connected.

Credentials Encryption

Please visit this page to get detailed instructions on password encryption. The steps in this document will guide you through the whole process.

Extensions Workbench

Workbench is an inbuilt feature provided with each extension in order to assist you to fine tune the extension setup before you actually deploy it on the controller. Please review the following document on How to use the Extensions WorkBench

Troubleshooting

Please follow the steps listed in this troubleshooting-document in order to troubleshoot your issue. These are a set of common issues that customers might have faced during the installation of the extension.
Error Completion Code '2', Reason '2495' Normally this error occurs if the environment variables are not set up correctly for this extension to work MQ in Bindings Mode.

If you are seeing Failed to load the WebSphere MQ native JNI library: 'mqjbnd', please add the following jvm argument when starting the MA.

-Djava.library.path=<path to libmqjbnd.so> For eg. on Unix it could -Djava.library.path=/opt/mqm/java/lib64 for 64-bit or -Djava.library.path=/opt/mqm/java/lib for 32-bit OS

Sometimes you also have run the setmqenv script before using the above jvm argument to start the machine agent.

. /opt/mqm/bin/setmqenv -s

For more details, please check this doc

This might occour due to various reasons ranging from incorrect installation to applying ibm fix packs but most of the time it happens when you are trying to connect in Bindings mode and machine agent is not on the same machine on which WMQ server is running. If you want to connect to WMQ server from a remote machine then connect using Client mode.

Another way to get around this issue is to avoid using the Bindings mode. Connect using CLIENT transport type from a remote box.
Error Completion Code '2', Reason '2035' This could happen for various reasons but for most of the cases, for Client mode the user specified in config.yml is not authorized to access the queue manager. Also sometimes even if userid and password are correct, channel auth (CHLAUTH) for that queue manager blocks traffics from other ips, you need to contact admin to provide you access to the queue manager. For Bindings mode, please make sure that the MA is owned by a mqm user. Please check this doc
MQJE001: Completion Code '2', Reason '2195' This could happen in Client mode. Please make sure that the IBM MQ dependency jars are correctly referenced in classpath of monitor.xml
MQJE001: Completion Code '2', Reason '2400' This could happen if unsupported cipherSuite is provided or JRE not having/enabled unlimited jurisdiction policy files. Please check SSL Support section.
If you are seeing "NoClassDefFoundError" or "ClassNotFound" error for any of the MQ dependency even after providing correct path in monitor.xml, then you can also try copying all the required jars in WMQMonitor (MAHome/monitors/WMQMonitor) folder and provide classpath in monitor.xml like below
```
 <classpath>websphere-mq-monitoring-extension.jar;com.ibm.mq.allclient.jar</classpath>
```
OR
```
 <classpath>websphere-mq-monitoring-extension.jar;com.ibm.mq.jar;com.ibm.mq.jmqi.jar;com.ibm.mq.commonservices.jar;com.ibm.mq.headers.jar;com.ibm.mq.pcf.jar;connector.jar;dhbcore.jar</classpath>
```
Last Message Date / Last Message Time shows value 1 for some channels (e.g. TO.LOOP.SDR) but a numeric value (e.g. 20xxx) for others (e.g. DEV.ADMIN.SVRCONN)
This is expected. The extension sends Last Message Time as HHMMSS (e.g. 205312 = 20:53:12); values in the 20k range are valid times. When MQ returns a value that cannot be parsed to 6 digits (e.g. empty, blank, or no recent message), the extension sends 1 and puts the raw string in the metric name. That often happens for channels with no recent activity or for some channel types (e.g. sender SDR). Check the metric name in the controller for the raw value (e.g. Last Message Time: ); do not treat 1 as a time.

Contributing

Always feel free to fork and contribute any changes directly via GitHub.

Version

Name	Version
Extension Version	7.0.7
Extension Version	7.0.7
IBM MQ Version tested On	7.x, 8.x, 9.x and Windows, Unix, AIX
Last Update	22/09/2025
List of Changes	Change Log

Note: While extensions are maintained and supported by customers under the open-source licensing model, they interact with agents and Controllers that are subject to AppDynamics’ maintenance and support policy. Some extensions have been tested with AppDynamics 4.5.13+ artifacts, but you are strongly recommended against using versions that are no longer supported.

Name		Name	Last commit message	Last commit date
Latest commit History 153 Commits
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
NOTICE.txt		NOTICE.txt
README.md		README.md
USE_CASE.md		USE_CASE.md
pom.xml		pom.xml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

AppDynamics Monitoring Extension for use with IBM WebSphere MQ

Use case

Prerequisites

Dependencies

Installation

Configuration

Extension Working - Internals

Access Permissions

SSL Support

Metrics

Understanding metric values (string vs. integer)

Quick reference: metric value types

Queue Manager metrics — value in controller

QueueManagerMetrics — reference

QueueMetrics

QueueMetrics

QueueStatusMetrics

ResetQueueStatistics

ChannelMetrics

ListenerMetrics

TopicMetrics

Credentials Encryption

Extensions Workbench

Troubleshooting

Contributing

Version

About

Uh oh!

Releases 10

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

AppDynamics Monitoring Extension for use with IBM WebSphere MQ

Use case

Prerequisites

Dependencies

Installation

Configuration

Extension Working - Internals

Access Permissions

SSL Support

Metrics

Understanding metric values (string vs. integer)

Quick reference: metric value types

Queue Manager metrics — value in controller

QueueManagerMetrics — reference

QueueMetrics

Credentials Encryption

Extensions Workbench

Troubleshooting

Contributing

Version

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Uh oh!

Uh oh!

Uh oh!

Languages