IBM MQ Exporter

Prometheus exporter for IBM MQ, written in Java. Exposes API metrics of IBM MQ and system metrics of it's host machine.

Table of contents

1. Getting Started
   • Compatibility
   • Dependencies
   • Configuration
   • Build
   • Run
     • Running exporter as mq service
     • Running exporter as standalone java application
2. Metrics
   • Metrics naming convention
     • Understanding metrics names
     • Domains and subdomains
     • Units
   • Metrics list
     • CPU metrics
     • CPU performance metrics - platform wide
     • CPU performance metrics - running queue manager
     • Platform persistent data store related metrics
     • Disk usage metrics - platform wide
     • Disk usage metrics - running queue managers
     • Disk usage metrics - queue manager recovery log
     • API usage metrics
     • MQCONN and MQDISC metrics
     • MQOPEN and MQCLOSE metrics
     • MQINQ and MQSET metrics
     • MQPUT metrics
     • MQGET metrics
     • Commit and rollback metrics
     • Subscription metrics
     • Publication metrics
     • API per-queue usage metrics
     • MQOPEN and MQCLOSE metrics
     • MQINQ and MQSET metrics
     • MQPUT and MQPUT1 metrics
     • MQGET metrics
     • MQ PCF API specific metrics
     • Metrics obtained by PCF commands
     • MQ constants mapping
       • Channel status mapping
       • Listener status mapping
3. Contributions
4. Known issues
5. Warning
6. License

Getting Started

Compatibility

_{^{Back to TOC.}}
Supports IBM MQ version 9.0.x.x and above.

Was tested on MQ ver.9.0.x.x and MQ ver. 9.1.x.x.

Note: The Publish/Subscribe Mode "PSMODE" Queue Manager attribute in IBM MQ should have value "enabled".

Dependencies

_{^{Back to TOC.}}
List of dependencies:

• IBM JRE 8 or higher \ Oracle JRE 8 or higher \ OpenJDK JRE 8 or higher
• Maven
• Prometheus
• IBM MQ

Configuration

_{^{Back to TOC.}}
All connection and monitoring settings have to be set in exporter_config.yaml file. Below is an example of a filled configuration file with all possible fields:

# MQ connection information -------------------------------
qmgrConnectionParams:
# Queue manager name.
  qmgrName: QM
# Queue manager host.
  qmgrHost: localhost
# Queue manager connection port.
  qmgrPort: 1414
# Queue manager connection channel.
  qmgrChannel: SYSTEM.DEF.SVRCONN
# Username, which will be used for connection (optional).
# User must have permission to subscribe to the topic $SYS/MQ/INFO/QMGR/QM/Monitor/ and all subtopics.
# User also must have permission to inquire  channels, queues and listeners listed below in Monitoring objects section! 
  user: mqm
# Password, which will be used for connection (optional).
  password: mqm
# Use MQCSP for connection?
  mqscp: false
# How long to wait until metrics are published by queue manager (milliseconds).
# Value must be at least 10000 (periodicity with which metrics are published by MQ).
  connTimeout: 12000
# Use TLS connection to queue manager? If useTLS equals "false" than all connection parameters below will be ignored.
  useTLS: true
# Path to keystore file
  keystorePath: /opt/mq_exporter/keystores/keystore.jks
# Keystore password
  keystorePassword: testpass2
# Path to truststore file
  truststorePath: /opt/mq_exporter/keystores/truststore.jks
# Truststore password
  truststorePassword: testpass2
# SSL protocol
  sslProtocol: TLSv1.2
# CipherSuite
  cipherSuite: TLS_RSA_WITH_AES_256_CBC_SHA256

# Prometheus connection information -------------------------------
prometheusEndpointParams:
# URL and port which will be used to expose metrics for Prometheus.
  url: /metrics
  port: 8080

# Monitoring objects ----------------------------------
# This block refers to collecting of additional metrics.
# If there are any queues, channels or listeners in the config file below,
# these metrics may be useful for you. (More info about additional metrics is located 
# under "MQ PCF API specific statistics" section.   
PCFParameters:
# Collect additional metrics? If false, all settings in this section below are ignored. 
# If yes, additional metrics will be collected for all queues, channels and listeners listed below. 
  sendPCFCommands: true
