IBM MQ

Plugin: ibm.d.plugin Module: mq

Overview

Monitors IBM MQ queue managers, queues, channels, and topics using the PCF (Programmable Command Format) protocol.

By default the collector tracks the critical system queues SYSTEM.DEAD.LETTER.QUEUE, SYSTEM.ADMIN.COMMAND.QUEUE, and SYSTEM.ADMIN.STATISTICS.QUEUE. All other queues are opt-in via the include_queues list, with exclude_queues removing noisy patterns such as SYSTEM.* or AMQ.*. Include patterns take precedence over excludes so you can safely monitor individual system queues while dropping the broader wildcard.

Per-queue charts are bounded by max_queues (default 50). When more queues are discovered, the collector exports the busiest ones individually, rolls the remainder into an aggregated __other__ dimension, and logs a throttled warning listing the overflowed groups. Parallel queue-group charts summarise depth, traffic, and backlog per naming prefix (first two dot-separated segments, collapsing all SYSTEM.* queues together), so high-level visibility is never lost even when detailed charts are trimmed.

The collector connects to IBM MQ and collects metrics via its monitoring interface.

This collector is supported on all platforms.

This collector supports collecting metrics from multiple instances of this integration, including remote instances.

Default Behavior

Auto-Detection

This integration doesn't support auto-detection.

Limits

The default configuration for this integration does not impose any limits on data collection.

Performance Impact

The default configuration for this integration is not expected to impose a significant performance impact on the system.

Setup

Prerequisites

Enable monitoring interface

Ensure the IBM MQ monitoring interface is accessible.

Configuration

Options

Configuration options for the mq collector.

Config options

Option	Description	Default	Required
update_every	Data collection frequency.	1	no
endpoint	Connection endpoint.	dummy://localhost	no

via File

The configuration file name for this integration is ibm.d/mq.conf.

You can edit the configuration file using the edit-config script from the Netdata config directory.

cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
sudo ./edit-config ibm.d/mq.conf

Examples

Basic

Basic configuration example.

Config

jobs:
  - name: local
    endpoint: dummy://localhost

Alerts

There are no alerts configured by default for this integration.

Metrics

Metrics grouped by scope.

The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels.

Per channel

These metrics refer to channel instances.

Labels:

Label	Description
channel	Channel identifier
type	Type identifier

Metrics:

Metric	Description	Dimensions	Unit
mq.channel.status	Channel Status	inactive, binding, starting, running, stopping, retrying, stopped, requesting, paused, disconnected, initializing, switching	status
mq.channel.messages	Channel Message Rate	messages	messages/s
mq.channel.bytes	Channel Data Transfer Rate	bytes	bytes/s
mq.channel.batches	Channel Batch Rate	batches	batches/s
mq.channel.batch_size	Channel Batch Size	batch_size	messages
mq.channel.batch_interval	Channel Batch Interval	batch_interval	milliseconds
mq.channel.intervals	Channel Intervals	disc_interval, hb_interval, keep_alive_interval	seconds
mq.channel.short_retry_count	Channel Short Retry Count	short_retry	retries
mq.channel.long_retry_interval	Channel Long Retry Interval	long_retry	seconds
mq.channel.max_msg_length	Channel Max Message Length	max_msg_length	bytes
mq.channel.sharing_conversations	Channel Sharing Conversations	sharing_conversations	conversations
mq.channel.network_priority	Channel Network Priority	network_priority	priority
mq.channel.buffer_counts	Channel Buffer Counts	sent, received	buffers
mq.channel.current_messages	Channel Current Messages	current	messages
mq.channel.xmitq_time	Channel Transmission Queue Time	xmitq_time	milliseconds
mq.channel.mca_status	Channel MCA Status	mca_status	status
mq.channel.indoubt_status	Channel In-Doubt Status	indoubt_status	status
mq.channel.ssl_key_resets	Channel SSL Key Resets	ssl_key_resets	resets
mq.channel.npm_speed	Channel Non-Persistent Message Speed	npm_speed	speed
mq.channel.current_sharing_convs	Channel Current Sharing Conversations	current_sharing	conversations

