Cinimex / mq-java-exporter

Exporter for IBM MQ metrics https://prometheus.io/
Apache License 2.0
26 stars 16 forks source link
aix aix-compatible exporter ibm ibm-mq monitoring mq mq-metrics prometheus prometheus-exporter system-metrics

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
  2. Metrics
  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:

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
  1. 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:

Domains and subdomains

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

Domain Domain description Subdomain Subdomain description
system Platform wide system metrics cpu CPU-related performance metrics
ram RAM-related performance metrics
disk Disk usage metrics
mq MQ manager wide metrics cpu CPU metrics of a running queue manager
ram RAM-related metrics, related to a running queue manager
disk Disk usage metrics, related to a running queue manager
rlog Queue manager recovery log metrics
mqconn Metrics related to MQCONN calls to a queue manager
mqdisc Metrics related to MQDISC calls to a queue manager
mqopen Metrics related to MQOPEN calls to a queue manager
mqclose Metrics related to MQCLOSE calls to a queue manager
mqinq Metrics related to MQINQ calls to a queue manager
mqset Metrics related to MQSET calls to a queue manager
put Metrics related to MQPUT, MQPUT1 and MQSTAT calls to a queue manager
get Metrics related to MQGET, MQCB and MQCTL calls to a queue manager
queue QM-wide queue metrics
commit Metrics related to MQCMIT calls to a queue manager
rollback Metrics related to MQBACK calls to a queue manager
subscribe Metrics related to subscriptions of a queue manager
publish Metrics related to publications of a queue manager
mqobject Metrics for specific objects of a queue manager: for a queue, for a channel, for a listener mqopen Metrics related to MQOPEN calls to a specific queue
mqclose Metrics related to MQCLOSE calls to a specific queue
mqinq Metrics related to MQINQ calls to a specific queue
mqset Metrics related to MQSET calls to a specific queue
put Metrics related to MQPUT and MQPUT1 calls to a specific queue
get Metrics related to MQGET calls to a specific queue
queue Metrics related to a specific queue
channel Metrics related to a specific channel
listener Metrics related to a specific listener

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:

Unit Unit description
percentage Shows %
megabytes Shows amount of megabytes
files Shows amount of files
bytes Shows amount of bytes
microseconds Shows amount of microseconds.
totalcalls Shows amount of calls. An accumulating count has "total" as the first part of a suffix.
totalconnections Shows amount of connections. An accumulating count has "total" as the first part of a suffix.
totalmessages Shows amount of messages. An accumulating count has "total" as the first part of a suffix.
totalbytes Shows amount of bytes. An accumulating count has "total" as the first part of a suffix.
totalbrowses Shows amount of browses. An accumulating count has "total" as the first part of a suffix.
subscriptions Shows amount of subscriptions.
totalattempts Shows amount of attempts. An accumulating count has "total" as the first part of a suffix.
totalqueues Shows amount of queues. An accumulating count has "total" as the first part of a suffix.
messages Shows amount of messages.
untyped If it's not obvious, what the type of metric is, then this type is used (for example, it is used, to reflect system's load average and LISTENER\CHANNEL status codes).

Metrics list

CPU metrics

CPU performance metrics - platform wide

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

Prometheus metric name Metric type Short description MQ metric element
system_cpu_user_cpu_time_percentage gauge Shows the percentage of CPU busy in user state. User CPU time percentage
system_cpu_cpu_time_percentage gauge Shows the percentage of CPU busy in system state System CPU time percentage
system_cpu_cpu_load_one_minute_average_untyped gauge Shows the load average over 1 minute. CPU load - one minute average
system_cpu_cpu_load_five_minute_average_untyped gauge Shows the load average over 5 minutes. CPU load - five minute average
system_cpu_cpu_load_fifteen_minute_average_untyped gauge Shows the load average over fifteen minutes.  CPU load - fifteen minute average
system_ram_ram_free_percentage gauge Shows the percentage of free RAM memory. RAM free percentage
system_ram_ram_total_megabytes gauge Shows the total bytes of RAM configured. RAM total bytes
CPU performance metrics - running queue manager

