IBM MQ OpenTelemetry metrics and attributes reference

This reference covers the IBM MQ metrics and attributes collected via OpenTelemetry: the metrics the mq-metric-samples exporter publishes and the collector forwards to New Relic. It applies to both the Linux host and Kubernetes deployments; the metric shape is identical.

Metric collection

All metrics keep the raw Prometheus shape the exporter emits: underscore names (ibmmq_*) and the raw qmgr, queue, and channel labels, plus the target.name identity attribute and optional cluster.name tag the collector attaches. New Relic's IBM MQ entity synthesis depends on this shape, so the collector forwards the names and labels unchanged.

Important

Enable MQI statistics on each queue manager, or the throughput and timing metrics stay empty. Queue-manager health, queue depth, and channel status report out of the box, but the MQI activity metrics (the queue throughput and queue manager MQI activity tables — ibmmq_queue_mqput_count, ibmmq_queue_average_queue_time_seconds, and so on) require statistics collection to be on, which is off by default. Enable it once per queue manager with MQSC — for example ALTER QMGR STATMQI(ON) STATQ(ON), then ALTER QLOCAL(...) STATQ(ON) for any queue you want per-queue stats on (or rely on the queue-manager STATQ default). Without this, the exporter is healthy and the entity appears, but those panels render blank. See the mq-metric-samples documentation for the exact statistics each metric depends on.

Conseil

Status metrics report numeric enum values, not 1/0 — see the status-code reference below before alerting on them. Counters are converted to delta temporality by the collector, so use sum() / rate() over a window rather than latest() when charting them.

The tables below group the OpenTelemetry metrics by area. To list every metric actually reporting in your account, run:

FROM Metric SELECT uniques(metricName, 2000) WHERE metricName LIKE 'ibmmq_%' SINCE 1 day ago

Metrics

Queue manager health and status

Metric	Description
`ibmmq_qmgr_status`	Queue manager run state (`2` = running).
`ibmmq_qmgr_command_server_status`	Command server run state (`2` = running).
`ibmmq_qmgr_channel_initiator_status`	Channel initiator (the queue-manager process that starts and manages MQ channels) run state (`2` = running).
`ibmmq_qmgr_connection_count`	Current number of connections to the queue manager.
`ibmmq_qmgr_uptime`	Queue manager uptime, in seconds.
`ibmmq_qmgr_active_listeners`	Number of active listeners.
`ibmmq_qmgr_active_services`	Number of active services.
`ibmmq_qmgr_concurrent_connections_high_water_mark`	Peak concurrent connections.

Queue manager resources (CPU, memory, log, file system)

Metric	Description
`ibmmq_qmgr_cpu_load_one_minute_average_percentage`	1-minute CPU load average for the queue manager (also `_five_` and `_fifteen_minute_`).
`ibmmq_qmgr_user_cpu_time_percentage`	User-space CPU time consumed by the queue manager.
`ibmmq_qmgr_system_cpu_time_percentage`	System (kernel) CPU time consumed by the queue manager.
`ibmmq_qmgr_ram_total_bytes`	Total RAM on the host.
`ibmmq_qmgr_ram_free_percentage`	Percentage of host RAM free.
`ibmmq_qmgr_ram_total_estimate_for_queue_manager_bytes`	Estimated RAM in use by this queue manager.
`ibmmq_qmgr_log_in_use_bytes`	Recovery log space currently in use.
`ibmmq_qmgr_log_max_bytes`	Maximum recovery log size.
`ibmmq_qmgr_log_current_primary_space_in_use_percentage`	Primary log space utilization.
`ibmmq_qmgr_log_file_system_free_space_bytes`	Free space on the log file system.
`ibmmq_qmgr_log_write_latency_seconds`	Recovery log write latency.
`ibmmq_qmgr_queue_manager_file_system_in_use_bytes`	Queue manager file system space in use.
`ibmmq_qmgr_queue_manager_file_system_free_space_percentage`	Free space on the queue manager file system.
`ibmmq_qmgr_mq_fdc_file_count`	Number of IBM MQ diagnostic dump files (FFST/FDC — written when the queue manager logs an internal error). A rising count signals problems worth investigating.

