Blocked Connection Notifications

Overview

It is sometimes desirable for clients to receive a notification when their connection gets blocked due to the broker running low on resources (memory or disk).

We have introduced an AMQP 0-9-1 protocol extension in which the broker sends to the client a connection.blocked method when the connection gets blocked, and connection.unblocked when it is unblocked.

To receive these notifications, the client must present a capabilities table in its client-properties in which there is a key connection.blocked and a boolean value true.

See the capabilities section for further details on this. Our supported clients indicate this capability by default and provide a way to register handlers for the connection.blocked and connection.unblocked methods.

When Notifications are Sent

A connection.blocked notification is sent to publishing connections the first time RabbitMQ is low on a resource. For example, when a RabbitMQ node detects that it is low on RAM, it sends connection.blocked to all connected publishing clients supporting this feature. If before the connections are unblocked the node also starts running low on disk space, another connection.blocked will not be sent.

A connection.unblocked is sent when all resource alarms have cleared and the connection is fully unblocked.

Using Blocked Connection Notifications with Java Client

With the official Java client, blocked connection notifications are handled by BlockedListener interface implementations. They can be registered on a Connection using the Connection.addBlockedListener method:

ConnectionFactory factory = new ConnectionFactory();
Connection connection = factory.newConnection();
connection.addBlockedListener(new BlockedListener() {
    public void handleBlocked(String reason) throws IOException {
        // Connection is now blocked
    }

    public void handleUnblocked() throws IOException {
        // Connection is now unblocked
    }
});

Using Blocked Connection Notifications with .NET Client

With the official .NET client, blocked connection notifications can be received by registering for the ConnectionBlocked and ConnectionUnblocked events in IConnection:

  public void HandleBlocked(object sender, ConnectionBlockedEventArgs args)
  {
      // Connection is now blocked
  }

  public void HandleUnblocked(object sender, EventArgs args)
  {
      // Connection is now unblocked
  }

Conn.ConnectionBlocked   += HandleBlocked;
Conn.ConnectionUnblocked += HandleUnblocked;