Back to TOC.
This section provides a description of CPU metrics of a running queue manager.

Prometheus metric name Metric type Short description MQ metric element
mq_cpu_user_cpu_time_estimate_percentage gauge Estimates the percentage of CPU use in user state for processes that are related to the queue managers that are being monitored. User CPU time - percentage estimate for queue manager
mq_cpu_system_cpu_time_estimate_percentage gauge Estimates the percentage of CPU use in system state for processes that are related to the queue managers that are being monitored System CPU time - percentage estimate for queue manager
mq_ram_ram_total_estimate_megabytes gauge Estimates the total bytes of RAM in use by the queue managers that are being monitored. RAM total bytes - estimate for 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.

Prometheus metric name Metric type Short description MQ metric element
system_disk_trace_file_system_in_use_megabytes gauge Shows the number of bytes of disk storage that are being used by the trace file system. MQ trace file system - bytes in use
system_disk_trace_file_system_free_space_percentage gauge Shows the disk storage that is reserved for the trace file system that is free. MQ trace file system - free space
system_disk_errors_file_system_in_use_megabytes gauge Shows the number of bytes of disk storage that is being used by error data. MQ errors file system - bytes in use
system_disk_errors_file_system_free_space_percentage gauge Shows the disk storage that is reserved for error data that is free. MQ errors file system - free space
system_disk_fdc_file_count_files gauge Shows the current number of FDC files. MQ FDC file count
Disk usage metrics - running queue managers

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

Prometheus metric name Metric type Short description MQ metric element
mq_disk_file_system_in_use_megabytes gauge Shows the number of bytes of disk storage that is used by queue manager files for the queue managers that you are monitoring. Queue Manager file system - bytes in use
mq_disk_file_system_free_space_percentage gauge Shows the disk storage that is reserved for queue manager files that is free. Queue Manager file system - free space
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.

Prometheus metric name Metric type Short description MQ metric element
mq_rlog_log_bytes_in_use_bytes gauge Shows the number of bytes of disk storage that is used for the recovery logs of the queue managers that you are monitoring. Log - bytes in use
mq_rlog_log_bytes_max_bytes gauge Shows the maximum bytes of disk storage that is configured to be used for queue manager recovery logs. Log - bytes max
mq_rlog_log_file_system_bytes_in_use_bytes gauge Shows the total number of disk bytes in use for the log file system. Log file system - bytes in use
mq_rlog_log_file_system_bytes_max_bytes gauge Shows the number of disk bytes that are configured for the log file system.  Log file system - bytes max
mq_rlog_log_physical_bytes_written_bytes counter Shows the number of bytes being written to the recovery logs. Log - physical bytes written
mq_rlog_log_logical_bytes_written_bytes counter Shows the logical number of bytes written to the recovery logs. Log - logical bytes written
mq_rlog_log_write_latency_microseconds gauge Shows a measure of the latency when writing synchronously to the queue manager recovery log. Log - write latency

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.

Prometheus metric name Metric type Short description MQ metric element
mq_mqconn_mqconnx_count_totalcalls counter Shows the number of calls to MQCONN and MQCONNX. MQCONN/MQCONNX count
mq_mqconn_failed_mqconn_mqconnx_count_totalcalls counter Shows the number of failed calls to MQCONN and MQCONNX. Failed MQCONN/MQCONNX count
mq_mqconn_concurrent_connections_high_water_mark_connections gauge Shows the maximum number of concurrent connections in the current statistics interval. Concurrent connections - high water mark
mq_mqdisc_mqdisc_count_totalcalls counter Shows the number of calls to MQDISC. MQDISC count
MQOPEN and MQCLOSE metrics

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