Queue depth, age, and handles

Metric	Description
`ibmmq_queue_depth`	Current number of messages on the queue.
`ibmmq_queue_attribute_max_depth`	Configured maximum queue depth.
`ibmmq_queue_oldest_message_age`	Age of the oldest message on the queue, in seconds.
`ibmmq_queue_uncommitted_messages`	Number of uncommitted messages.
`ibmmq_queue_time_since_put`	Seconds since the last `MQPUT` to the queue.
`ibmmq_queue_time_since_get`	Seconds since the last `MQGET` from the queue.
`ibmmq_queue_input_handles`	Open input handles (consumers) on the queue.
`ibmmq_queue_output_handles`	Open output handles (producers) on the queue.
`ibmmq_queue_browse_handles`	Open browse handles on the queue.
`ibmmq_queue_publish_handles`	Open publish handles on the queue.
`ibmmq_queue_qfile_current_size`	Current queue file size on disk.
`ibmmq_queue_qfile_max_size`	Maximum queue file size on disk.

Queue throughput and timing (MQI)

These counters track IBM MQ's core message API calls per queue: MQPUT / MQPUT1 (put a message onto a queue) and MQGET (get a message from a queue). They require MQI statistics to be enabled on the queue manager (see Metric collection).

Metric	Description
`ibmmq_queue_mqput_count`	`MQPUT`/`MQPUT1` operations against the queue.
`ibmmq_queue_mqget_count`	`MQGET` operations against the queue.
`ibmmq_queue_mqput_bytes` / `ibmmq_queue_mqget_bytes`	Bytes put to / got from the queue.
`ibmmq_queue_mqput_non_persistent_message_count` / `ibmmq_queue_mqput_persistent_message_count`	Non-persistent / persistent messages put.
`ibmmq_queue_average_queue_time_seconds`	Average time messages spent on the queue.
`ibmmq_queue_qtime_short` / `ibmmq_queue_qtime_long`	Short- / long-interval queue-time samples.
`ibmmq_queue_avoided_puts_percentage`	Percentage of puts that went straight to a waiting getter.
`ibmmq_queue_expired_messages`	Messages that expired on the queue.
`ibmmq_queue_rolled_back_mqget_count` / `ibmmq_queue_rolled_back_mqput_count`	Rolled-back gets / puts.

Channel metrics

Metric	Description
`ibmmq_channel_status`	Channel run state (`3` = running).
`ibmmq_channel_status_squash`	Simplified channel status with fewer enum values (informational; for alerting, use `ibmmq_channel_status` and the status-code reference).
`ibmmq_channel_messages`	Messages sent over the channel.
`ibmmq_channel_bytes_sent` / `ibmmq_channel_bytes_rcvd`	Bytes sent / received.
`ibmmq_channel_buffers_sent` / `ibmmq_channel_buffers_rcvd`	Transmission buffers sent / received.
`ibmmq_channel_cur_inst`	Current number of running channel instances.
`ibmmq_channel_attribute_max_inst` / `ibmmq_channel_attribute_max_instc`	Max instances total / per client.
`ibmmq_channel_time_since_msg`	Seconds since the last message on the channel.
`ibmmq_channel_type` / `ibmmq_channel_instance_type`	Channel type / instance type.
`ibmmq_channel_substate`	Channel sub-state.

Queue manager MQI activity and errors

These queue-manager-wide counters summarize API activity and failures across all objects — useful for spotting application errors and transaction churn. They require MQI statistics to be enabled (see Metric collection).

