IronMQ Queue Alerts

Table of Contents


Check out our Blog Post on Queue Alerts.

Alerts, triggered when the queue hits a pre-determined number of messages (both ascending and descending), allow developers to notify other systems based on the activity of a queue. Actions include things like: auto-scaling, failure detection, load-monitoring, and system health. 

Alerts Parameters

IronMQ provides a number of routes to manipulate queue alerts.

Add and Update Alerts Endpoints

Request body example:

  "alerts": [
      "type": "fixed",
      "direction": "asc",
      "trigger": 1000,
      "queue": "queue-to-post-size-alerts-to",
      "snooze": 120
      "type": "progressive",
      "direction": "desc",
      "trigger": 100,
      "queue": "queue-to-post-progressive-to"
  • alerts - optional - array of hashes containing alerts hashes.


  • type - set to “fixed” or “progressive”
    • A “fixed” alert will trigger an alert when the queue size passes the value set by trigger parameter.
    • A “progressive” alert will trigger when queue size passes any of values calculated by trigger * N where N >= 1. Example: trigger is set to 10, alerts will be triggered at queue sizes 10, 20, 30, etc.
  • trigger - must be integer value > 0.
    • Used to calculate actual values of queue size when alert must be triggered. See type field description.
  • queue
    • Name of queue which will be used to post alert messages.


  • direction - set to “asc” (default) or “desc”
    • An “asc” setting will trigger alerts as the queue grows in size.
    • A “desc” setting will trigger alerts as the queue decreases in size.
  • snooze - Number of seconds between alerts. Must be integer value >= 0
    • If alert must be triggered but snooze is still active, alert will be omitted.

Alerts Messages

Alert messages are JSONified strings in the following format:

  "source_queue": "test_queue",
  "queue_size": 12,
  "alert_id": "530392f41185ab1f2a0005f7",
  "alert_type": "progressive",
  "alert_direction": "asc",
  "alert_trigger": 5,
  "created_at": "2014-02-18T17:10:43Z"

Setting Alerts in Dashboard

You can easily create an alert through our interface on our queue view in the dashboard. Navigate down and click view queue alerts on the left hand side of the queue view.


Here you can add up to 5 alerts per queue.


Example Alert Settings and their meaning

The following serve as examples of how you may do about setting your alert settings.

  "type": "progressive",
  "direction": "asc",
  "trigger": 1000,
  "queue": "worker_push_queue"

Interpretation: For every progressive increment of 1,000 messages on my queue in the ascending direction trigger an alert to my queue entitled “worker_push_queue”. This pattern would trigger additional workers to run for seamless autoscaling.

  "type": "fixed",
  "direction": "asc",
  "trigger": 1,
  "queue": "worker_polling_queue"

Interpretation: When my queue passes the fixed value of 1 post to my “worker_polling_queue”. This pattern would trigger a worker to run whenever there are items within the queue.

Important Notes

  • Our system checks for duplicate alerts each time you add a new alert to a queue. It the compares type, direction, and trigger parameters to find duplicates. If one or more of the new alerts is a duplicate, we will return a HTTP 400 error and message as such: {"msg": "At least one new alert duplicates current queue alerts."}.
  • When you try to add alerts to a Push Queue or convert Pull Queue with alerts to a Push Queue, IronMQ will respond with HTTP 400 error and message as such: {"msg": "Push queues do not support alerts."}