Per channelstatistics

These metrics refer to channelstatistics instances.

Labels:

Label	Description
channel	Channel identifier
type	Type identifier

Metrics:

Metric	Description	Dimensions	Unit
mq.channel_stats.messages	Channel Messages (Statistics)	messages	messages/s
mq.channel_stats.bytes	Channel Bytes (Statistics)	bytes	bytes/s
mq.channel_stats.batches	Channel Batches (Statistics)	full_batches, incomplete_batches	batches/s
mq.channel_stats.batch_size	Channel Average Batch Size (Statistics)	avg_batch_size	messages
mq.channel_stats.put_retries	Channel Put Retries (Statistics)	put_retries	retries/s

Per listener

These metrics refer to listener instances.

Labels:

Label	Description
listener	Listener identifier
port	Port identifier
ip_address	Ip_address identifier

Metrics:

Metric	Description	Dimensions	Unit
mq.listener.status	Listener Status	stopped, starting, running, stopping, retrying	status
mq.listener.backlog	Listener Connection Backlog	backlog	connections
mq.listener.uptime	Listener Uptime	uptime	seconds

Per mqistatistics

These metrics refer to mqistatistics instances.

Labels:

Label	Description
queue_manager	Queue_manager identifier

Metrics:

Metric	Description	Dimensions	Unit
mq.mqi_stats.opens	MQOPEN Operations (Statistics)	opens_total, opens_failed	operations/s
mq.mqi_stats.closes	MQCLOSE Operations (Statistics)	closes_total, closes_failed	operations/s
mq.mqi_stats.inqs	MQINQ Operations (Statistics)	inqs_total, inqs_failed	operations/s
mq.mqi_stats.sets	MQSET Operations (Statistics)	sets_total, sets_failed	operations/s

Per queue

These metrics refer to queue instances.

Labels:

Label	Description
queue	Queue identifier
type	Type identifier

Metrics:

Metric	Description	Dimensions	Unit
mq.queue.depth	Queue Depth	current, max	messages
mq.queue.depth_percentage	Queue Depth Percentage	percentage	percentage
mq.queue.messages	Queue Messages	enqueued, dequeued	messages/s
mq.queue.connections	Queue Connections	input, output	connections
mq.queue.high_depth	Queue Peak Depth	high_depth	messages
mq.queue.uncommitted_msgs	Queue Uncommitted Messages	uncommitted	messages
mq.queue.file_size	Queue File Size	current, max	bytes
mq.queue.last_activity	Time Since Last Queue Activity	since_last_get, since_last_put	seconds
mq.queue.oldest_msg_age	Queue Oldest Message Age	oldest_msg_age	seconds
mq.queue.time_indicators	Queue Time Indicators	short_period, long_period	microseconds
mq.queue.service_interval	Queue Service Interval	service_interval	milliseconds
mq.queue.inhibit_status	Queue Inhibit Status	inhibit_get, inhibit_put	status
mq.queue.priority	Queue Priority Configuration	def_priority	priority
mq.queue.message_persistence	Queue Default Message Persistence	persistent, non_persistent	boolean
mq.queue.retention_interval	Queue Retention Interval	retention_interval	hours
mq.queue.triggers	Queue Trigger Configuration	trigger_depth, trigger_type	messages
mq.queue.backout_threshold	Queue Error Handling	backout_threshold	retries
mq.queue.max_msg_length	Queue Max Message Length	max_msg_length	bytes
mq.queue.scope	Queue Scope	queue_manager, cell	boolean
mq.queue.usage	Queue Usage Type	normal, transmission	boolean
mq.queue.msg_delivery_sequence	Message Delivery Sequence	priority, fifo	boolean
mq.queue.harden_get_backout	Harden Get Backout	enabled, disabled	boolean

Per queuegroup

These metrics refer to queuegroup instances.

Labels:

Label	Description
group	Group identifier

Metrics:

