Menu

Introduction

Prerequisites

This tutorial assumes RabbitMQ is installed and running on localhost on standard port (5672). In case you use a different host, port or credentials, connections settings would require adjusting.

Where to get help

If you're having trouble going through this tutorial you can contact us through the mailing list.

RabbitMQ is a message broker: it accepts and forwards messages. You can think about it as a post office: when you put the mail that you want posting in a post box, you can be sure that Mr. Postman will eventually deliver the mail to your recipient. In this analogy, RabbitMQ is a post box, a post office and a postman.

The major difference between RabbitMQ and the post office is that it doesn't deal with paper, instead it accepts, stores and forwards binary blobs of data ‒ messages.

RabbitMQ, and messaging in general, uses some jargon.

  • Producing means nothing more than sending. A program that sends messages is a producer :

    digraph { bgcolor=transparent; truecolor=true; rankdir=LR; node [style="filled"]; // P1 [label="P", fillcolor="#00ffff"]; }

  • A queue is the name for a post box which lives inside RabbitMQ. Although messages flow through RabbitMQ and your applications, they can only be stored inside a queue. A queue is only bound by the host's memory & disk limits, it's essentially a large message buffer. Many producers can send messages that go to one queue, and many consumers can try to receive data from one queue. This is how we represent a queue:

    digraph { bgcolor=transparent; truecolor=true; rankdir=LR; node [style="filled"]; // subgraph cluster_Q1 { label="queue_name"; color=transparent; Q1 [label="{||||}", fillcolor="red", shape="record"]; }; }

  • Consuming has a similar meaning to receiving. A consumer is a program that mostly waits to receive messages:

    digraph { bgcolor=transparent; truecolor=true; rankdir=LR; node [style="filled"]; // C1 [label="C", fillcolor="#33ccff"]; }

Note that the producer, consumer, and broker do not have to reside on the same host; indeed in most applications they don't.

"Hello World"

(using the Bunny Ruby Client)

In this part of the tutorial we'll write two small programs in Ruby; a producer (sender) that sends a single message, and a consumer (receiver) that receives messages and prints them out. We'll gloss over some of the detail in the Bunny API, concentrating on this very simple thing just to get started. It's a "Hello World" of messaging.

In the diagram below, "P" is our producer and "C" is our consumer. The box in the middle is a queue - a message buffer that RabbitMQ keeps on behalf of the consumer.

(P) -> [|||] -> (C)

The Bunny client library

RabbitMQ speaks multiple protocols. This tutorial uses AMQP 0-9-1, which is an open, general-purpose protocol for messaging. There are a number of clients for RabbitMQ in many different languages. We'll use the Bunny, the most popular Ruby client, in this tutorial.

First, install Bunny using Rubygems:

gem install bunny --version ">= 2.6.4"

Now we have Bunny installed, we can write some code.

Sending

(P) -> [|||]

We'll call our message producer send.rb and our message consumer receive.rb. The producer will connect to RabbitMQ, send a single message, then exit.

In send.rb, we need to require the library first:

#!/usr/bin/env ruby
# encoding: utf-8

require "bunny"

then connect to RabbitMQ server

conn = Bunny.new
conn.start

The connection abstracts the socket connection, and takes care of protocol version negotiation and authentication and so on for us. Here we connect to a broker on the local machine with all default settings.

If we wanted to connect to a broker on a different machine we'd simply specify its name or IP address using the :hostname option:

conn = Bunny.new(:hostname => "rabbit.local")
conn.start

Next we create a channel, which is where most of the API for getting things done resides:

ch   = conn.create_channel

To send, we must declare a queue for us to send to; then we can publish a message to the queue:

q    = ch.queue("hello")
ch.default_exchange.publish("Hello World!", :routing_key => q.name)
puts " [x] Sent 'Hello World!'"

Declaring a queue is idempotent - it will only be created if it doesn't exist already. The message content is a byte array, so you can encode whatever you like there.

Lastly, we close the connection;

conn.close

Here's the whole send.rb script.

Sending doesn't work!

If this is your first time using RabbitMQ and you don't see the "Sent" message then you may be left scratching your head wondering what could be wrong. Maybe the broker was started without enough free disk space (by default it needs at least 200 MB free) and is therefore refusing to accept messages. Check the broker logfile to confirm and reduce the limit if necessary. The configuration file documentation will show you how to set disk_free_limit.

Receiving

That's it for our producer. Our consumer is pushed messages from RabbitMQ, so unlike the producer which publishes a single message, we'll keep it running to listen for messages and print them out.

[|||] -> (C)

The code (in receive.rb) has the same require as send:

#!/usr/bin/env ruby
# encoding: utf-8

require "bunny"

Setting up is the same as the producer; we open a connection and a channel, and declare the queue from which we're going to consume. Note this matches up with the queue that send publishes to.

conn = Bunny.new
conn.start

ch   = conn.create_channel
q    = ch.queue("hello")

Note that we declare the queue here, as well. Because we might start the consumer before the producer, we want to make sure the queue exists before we try to consume messages from it.

We're about to tell the server to deliver us the messages from the queue. Since it will push us messages asynchronously, we provide a callback that will be executed when RabbitMQ pushes messages to our consumer. This is what Bunny::Queue#subscribe does.

puts " [*] Waiting for messages in #{q.name}. To exit press CTRL+C"
q.subscribe(:block => true) do |delivery_info, properties, body|
  puts " [x] Received #{body}"

  # cancel the consumer to exit
  delivery_info.consumer.cancel
end

Bunny::Queue#subscribe is used with the :block option that makes it block the calling thread (we don't want the script to finish running immediately!).

Here's the whole receive.rb script.

Putting it all together

Now we can run both scripts. In a terminal, run the consumer (receiver):

ruby -rubygems receive.rb

then, run the publisher (sender):

ruby -rubygems send.rb

The consumer will print the message it gets from the producer via RabbitMQ. The consumer will keep running, waiting for messages (Use Ctrl-C to stop it), so try running the producer from another terminal.

Listing queues

You may wish to see what queues RabbitMQ has and how many messages are in them. You can do it (as a privileged user) using the rabbitmqctl tool:

sudo rabbitmqctl list_queues

On Windows, omit the sudo:

rabbitmqctl.bat list_queues

Time to move on to part 2 and build a simple work queue.

1 "Hello World!"

The simplest thing that does something

2 Work queues

Distributing tasks among workers (the competing consumers pattern)

3 Publish/Subscribe

Sending messages to many consumers at once

4 Routing

Receiving messages selectively

5 Topics

Receiving messages based on a pattern (topics)

6 RPC

Request/reply pattern example