Prometheus metric name Metric type Short description MQ metric element
mq_mqopen_mqopen_count_totalcalls counter Shows the number of calls to MQOPEN. MQOPEN count
mq_mqopen_failed_mqopen_count_totalcalls counter Shows the number of failed calls to MQOPEN. Failed MQOPEN count
mq_mqclose_mqclose_count_totalcalls counter Shows the number of calls to MQCLOSE. MQCLOSE count
mq_mqclose_failed_mqclose_count_totalcalls counter Shows the number of failed calls to MQCLOSE. Failed MQCLOSE count
MQINQ and MQSET metrics

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

Prometheus metric name Metric type Short description MQ metric element
mq_mqinq_mqinq_count_totalcalls counter Shows the number of calls to MQINQ. MQINQ count
mq_mqinq_failed_mqinq_count_totalcalls counter Shows the number of failed calls to MQINQ. Failed MQINQ count
mq_mqset_mqset_count_totalcalls counter Shows the number of calls to MQSET. MQSET count
mq_mqset_failed_mqset_count_totalcalls counter Shows the number of failed calls to MQSET. Failed MQSET count
MQPUT metrics

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

Prometheus metric name Metric type Short description MQ metric element
mq_put_interval_total_mqput_mqput1_count_totalcalls counter Shows the number of calls to MQPUT and MQPUT1. Interval total MQPUT/MQPUT1 count
mq_put_interval_total_mqput_mqput1_byte_count_totalbytes counter Shows the total bytes of data that is put by calls to MQPUT and MQPUT1. Interval total MQPUT/MQPUT1 byte count
mq_put_non_persistent_message_mqput_count_totalmessages counter Shows the number of non-persistent messages that are put by MQPUT. Non-persistent message MQPUT count
mq_put_persistent_message_mqput_count_totalmessages counter Shows the number of persistent messages that are put by MQPUT. Persistent message MQPUT count
mq_put_failed_mqput_count_totalcalls counter Shows the number of failed calls to MQPUT. Failed MQPUT count
mq_put_non_persistent_message_mqput1_count_totalmessages counter Shows the number of non-persistent messages that are put by MQPUT1. Non-persistent message MQPUT1 count
mq_put_persistent_message_mqput1_count_totalmessages counter Shows the number of persistent messages that are put by MQPUT1. Persistent message MQPUT1 count
mq_put_failed_mqput1_count_totalcalls counter Shows the number of failed calls to MQPUT1. Failed MQPUT1 count
mq_put_put_non_persistent_messages_byte_count_totalbytes counter Shows the number of bytes put in non-persistent messages. Put non-persistent messages - byte count
mq_put_put_persistent_messages_byte_count_totalbytes counter Shows the number of bytes put in persistent messages. Put persistent messages - byte count
mq_put_mqstat_count_totalcalls counter Shows the number of calls to MQSTAT. MQSTAT count
MQGET metrics

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