Metric	Description	Dimensions	Unit
mq.queue_group.depth	Queue Group Depth	current, max	messages
mq.queue_group.depth_percentage	Queue Group Depth Percentage	percentage	percentage
mq.queue_group.messages	Queue Group Messages	enqueued, dequeued	messages/s
mq.queue_group.connections	Queue Group Connections	input, output	connections
mq.queue_group.uncommitted_msgs	Queue Group Uncommitted Messages	uncommitted	messages
mq.queue_group.file_size	Queue Group File Size	current, max	bytes
mq.queue_group.oldest_msg_age	Queue Group Oldest Message Age	oldest_msg_age	seconds

Per IBM MQ instance

These metrics refer to the entire monitored instance.

This scope has no labels.

Metrics:

Metric	Description	Dimensions	Unit
mq.qmgr.status	Queue Manager Status	status	status
mq.qmgr.connection_count	Queue Manager Connections	connections	connections
mq.qmgr.uptime	Queue Manager Uptime	uptime	seconds
mq.queues.overview	Queues Monitoring Status	monitored, excluded, invisible, failed	queues
mq.channels.overview	Channels Monitoring Status	monitored, excluded, invisible, failed	channels
mq.topics.overview	Topics Monitoring Status	monitored, excluded, invisible, failed	topics
mq.listeners.overview	Listeners Monitoring Status	monitored, excluded, invisible, failed	listeners

Per IBM MQ instance

These metrics refer to the entire monitored instance.

This scope has no labels.

Metrics:

Metric	Description	Dimensions	Unit
mq.qmgr.cpu_usage	Queue Manager CPU Usage	user, system	percentage
mq.qmgr.memory_usage	Queue Manager Memory Usage	total	bytes
mq.qmgr.ram_usage	Queue Manager RAM Usage	total	bytes
mq.qmgr.log_utilization	Queue Manager Log Utilization	used	percentage
mq.qmgr.log_file_size	Queue Manager Log File Size	size	bytes
mq.qmgr.log_write_rate	Queue Manager Log Write Rate	rate	bytes/s

Per queuestatistics

These metrics refer to queuestatistics instances.

Labels:

Label	Description
queue	Queue identifier
type	Type identifier

Metrics:

Metric	Description	Dimensions	Unit
mq.queue_stats.depth_min_max	Queue Depth Min/Max (Statistics)	min_depth, max_depth	messages
mq.queue_stats.avg_queue_time	Queue Average Time (Statistics)	non_persistent, persistent	microseconds
mq.queue_stats.time_indicators	Queue Time Indicators (Statistics)	short_period, long_period	microseconds
mq.queue_stats.operations	Queue Operations (Statistics)	puts_non_persistent, puts_persistent, gets_non_persistent, gets_persistent, put1s, browses	operations/s
mq.queue_stats.bytes	Queue Bytes (Statistics)	put_bytes_non_persistent, put_bytes_persistent, get_bytes_non_persistent, get_bytes_persistent, browse_bytes	bytes/s
mq.queue_stats.failures	Queue Operation Failures (Statistics)	puts_failed, put1s_failed, gets_failed, browses_failed	failures/s
mq.queue_stats.message_lifecycle	Queue Message Lifecycle (Statistics)	expired, purged, not_queued	messages/s

Per subscription

These metrics refer to subscription instances.

Labels:

Label	Description
subscription	Subscription identifier
topic	Topic identifier

Metrics:

Metric	Description	Dimensions	Unit
mq.subscription.messages	IBM MQ Subscription Messages	pending	messages
mq.subscription.last_message_age	IBM MQ Subscription Last Message Age	age	seconds

Per topic

These metrics refer to topic instances.

Labels:

Label	Description
topic	Topic identifier

Metrics:

Metric	Description	Dimensions	Unit
mq.topic.publishers	Topic Publishers	publishers	publishers
mq.topic.subscribers	Topic Subscribers	subscribers	subscribers
mq.topic.messages	Topic Message Rate	messages	messages/s
mq.topic.time_since_last_message	Time Since Last Message	time_since_last_msg	seconds