# If usePCFWildcards equals "true", then all monitored objects will be grouped by object type: QUEUE, CHANNEL and LISTENER. Only one PCF command will be sent for each object type. 
# If usePCFWildcards equals "false", then PCF command will be send for each object.
# Each PCF command uses a separate connection, so sending a large number of PCF commands will create a large number of connections to MQ queue manager.
# For example, for 100 monitoring queues will be opened 100 connections to MQ queue manager, if usePCFwildcard equals "false".
# On the other hand, for usePCFwildcard equals "true", if there are 10.000 queues in the queue manager and just a few queues is need to be monitored, 
# only one PCF command will be sent. But response will contain metrics for all 10.000 queues and that will lead to performance problems.
  usePCFWildcards: true
# Interval in seconds between sending PCF commands.
  scrapeInterval: 300

# Further block contains info about monitoring objects. It supports "*" wildcard at the end of the name.
# Firstly, objects from "include" section are retrieved.
# Then objects from "exclude" section are retrieved.
# Finally, objects that are in the first group but not in the second are added to the monitoring list.

#Interval in seconds between updating objects (in case some objects were removed or created).
updateInterval: 30

# Monitored queues.
queues:
  include:
    - '*'
  exclude:
    - SYSTEM.*

# Monitored listeners.
listeners:
  include:
  exclude:
    - SYSTEM.*

# Monitored channels.
channels:
  include:

Build

_{^{Back to TOC.}}
Steps, that need to be taken to build the exporter:

1. Download current repository.
2. Install Maven.
3. Go to mq-java-exporter root folder (where pom.xml is located) and run:

mvn package

4. After processing is completed, go to mq-java-exporter/target. lib directory and mq_exporter.jar should appear there.

Run

_{^{Back to TOC.}}
To run exporter, lib directory (and all jars in it) and mq_exporter.jar should be located in the same folder.

Running exporter as mq service

_{^{Back to TOC.}}
It is recommended way of running the exporter. Note: all commands should be executed via MQ CLI. More info can be found here.

Define queue manager service with the following command:

  DEFINE SERVICE(MQEXPORTER) CONTROL(QMGR) SERVTYPE(SERVER) +
  STARTCMD('/opt/mqm/java/jre64/jre/bin/java')              +
  STARTARG('-Dlog4j.configurationFile=/opt/mq_exporter/log4j2.properties -jar /opt/mq_exporter/mq_exporter.jar /opt/mq_exporter/exporter_config.yaml') +
  STOPCMD('/usr/bin/kill ' ) STOPARG(+MQ_SERVER_PID+)       +
  STDOUT('/opt/mq_exporter/mq_prometheus.out')              +
  STDERR('/opt/mq_exporter/mq_prometheus.out')              +
  DESCR('MQ exporter for Prometheus')

More information about this command can be found here.

To start exporter, execute the following command:

  START SERVICE(MQEXPORTER)

To stop exporter, execute the following command:

   STOP SERVICE(MQEXPORTER)

Running exporter as standalone java application

_{^{Back to TOC.}}
To run exporter execute the following command:

 java -jar mq_exporter.jar /opt/mq_exporter/exporter_config.yaml

The only input parameter is the path to your configuration file.

Metrics

Metrics naming convention

Understanding metrics names

_{^{Back to TOC.}}
All metrics have predefined structure: domain, subdomain, name, units:

• Domain - the first single-word prefix that represents a metric type. The examples of domain-level prefixes are: system, mq, mqobject and etc. More information can be found in "Domains and subdomains" section.
• Subdomain - second single-word prefix representation of a metric type. It provides more specific information about metric type and helps to differentiate metrics in a single domain. The examples of subdomain-level prefixes are: cpu, ram, put, subscribe, get and etc. More information can be found in "Domains and subdomains" section.
• Units - single-word suffix describing the metric's unit, in plural form. Note that an accumulating count has "total" as the first part of a suffix. The examples of unit suffixes are: percentage, messages, totalmessages and etc. More information can be found in "Units" section.
• Name - represents metric meaning. The examples of a metric name are: cpu_time, cpu_load_fifteen_minute_average, failed_mqget_count and etc. Note that the amount of words in a metric name can vary:

Domains and subdomains

_{^{Back to TOC.}}
This section provides a description of domains and subdomains and reflects their relations.

Units

_{^{Back to TOC.}}
This section provides a description of metric units.
"Metric and label naming" article by Prometheus states that metrics "...should use base units (e.g. seconds, bytes, meters - not milliseconds, megabytes, kilometers)". There was an attempt to find a balance between MQ metrics and Prometheus metrics (according to the Prometheus conventions), but it was decided to change the metrics from MQ as little as possible, since some metrics do not fit the description in the article. Conversion of values for certain metrics can lead to a distortion of actual values (e.g. integer amount megabytes) and increasing in disk space, occupied by the metric. So the exporter has following list of units:

