Queue Depth

Queue depth is the heartbeat metric of IBM MQ operations: how many messages are waiting on a queue right now. DISPLAY QLOCAL shows CURDEPTH; your metrics platform charts it every thirty seconds; on-call rules fire when utilization crosses policy limits. Beginners watch depth spike and restart queue managers—a destructive habit when the real issue is a stopped consumer or a channel in RETRY. This tutorial explains what depth measures, related attributes on DISPLAY QLOCAL (MAXDEPTH, IPPROCS, OPPROCS, UNCOMMITTED messages context), how depth behaves under syncpoint and browse, exporting depth to Prometheus and viewing in Grafana, threshold design, distinguishing local queue depth from transmission queue backlog, z/OS shared queue nuances, and troubleshooting playbooks when depth grows without obvious cause.

What CURDEPTH Represents

Each successful MQPUT or equivalent put adds one message to the queue depth count (persistent messages survive restarts; non-persistent follow queue rules on restart). Each successful MQGET with default options removes one message and lowers CURDEPTH. Browse without get does not reduce depth. Transactions under syncpoint hold messages in a way that affects visibility depending on get options and UOW state—operators during incidents should know if consumers use syncpoint and whether uncommitted gets hide messages from other consumers. Depth is a point-in-time snapshot; two queues with depth 1000 can mean different severity if one drains at ten thousand messages per second and the other has zero get rate.

Depth vs Utilization

Absolute alert: CURDEPTH greater than 50000. Works when all tier-1 queues use MAXDEPTH 100000. Utilization alert: CURDEPTH divided by MAXDEPTH greater than 0.8. Works when MAXDEPTH varies from 1000 to 500000 across applications. A queue at depth 900 with MAXDEPTH 1000 is ninety percent full and more urgent than depth 900 with MAXDEPTH 1000000. Exporters should expose both raw depth and max depth labels or a precomputed ratio metric to simplify Grafana stat panels.

1
2
3
4
DISPLAY QLOCAL('ORDERS.IN') CURDEPTH MAXDEPTH IPPROCS OPPROCS MONQ
* Example reading:
* CURDEPTH(45230) MAXDEPTH(100000) IPPROCS(3) OPPROCS(0)
* Interpretation: producers active, no open getters — investigate consumers

Queue Monitoring Events

ALTER QLOCAL MONQ(ENABLED) with queue manager event configuration allows depth high and depth low events to appear on the system event queue or event streams your tooling consumes. Events complement metrics: an event might fire at a threshold defined in queue attributes while Prometheus scrapes every thirty seconds and might miss a brief spike. Use both for tier-1 queues. Event parameters include QDEPTHHI, QDEPTHLO, QDPHIEV, QDPLOEV per attribute names on your MQ version—verify exact spellings in product documentation before scripting ALTER commands.

Exporting Depth to Metrics Platforms

1. Deploy MQ metrics exporter with credentials to DISPLAY queues.
2. Exporter issues PCF INQUIRE or equivalent on schedule.
3. Prometheus scrapes gauge ibmmq_queue_depth or vendor-specific name.
4. Grafana plots time series; Alertmanager or Grafana alerts on threshold.
5. Instana or Dynatrace sensors may collect same attribute without Prometheus.

Cardinality warning: labeling every queue name on a cluster with ten thousand queues creates ten thousand series. Filter exporter config to application queues, use regex include lists, or aggregate by queue manager for NOC dashboards and drill to name only in Console during incidents.

Local Queue vs Transmission Queue Depth

Growing depth on a local application queue usually means slow or stopped consumers on that queue manager. Growing depth on a transmission queue (XMITQ) means messages cannot leave the queue manager—channel STOPPED, RETRY, partner down, or network failure. Alerting rules should tag queue type in runbooks. DISPLAY QLOCAL on XMITQ names tied to SDR channels; DISPLAY CHSTATUS on the paired channel when XMITQ depth rises.

Shared Queues on z/OS

In queue sharing groups, depth may reflect shared message storage in coupling facility structures. Monitoring tools must use APIs that report correct depth for shared queues on the queue manager you query. Capacity planning includes CF structure utilization, not only CURDEPTH on paper. Beginners on z/OS should read CF structure high-water marks alongside queue depth tiles.

Troubleshooting Rising Depth

1. Confirm CURDEPTH and MAXDEPTH; compute utilization.
2. Check OPPROCS: are getters connected?
3. Compare put rate and get rate from statistics or metrics.
4. Sample messages: poison pattern, huge payload, bad format?
5. Consumer logs, JVM hangs, database locks downstream of MQ.
6. For XMITQ, channel status and partner queue manager health.
7. Avoid CLEAR QLOCAL without change approval—data loss risk.

Alert Threshold Examples

• Warning: utilization greater than seventy percent for fifteen minutes on tier-1 list.
• Critical: utilization greater than ninety percent for five minutes.
• Rate-based: derivative of depth positive while OPPROCS equals zero for ten minutes.
• Maintenance: silence alerts during known batch window with documented expected depth shape.

Explainer: Line at the Coffee Shop

Queue depth is how many people stand in line. MAXDEPTH is fire code capacity. Baristas are consumers; customers ordering are producers. A long line with no baristas means fix staffing, not demolish the building (restart QM without analysis).

Explain Like I'm Five: Queue Depth

Queue depth is how many letters are in the mailbox. If more letters keep arriving and nobody takes them out, the mailbox gets full and new letters cannot fit.

Practice Exercises

Exercise 1

Given CURDEPTH 8500 and MAXDEPTH 10000, write warning and critical alert thresholds as percentages.

Exercise 2

Interpret IPPROCS 5 OPPROCS 0 with rising depth—list three investigation steps.

Exercise 3

Design exporter filter list for twenty tier-1 queues instead of all queues on QM.

Frequently Asked Questions

Test Your Knowledge