Prometheus metric name Metric type Short description MQ metric element
mq_get_interval_total_destructive_get_count_totalmessages counter Number of messages that are removed from queues by MQGET. Interval total destructive get- count
mq_get_interval_total_destructive_get_byte_count_totalbytes counter Bytes of data that is removed from queues by MQGET. Interval total destructive get - byte count
mq_get_non_persistent_message_destructive_get_count_totalmessages counter Number of non-persistent messages that are removed from queues by MQGET. Non-persistent message destructive get - count
mq_get_persistent_message_destructive_get_count_totalmessages counter Number of persistent messages that are removed from queues by MQGET. Persistent message destructive get - count
mq_get_failed_mqget_count_totalcalls counter Shows the number of failed calls to MQGET. Failed MQGET - count
mq_get_got_non_persistent_messages_byte_count_totalbytes counter Shows a count of bytes of non-persistent messages that are returned to MQGET. Got non-persistent messages - byte count
mq_get_got_persistent_messages_byte_count_totalbytes counter Shows a count of bytes of persistent messages that are returned to MQGET. Got persistent messages - byte count
mq_get_non_persistent_message_browse_count_totalmessages counter Shows a count of non-persistent messages that have been browsed. Non-persistent message browse - count
mq_get_persistent_message_browse_count_totalmessages counter Shows a count of persistent messages that have been browsed. Persistent message browse - count
mq_get_failed_browse_count_totalbrowses counter Shows a count of failed message browses. Failed browse count
mq_get_non_persistent_message_browse_byte_count_totalmessages counter Shows the number of bytes of non-persistent messages that have been browsed. Non-persistent message browse - byte count
mq_get_persistent_message_browse_byte_count_totalmessages counter Shows the number of bytes of persistent messages that have been browsed. Persistent message browse - byte count
mq_get_expired_message_count_totalmessages counter Shows a count of expired messages. Expired message count
mq_queue_purged_queue_count_totalqueues counter Shows a count of queues that have been purged. Purged queue count
mq_get_mqcb_count_totalcalls counter Shows the number of calls to MQCB. MQCB count
mq_get_failed_mqcb_count_totalcalls counter Shows the number of failed calls to MQCB. Failed MQCB count
mq_get_mqctl_count_totalcalls counter Shows the number of calls to MQCTL. MQCTL count
mqobject_get_average_destructive_mqget_persistent_message_size_bytes gauge Shows an average amount of bytes per persistent message that are returned by MQGET. destructive MQGET persistent average message byte count
mqobject_get_average_destructive_mqget_non_persistent_message_size_bytes gauge Shows an average amount of bytes per non-persistent message that are returned by MQGET. destructive MQGET non-persistent average message byte count
mqobject_get_average_destructive_mqget_persistent_and_non_persistent_message_size_bytes gauge Shows an average amount of bytes per persistent and non-persistent messages that are returned by MQGET. destructive MQGET persistent and non-persistent average message byte count
Commit and rollback metrics

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

Prometheus metric name Metric type Short description MQ metric element
mq_commit_commit_count_totalcalls counter Shows the number of calls to MQCMIT. Commit count
mq_rollback_rollback_count_totalcalls counter Shows the number of calls to MQBACK. Rollback count
Subscription metrics

Back to TOC.
This section provides a description of metrics related to subscriptions of a queue manager.

Prometheus metric name Metric type Short description MQ metric element
mq_subscribe_create_durable_subscription_count_totalcalls counter Shows the number of calls to MQSUB to create durable subscriptions. Create durable subscription count
mq_subscribe_alter_durable_subscription_count_totalcalls counter Shows the number of calls to MQSUB to alter durable subscriptions. Alter durable subscription count
mq_subscribe_resume_durable_subscription_count_totalcalls counter Shows the number of calls to MQSUB to resume durable subscriptions. Resume durable subscription count
mq_subscribe_create_non_durable_subscription_count_totalcalls counter Shows the number of calls to MQSUB to create non-durable subscriptions. Create non-durable subscription count
mq_subscribe_failed_create_alter_resume_subscription_count_totalcalls counter Shows the number of failed calls to MQSUBRQ to create, alter, or resume subscriptions. Failed create/alter/resume subscription count
mq_subscribe_delete_durable_subscription_count_totalcalls counter Shows the number of calls to MQSUB to delete durable subscriptions. Delete durable subscription count
mq_subscribe_delete_non_durable_subscription_count_totalcalls counter Shows the number of calls to MQSUB to delete non-durable subscriptions. Delete non-durable subscription count
mq_subscribe_subscription_delete_failure_count_totalcalls counter Shows the number of calls to MQSUB to delete subscriptions. Subscription delete failure count
mq_subscribe_mqsubrq_count_totalcalls counter Shows the number of calls to MQSUBRQ MQSUBRQ count
mq_subscribe_failed_mqsubrq_count_totalcalls counter Shows the number of failed calls to MQSUBRQ Failed MQSUBRQ count
mq_subscribe_durable_subscriber_high_water_mark_subscriptions gauge Shows the maximum number of durable subscriptions in the current statistics interval. Durable subscriber - high water mark
mq_subscribe_durable_subscriber_low_water_mark_subscriptions gauge Shows the minimum number of durable subscriptions in the current statistics interval. Durable subscriber - low water mark
mq_subscribe_non_durable_subscriber_high_water_mark_subscriptions gauge Shows the maximum number of non-durable subscriptions in the current statistics interval. Non-durable subscriber - high water mark
mq_subscribe_non_durable_subscriber_low_water_mark_subscriptions gauge Shows the minimum number of non-durable subscriptions in the current statistics interval. Non-durable subscriber - low water mark
Publication metrics

