Contents
Why queue depth is a key metric
If an operator could monitor only one PowerMTA metric, queue depth would be a strong candidate, because it is the single number that most reliably signals when something has gone wrong with delivery. A growing PowerMTA queue is the visible symptom of nearly any delivery problem, and an operator alerted to a growing queue gets a prompt, general warning that delivery health has degraded, in time to investigate before the problem becomes severe.
This guide exists to cover queue depth monitoring properly, both the understanding and the practical setup. The structure of this guide: why queue depth is a key metric, what queue depth tells an operator, the important distinction between a healthy fluctuating queue and a genuinely growing one, how to monitor queue depth through PowerMTA's interfaces, setting a sensible alerting threshold, per-domain queue monitoring to localize a problem, integrating PowerMTA queue metrics into a monitoring system, and the diagnostic workflow when the queue is growing.
What queue depth tells an operator
The PowerMTA queue depth is the number of messages waiting in PowerMTA's queues to be delivered. What it tells an operator is the balance between two rates: the rate at which mail is entering PowerMTA and the rate at which PowerMTA is successfully delivering it.
| Queue behavior | What it means |
|---|---|
| Low and stable | Delivery is keeping up with inflow |
| Growing | Mail is entering faster than it is being delivered |
| Draining after a peak | A normal injection being worked off |
When PowerMTA delivers mail as fast as it arrives, the queue stays low and stable, messages enter, get delivered, and leave, and the queue is just the small working set in flight at any moment. When mail enters faster than PowerMTA delivers it, the queue grows, because the undelivered messages accumulate.
So queue depth is a real-time indicator of delivery health. A low, stable queue means delivery is keeping up. A growing queue means delivery is not keeping up, something is slowing the outflow, and the queue is the visible accumulation of the gap.
This is what makes queue depth so valuable: a growing queue is an early, general signal that something is wrong, before the operator might notice the specific cause. The queue can grow for many reasons, a receiver throttling the sender, a reputation problem causing widespread deferrals, a configuration limit, a DNS problem, a surge of inbound volume, but whatever the cause, it shows up as a growing queue. Queue depth does not by itself tell the operator what is wrong, but it reliably tells them that something is, which is exactly what an early-warning metric should do.
A healthy queue versus a growing one
An important subtlety: a healthy PowerMTA queue is not static. It fluctuates, and distinguishing a healthy fluctuating queue from a genuinely growing one is essential to monitoring it well.
A healthy queue rises and falls with the normal rhythm of sending. When a campaign is injected, a burst of mail enters PowerMTA and the queue rises; then as PowerMTA delivers that mail, the queue falls back down. So an elevated queue depth at a particular moment does not by itself mean a problem, it might just be the normal post-injection peak that will drain.
What indicates a problem is a queue that grows and does not drain, a sustained upward trend rather than a peak that recedes.
The instantaneous queue depth is not enough to distinguish a normal campaign injection peak from the start of a sustained climb. A queue at an elevated number could be a peak about to drain or the beginning of a real problem, and a single look cannot tell which. This is why queue monitoring must be continuous and trended, not a spot check. A healthy queue, plotted over time, shows peaks that rise and fall back toward a stable baseline; a problem queue shows a line that keeps climbing, or that settles at a new higher baseline and does not return to the old one. The trend over time is what makes the distinction; the instantaneous number cannot.
This has a direct implication for alerting, covered below: a good queue alert is not simply triggered by the queue exceeding a number, because that would fire on every normal campaign peak. It should catch a queue that is elevated and sustained.
How to monitor queue depth
PowerMTA provides built-in interfaces for observing the queue depth.
The HTTP monitoring interface. PowerMTA exposes a web-based monitoring interface that shows its operational state, including the queues, their depths, and the per-domain breakdown. This HTTP interface is the primary window into queue depth. Importantly, it also exposes the data in a machine-readable form, which is what allows a monitoring system to scrape it programmatically.
The pmta command-line tool. From the command line, the pmta show queues command displays the current queues and their depths:
# Show the current queues and their depths
pmta show queues
# Show top queues by recipient count
pmta show queues --orderby=rcpt --num=20This is useful for an immediate look at the queue state, for instance when investigating a problem.
For ongoing monitoring, though, an operator does not want to be manually checking the HTTP interface or running pmta show queues. They want a monitoring system that continuously collects the queue depth and trends it, so that the trend is always visible and an alert fires automatically. The manual interfaces are for spot investigation; continuous monitoring requires the integration covered below.
Setting a sensible alerting threshold
The point of monitoring queue depth is to be alerted when the queue indicates a problem, and designing the alert well matters, because a poorly-designed queue alert either misses problems or fires constantly on normal peaks.
The principles for a sensible queue alert:
Alert on sustained elevation, not a momentary number. As established, a queue exceeding a number momentarily is often just a normal injection peak. An alert that fires the instant the queue crosses a threshold will fire on every campaign. The alert should require the queue to be above the threshold for a meaningful duration, sustained for, say, a period of many minutes, before firing. This catches a queue that is genuinely not draining while ignoring normal peaks.
Set the threshold relative to the deployment's normal. There is no universal correct queue depth threshold, it depends on the deployment's volume and normal queue behavior. The operator should observe their queue's normal range, the typical baseline and the typical peak heights, and set the threshold above the normal peaks, so the alert distinguishes abnormal from normal for that specific deployment.
Consider alerting on the trend, not just the level. A more sophisticated alert looks at the rate of change: a queue that is climbing steadily, regardless of its current absolute number, is a problem. Alerting on a sustained upward trend can catch a problem earlier than waiting for an absolute threshold.
Make the alert actionable. The alert should reach the operator promptly and through a channel they will see, and ideally carry enough context, which is where per-domain monitoring helps, to begin the investigation.
A well-designed queue alert is one that stays quiet through normal sending and fires reliably when the queue is genuinely growing and not draining. Getting the sustained-duration and the threshold right for the specific deployment is what achieves that.
Per-domain queue monitoring
The total queue depth tells the operator that something is wrong; the per-domain queue breakdown tells them where.
PowerMTA's queues are organized per destination domain, and the HTTP monitoring interface and pmta show queues both expose the per-domain breakdown. This per-domain view is valuable for localization:
- A problem concentrated in one domain's queue points at a problem specific to that receiver, that receiver throttling the sender, a reputation problem with that receiver. If the gmail.com queue is growing while the others are normal, the problem is with Gmail.
- A problem across all domains' queues points at something general, a server-resource constraint, a DNS problem, a configuration issue affecting all sending, an inbound surge. If every domain's queue is growing together, the cause is not receiver-specific.
So per-domain queue monitoring turns the queue depth from a problem-exists signal into a problem-is-here signal. An operator monitoring the per-domain queues, not just the total, sees not only that the queue is growing but which destination is responsible, which is a substantial head start on the diagnosis.
The practical recommendation is to monitor both the total queue depth, as the overall health signal and the basis of the main alert, and the per-domain queue depths, at least for the major destinations, so that when the total queue alert fires, the per-domain view immediately shows where the problem is concentrated.
Integrating into a monitoring system
Turning queue depth into continuous, trended, alerted monitoring means integrating PowerMTA's queue metrics into a monitoring system.
The integration uses the HTTP monitoring interface's machine-readable data. The setup:
- The monitoring system polls the HTTP interface. The operator's monitoring and metrics platform periodically polls PowerMTA's HTTP monitoring interface, reading the queue depth, both total and per-domain, from the machine-readable data.
- The metrics are stored as a time series. The polled values are stored over time, so the trend is preserved and visible. This time series is what makes the healthy-versus-growing distinction possible.
- A dashboard displays the trend. The queue depth trend is displayed on a dashboard, so an operator can see the queue's behavior at a glance.
- Alerts are configured. The monitoring system's alerting fires on the queue conditions, the sustained-elevation or trend conditions described above.
PowerMTA's HTTP interface providing machine-readable data is what makes this integration straightforward, the monitoring system reads the queue depth the same way it reads any other metric it collects. The operator generally does not need a PowerMTA-specific monitoring tool; their existing monitoring platform can poll the HTTP interface.
The result is queue depth transformed from a number an operator can look up into an active early-warning system: continuously collected, trended so the healthy-versus-growing distinction is clear, displayed on a dashboard, and alerting automatically when the queue indicates a problem. This integrated queue monitoring is a core part of operating a PowerMTA deployment well, and it should be set up alongside the monitoring of the other key signals, the delivery and bounce rates from the accounting log, the server resources, the reputation.
When the queue is growing
When the queue monitoring alerts that the queue is growing, the diagnostic workflow:
Step 1: confirm it is sustained, not a peak. Check the trend. Confirm the queue is genuinely growing and not draining, rather than a normal injection peak. The trend on the dashboard shows this.
Step 2: check the per-domain breakdown. Look at the per-domain queues. Is the growth concentrated in one domain or spread across all? This localizes the problem immediately.
Step 3: for a one-domain problem, investigate that receiver. A queue growing for one domain points at that receiver, check the accounting log for that domain, 421 deferrals indicate throttling, and consider a reputation problem with that receiver.
Step 4: for an all-domain problem, suspect a general cause. A queue growing across all domains points at something general, check the server resources, the DNS resolution, the configuration, and whether inbound volume surged.
Step 5: check the inflow side. Confirm whether the queue is growing because delivery slowed, or because inflow surged. A large campaign injection can grow the queue legitimately; if the inflow is normal and the queue is still growing, the problem is on the delivery side.
Step 6: read the accounting log. The accounting log shows what is happening to the delivery attempts, the deferral and bounce patterns, which reveals the specific cause behind the growing queue.
Step 7: address the cause and confirm the queue drains. Once the cause is addressed, watch the queue depth, a recovering queue drains back toward its normal baseline, which confirms the fix worked.
An operator we worked with had set up queue depth monitoring, with their monitoring system polling PowerMTA's HTTP interface and a dashboard showing the trend, but they had only monitored the total queue depth, not the per-domain breakdown. One day their queue alert fired: the total queue depth had been climbing steadily for some time and was well above its normal range, clearly a sustained growth rather than a campaign peak. The alert correctly told them delivery health had degraded. But the total-queue-only monitoring told them only that, that something was wrong, not what or where. They began a broad investigation, checking the server resources, which were fine, checking the DNS, which was fine, checking for an inbound surge, which there was not, working through the general causes one by one, and it took them a while to get to the answer. When we reviewed their setup afterward, we pointed them at the per-domain queue breakdown, which PowerMTA's HTTP interface exposes and their monitoring system could just as easily have collected. We looked at the per-domain queues for the incident period using PowerMTA's data, and the answer was visible instantly: the entire queue growth had been concentrated in one domain's queue, a single major receiver, while every other domain's queue had stayed completely normal throughout. The growth being concentrated in one receiver's queue immediately rules out all the general causes, the server, the DNS, the inbound volume, because a general cause would have grown all the queues together. A one-receiver queue growth points straight at that receiver: that receiver was throttling the operator's mail, and the accounting log for that domain, once they looked, showed the 421 deferrals confirming it. The diagnosis that had taken them a long broad investigation would have taken seconds with the per-domain view: see the growth concentrated in one domain, conclude it is that receiver, check that domain's accounting log, confirm the throttling. The operator added per-domain queue monitoring to their setup after that. The lesson is that queue depth monitoring is far more powerful with the per-domain breakdown than with the total alone. The total queue depth tells the operator that something is wrong; the per-domain breakdown tells them where, and where is most of the diagnosis. Since PowerMTA's HTTP interface exposes the per-domain queues at no extra cost, there is no reason to monitor only the total, and monitoring the per-domain breakdown turns a queue alert from a vague something-is-wrong into a specific the-problem-is-with-this-receiver.
PowerMTA queue depth is one of the most valuable single metrics to monitor, because a growing queue is the visible symptom of nearly any delivery problem and serves as an early, general warning that delivery health has degraded. Reading it correctly means understanding that a healthy queue fluctuates, rising on injections and draining after, so the signal of a problem is a sustained upward trend rather than an instantaneous elevated number, which is why queue monitoring must be continuous and trended rather than a spot check. PowerMTA exposes the queue depth through its HTTP monitoring interface, in machine-readable form, and through pmta show queues, and the practical setup integrates the HTTP interface into the operator's monitoring system for continuous collection, trending, a dashboard, and alerting designed to fire on sustained elevation rather than normal peaks. Monitoring the per-domain queue breakdown, not just the total, is what turns a queue alert from a problem-exists signal into a problem-is-here signal, localizing the cause to a specific receiver or revealing a general cause. Operators who integrate trended, per-domain queue monitoring with sensible alerting get a reliable early warning of delivery problems and a head start on diagnosing them; operators who monitor only the total, or only spot-check, get a vaguer signal and a slower diagnosis.