Metrics list

CPU metrics

CPU performance metrics - platform wide

_{^{Back to TOC.}}
This section provides a description of CPU- and RAM-related metrics.

CPU performance metrics - running queue manager

_{^{Back to TOC.}}
This section provides a description of CPU metrics of a running queue manager.

Platform persistent data store related metrics

Disk usage metrics - platform wide

_{^{Back to TOC.}}
This section provides a description of disk usage metrics.

Disk usage metrics - running queue managers

_{^{Back to TOC.}}
This section provides a description of disk usage metrics, related to a running queue manager.

Disk usage metrics - queue manager recovery log

_{^{Back to TOC.}}
This section provides a description of disk usage metrics, related to queue manager recovery log.

API usage metrics

MQCONN and MQDISC metrics

_{^{Back to TOC.}}
This section provides a description of metrics related to MQCONN and MQDISC calls to a queue manager.

MQOPEN and MQCLOSE metrics

_{^{Back to TOC.}}
This section provides a description of metrics related to MQOPEN and MQCLOSE calls to a queue manager.

MQINQ and MQSET metrics

_{^{Back to TOC.}}
This section provides a description of metrics related to MQINQ and MQSET calls to a queue manager.

MQPUT metrics

_{^{Back to TOC.}}
This section provides a description of metrics related to MQPUT, MQPUT1 and MQSTAT calls to a queue manager.

MQGET metrics

_{^{Back to TOC.}}
This section provides a description of metrics related to MQGET, MQCB and MQCTL calls to a queue manager.

Commit and rollback metrics

_{^{Back to TOC.}}
This section provides a description of metrics related to MQCMIT and MQBACK calls to a queue manager.

Subscription metrics

_{^{Back to TOC.}}
This section provides a description of metrics related to subscriptions of a queue manager.

Publication metrics

_{^{Back to TOC.}}
This section provides a description of metrics related to publications of a queue manager.

API per-queue usage metrics

MQOPEN and MQCLOSE metrics

_{^{Back to TOC.}}
This section provides a description of metrics related to MQOPEN and MQCLOSE calls to a specific queue.

MQINQ and MQSET metrics

_{^{Back to TOC.}}
This section provides a description of metrics related to MQINQ and MQSET calls to a specific queue.

MQPUT and MQPUT1 metrics

_{^{Back to TOC.}}
This section provides a description of metrics related to MQPUT and MQPUT1 calls to a specific queue.

MQGET metrics

_{^{Back to TOC.}}
This section provides a description of metrics related to MQGET calls to a specific queue.

MQ PCF API specific metrics

Metrics obtained by PCF commands

_{^{Back to TOC.}}
This section provides a description of metrics of queues, channels and listeners that are collected via sending direct PCF commands to queue manager.

MQ constants mapping

Channel status mapping

_{^{Back to TOC.}}
This section provides a mapping between MQ channel statuses and metric values, that are sent to Prometheus.

Note: If channel has status INACTIVE, there is no way to retrieve it's status by PCF command (because technically channel has no status) and MQRCCF_CHL_STATUS_NOT_FOUND will be returned by queue manager. Since INACTIVE status of the channel is the most frequent reason for receiving such an error, the exporter interprets it as INACTIVE status of the channel.

Listener status mapping

_{^{Back to TOC.}}
This section provides a mapping between MQ listener statuses and metric values, that are sent to Prometheus.

Contributions

_{^{Back to TOC.}}
Feel free to express your thoughts about the exporter, unexpected behaviour and\or issues. New feature suggestions are welcome, use issue tracker. Pull requests are always welcome.

Known issues

_{^{Back to TOC.}}
The following are known issues and may affect your use of exporter.

1. Metric mq_ram_ram_total_estimate_megabytes may contain negative values. #62

   This problem is related to this IBM APAR. The problem appeared during testing the exporter on MQ ver. 9.0.1.0. We could not reproduce this problem on MQ ver. 9.1.0.1 (this version includes fix for APAR above). Unfortunately, there is no way to fix this problem on the exporter side and the only option is to wait for the fix from IBM for MQ ver. 9.0.x.x.

Warning

_{^{Back to TOC.}}
The exporter is provided as-is with no guarantees.

License

_{^{Back to TOC.}}
The exporter and it's code is licensed under the Apache License 2.0.