Back to TOC.
This section provides a description of metrics related to publications of a queue manager.

Prometheus metric name Metric type Short description MQ metric element
mq_publish_topic_mqput_mqput1_interval_total_totalmessages counter The number of messages that are put to topics. Topic MQPUT/MQPUT1 interval total
mq_publish_interval_total_topic_bytes_put_totalbytes counter The number of message bytes put to topics. Interval total topic bytes put
mq_publish_published_to_subscribers_message_count_totalmessages counter Shows the number of messages that are published to subscribers. Published to subscribers - message count
mq_publish_published_to_subscribers_byte_count_totalbytes counter Shows the byte count of messages that are published to subscribers. Published to subscribers - byte count
mq_publish_non_persistent_topic_mqput_mqput1_count_totalmessages counter Shows the number of non-persistent messages that are put to topics. Non-persistent - topic MQPUT/MQPUT1 count
mq_publish_persistent_topic_mqput_mqput1_count_totalmessages counter Shows the number of persistent messages that are put to topics. Persistent - topic MQPUT/MQPUT1 count
mq_publish_failed_topic_mqput_mqput1_count_totalattempts counter Shows the number of failed attempts to put to a topic. Failed topic MQPUT/MQPUT1 count

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.

Prometheus metric name Metric type Short description MQ metric element
mqobject_mqopen_mqopen_count_totalcalls counter Shows the number of calls to MQOPEN. MQOPEN count
mqobject_mqclose_mqclose_count_totalcalls counter Shows the number of calls to MQCLOSE. MQCLOSE count
MQINQ and MQSET metrics

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

Prometheus metric name Metric type Short description MQ metric element
mqobject_mqinq_mqinq_count_totalcalls counter Shows the number of calls to MQINQ. MQINQ count
mqobject_mqset_mqset_count_totalcalls counter Shows the number of calls to MQSET. MQSET count
MQPUT and MQPUT1 metrics

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

Prometheus metric name Metric type Short description MQ metric element
mqobject_put_mqput_mqput1_count_totalcalls counter Shows the number of calls to MQPUT and MQPUT1. MQPUT/MQPUT1 count
mqobject_put_mqput_byte_count_totalbytes counter Shows the total bytes of data that is put by calls to MQPUT and MQPUT1. MQPUT byte count
mqobject_put_mqput_non_persistent_message_count_totalmessages counter Shows the number of non-persistent messages that are put by MQPUT. MQPUT non-persistent message count
mqobject_put_mqput_persistent_message_count_totalmessages counter Shows the number of persistent messages that are put by MQPUT. MQPUT persistent message count
mqobject_put_mqput1_non_persistent_message_count_totalmessages counter Shows the number of non-persistent messages that are put by MQPUT1. MQPUT1 non-persistent message count
mqobject_put_mqput1_persistent_message_count_totalmessages counter Shows the number of persistent messages that are put by MQPUT1. MQPUT1 persistent message count
mqobject_put_non_persistent_byte_count_totalbytes counter Shows the number of bytes put in non-persistent messages. non-persistent byte count
mqobject_put_persistent_byte_count_totalbytes counter Shows the number of bytes put in persistent messages. persistent byte count
mqobject_put_queue_avoided_puts_percentage gauge Shows the percentage of messages that avoided put - if a message is put to a queue when there is a waiting getter, the message may not need to be queued as it may be possible for it to be passed to the getter immediately. queue avoided puts
mqobject_put_queue_avoided_bytes_percentage gauge Shows the percentage of bytes that avoided put - if a message is put to a queue when there is a waiting getter, the message may not need to be queued as it may be possible for it to be passed to the getter immediately. queue avoided bytes
mqobject_put_lock_contention_percentage gauge Shows the percentage of attempts to lock the queue that resulted in waiting for another process to release the lock first. lock contention
MQGET metrics

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