Metric	Description
`ibmmq_qmgr_interval_mqput_mqput1_total_count`	Total `MQPUT` + `MQPUT1` calls in the interval.
`ibmmq_qmgr_interval_destructive_get_total_count`	Total destructive `MQGET` calls in the interval.
`ibmmq_qmgr_published_to_subscribers_message_count`	Messages published to subscribers (publish/subscribe throughput).
`ibmmq_qmgr_mqopen_count` / `ibmmq_qmgr_mqclose_count`	Total `MQOPEN` / `MQCLOSE` calls.
`ibmmq_qmgr_mqconn_mqconnx_count` / `ibmmq_qmgr_mqdisc_count`	Connect / disconnect calls.
`ibmmq_qmgr_commit_count` / `ibmmq_qmgr_rollback_count`	Transaction commits / rollbacks.
`ibmmq_qmgr_failed_mqput_count` / `ibmmq_qmgr_failed_mqput1_count`	Failed `MQPUT` / `MQPUT1` calls.
`ibmmq_qmgr_failed_mqget_count` / `ibmmq_qmgr_failed_mqopen_count`	Failed get / open calls.
`ibmmq_qmgr_failed_mqconn_mqconnx_count`	Failed connect calls.
`ibmmq_qmgr_expired_message_count`	Messages expired across the queue manager.
`ibmmq_qmgr_purged_queue_count`	Queues purged.

MQ status-code reference

IBM MQ status metrics report numeric enum values, not 1/0 — and the healthy ("running") value differs by metric (2 for queue-manager-level status, 3 for channel status). Alert on inequality to the running value (for example, ibmmq_qmgr_status != 2):

Metric	Healthy value	Meaning
`ibmmq_qmgr_status`	`2`	Queue manager is running
`ibmmq_qmgr_command_server_status`	`2`	Command server is running
`ibmmq_qmgr_channel_initiator_status`	`2`	Channel initiator is running
`ibmmq_channel_status`	`3`	Channel is running

Any other value (or a missing data point) means the component is not in its running state.

Resource attributes

The collector attaches identity and context attributes to every IBM MQ metric. Some are common to all deployments; others depend on whether the collector runs on a Linux host or in Kubernetes.

Common attributes

Attribute	Description	Example
`target.name`	Stable identity attribute — the first segment of every IBM MQ entity GUID. Injected as the `targetName` scrape label, then renamed to `target.name` by the collector.	`prod-mq-01`, `prod-mq-cluster`
`qmgr`	Queue manager name (raw exporter label; entity synthesis keys on it).	`QM1`
`queue`	Queue name (on queue-scoped metrics).	`APP.ORDERS.IN`
`channel`	Channel name (on channel-scoped metrics).	`APP.SVRCONN`
`cluster.name`	Optional grouping tag for queue managers in the same MQ cluster. Not part of the entity GUID; safe to leave unset or change later.	`prod-mq`
`instrumentation.provider`	Always `opentelemetry` for this integration; use it to scope queries to the OpenTelemetry path.	`opentelemetry`

On-host deployment attributes

Attribute	Description	Example
`host.id`	Identifier of the host running the collector, from the `resourcedetection` processor (`system` / `ec2` detectors). Links the queue manager to its underlying host entity.	`i-1234567890abcdef0`

Kubernetes deployment attributes

Attribute	Description	Example
`k8s_namespace`	Namespace of the discovered exporter pod, stamped by the collector's relabel rules.	`ibmmq`
`k8s_pod`	Name of the discovered exporter pod.	`qm1-0`
`host.id`	Identifier of the node running the pod, from `resourcedetection`.	`ip-10-0-1-23`

Metric collection details

Collection frequency

Default interval: 60 seconds (the collector's scrape_interval). It must be greater than or equal to the mq-metric-samples exporter's own pollInterval.
Configurable: adjust IBMMQ_SCRAPE_INTERVAL (Linux) or scrape_interval in the Helm values.yaml (Kubernetes).

Data source

All metrics originate from the mq-metric-samples exporter, which polls each queue manager over PCF and republishes the statistics as Prometheus metrics on an HTTP /metrics endpoint. The collector's prometheus receiver scrapes that endpoint.

Metric types

Gauges — point-in-time values such as ibmmq_qmgr_status, ibmmq_queue_depth, and ibmmq_channel_status. Chart with latest().
Counters — cumulative totals such as ibmmq_queue_mqput_count. The collector's cumulativetodelta processor converts them to delta temporality, so chart with sum() or rate() rather than latest().

Self-hosted instrumentation for IBM MQ

Learn how to set up your IBM MQ for self-hosted monitoring in New Relic.

Kubernetes instrumentation for IBM MQ

Learn how to set up your IBM MQ for Kubernetes monitoring in New Relic.

View and query your data

Learn how to view and query your IBM MQ data in New Relic.