Prometheus metric name Metric type Short description MQ metric element
mqobject_get_mqget_count_totalcalls counter Shows the number of calls to MQGET. MQGET count
mqobject_get_mqget_byte_count_totalbytes counter Shows the total bytes of data that is got by calls to MQGET. MQGET byte count
mqobject_get_destructive_mqget_non_persistent_message_count_totalmessages counter Number of non-persistent messages that are removed from the queue by MQGET. destructive MQGET non-persistent message count
mqobject_get_destructive_mqget_persistent_message_count_totalmessages counter Number of persistent messages that are removed from the queue by MQGET. destructive MQGET persistent message count
mqobject_get_destructive_mqget_non_persistent_byte_count_totalbytes counter Shows a count of bytes of non-persistent messages that are returned to MQGET. destructive MQGET non-persistent byte count
mqobject_get_destructive_mqget_persistent_byte_count_totalbytes counter Shows a count of bytes of persistent messages that are returned to MQGET. destructive MQGET persistent byte count
mqobject_get_mqget_browse_non_persistent_message_count_totalmessages counter Shows a count of non-persistent messages that have been browsed. MQGET browse non-persistent message count
mqobject_get_mqget_browse_persistent_message_count_totalmessages counter Shows a count of persistent messages that have been browsed. MQGET browse persistent message count
mqobject_get_mqget_browse_non_persistent_byte_count_totalbytes counter Shows the number of bytes of non-persistent messages that have been browsed. MQGET browse non-persistent byte count
mqobject_get_mqget_browse_persistent_byte_count_totalbytes counter Shows the number of bytes of persistent messages that have been browsed. MQGET browse persistent byte count
mqobject_queue_messages_expired_totalmessages counter Shows a count of expired messages. messages expired
mqobject_queue_queue_purged_count_totalqueues counter Shows a count of queues that have been purged. queue purged count
mqobject_queue_average_queue_time_microseconds gauge Shows the average latency of messages that are retrieved from the queue. average queue time
mqobject_queue_queue_depth_messages gauge Shows the number of messages on the queue. Queue depth

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.

Prometheus metric name Metric type Short description
mqobject_queue_queue_max_depth_messages gauge Shows maximum number of messages that are allowed on the queue.
mqobject_queue_queue_fill_percentage gauge Shows queue fill percentage.
mqobject_queue_queue_get_inhibited_untyped gauge Returns 0 if get is allowed and 1 otherwise.
mqobject_queue_queue_put_inhibited_untyped gauge Returns 0 if put is allowed and 1 otherwise.
mqobject_channel_channel_status_untyped gauge Shows current channel status. Mapping of channel statuses to prometheus metric values can be found here.
mqobject_listener_listener_status_untyped gauge Shows current listener status. Mapping of listener statuses to prometheus metric values can be found here.
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.

MQ channel status code Prometheus metric value
RUNNING 100
REQUESTING 90
PAUSED 80
BINDING 70
STARTING 60
INITIALIZING 50
SWITCHING 40
STOPPING 30
RETRYING 20
STOPPED 10
INACTIVE 0

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.

MQ listener status code Prometheus metric value
RUNNING 100
STARTING 75
STOPPING 50
STOPPED 0

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.