Contents

1. Tuning Principles
2. Process Tuning
3. Network Tuning
4. Tuning Queue Performance
5. Tuning the WireAPI Client Layers
6. Testing Throughput
7. Tuning FAQ

1. Tuning Principles

OpenAMQ provides a wide set of tuning options. Before you start tuning your server, please note that:

• The default installation is already tuned for general performance. While we encourage you to experiment to understand how your OpenAMQ server behaves, tuning is not an essential part of normal OpenAMQ usage.
• When tuning, make sure you have a good test platform so that you can measure the impact of each choice. It is quite easy to make the performance of a server worse by making the wrong kind of tuning.
• Test each option independently on the command-line before adding it to a configuration file.
• You can tune the WireAPI client libraries with many of the same options as those for the server.

2. Process Tuning

These are the options that affect the server process:

max_memory_mb = "512"

Specifies the maximum memory allowed for the server, in MB. When the server reaches this limit, it will slow down publishers. If zero, no limit is enforced. Default value is 512. This option can be changed at runtime. Note: This option is not functional in the current release (1.2c4), and will be reviewed and fixed in the next release.

polling_threads = "4"

On multithreaded builds, defines the number of OS threads dedicated to socket polling. Default value is 4.

working_threads = "4"

On multithreaded builds, defines the number of OS threads dedicated to processing, that is, tasks other than socket polling. Default value is 4.

3. Network Tuning

These are the options that affect network configuration and performance:

heartbeat = "2"

Defines the timeout for connection heartbeating. Default value is 2. This option can be changed at runtime.

tcp_nodelay = "1"

If this value is 1, socket data is written immediately, which is usually good for latency. If this value is 0, data is buffered until there is a full packet, which is usually good for throughput. Default value is 1. This option can be changed at runtime.

tcp_rcvbuf = "0"

If this value is greater than zero, all client connections will use the specified value. Note: setting this value is delicate, do not use this option unless you know what you are doing. Default value is 0. This option can be changed at runtime.

tcp_sndbuf = "0"

If this value is greater than zero, all client connections will use the specified value. Note: setting this value is delicate, do not use this option unless you know what you are doing. Default value is 0. This option can be changed at runtime.

Note: We recommend that rather than tuning the tcp_rcvbuf and tcp_sndbuf options at the application level, you should rely on the default values of "0" and tune your operating system's TCP stack appropriately. For a good guide to TCP Tuning, see here.

4. Tuning Queue Performance

You can tune the number of messages that queues will accept. This is useful to ensure that your server does not run out of virtual memory when you have fast publishers and slow clients, and a very high rate of data.

OpenAMQ provides a mechanism called "queue profiles" to let you control the limits on a per-queue basis. By default (in amq_server_base.cfg), we define two queue profiles as follows:

<queue_profile name = "private">
    <limit name = "warn" value = "10000" />
    <limit name = "trim" value = "50000" />
</queue_profile>
<queue_profile name = "shared">
    <limit name = "warn" value = "10000" />
    <limit name = "kill" value = "50000" />
</queue_profile>

These profiles define the behaviour of private and shared queues respectively. In each profile we can define up to 10 limits, which specify a number of messages, and an action to perform when that limit is reached:

• warn - issue a warning to the console and accept the message onto the queue. The warning is only issued once when the limit is crossed. * trim - delete an old message from the queue to make space for the new message. * drop - drop the new message, do not delete existing queued messages. * kill - issue a warning and kill the connection and queue. This handles the case when publishers are extremely unbalanced.

To override these limits, edit amq_server.cfg (not the base config file) e.g.:

amq_server.cfg:
<?xml version="1.0"?>
<config>
    <queue_profile name = "shared">
        <limit name = "warn" value = "500" />
        <limit name = "drop" value = "1000" />
    </queue_profile>
    <queue_profile name = "private">
        <limit name = "warn" value = "500" />
        <limit name = "trim" value = "1000" />
    </queue_profile>
</config>

OpenAMQ also lets you define per-queue profiles. When your application creates a queue, using the Queue.Declare method (the amq_queue_declare() method in the WireAPI interface), it can specify a profile name, as follows:

• The application must be capable of constructing and passing an arguments table. * It creates an argument field called "profile" with the value of the profile it wants to use for that queue. * OpenAMQ then takes the profile definition from the configuration data.

This only happens when the queue is created; if the Queue.Declare is specified for an existing queue, it's profile is not modified. If no profile is specified in the Queue.Declare method, OpenAMQ uses 'private' for exclusive queues and 'shared for non-exclusive queues.

5. Tuning the WireAPI Client Layers

The WireAPI layers are not configurable via the command line, so you will want to create an XML configuration file to tune this layer.

The file must be called wireapi.cfg and must be located on the PATH, or in the current directory where the applications are run.

Use the same format for this file as for the server configuration file, e.g.

<?xml?>
<config>
    <tuning
        tcp_rcvbuf = "128000"
        tcb_sndbuf = "128000"
        heartbeat = "5"
    />
</config>

6. Testing Throughput

The standard test tool for performance is amq_client. This sends a number of messages to a private temporary queue, and reads the messages back off that queue.

Start the server with monitoring enabled (so that it displays the traffic rate):

amq_server --monitor 1

Start multiple instances of amq_client on one or a series of test systems:

amq_client -s server:port -n 20000 -x 500 -r 0

This is an example of the monitor output produced by the server:

I: incoming rate=2545 mean=2392 peak=4115
I: outgoing rate=2545 mean=2392 peak=4114 iomean=4784

• The incoming rate represents the number of messages (AMQP contents) read off the network each second.
• The outgoing rate represents the number of messages written to the network each second.
• The mean rates represent a rolling average per second calculated over the previous ten seconds.
• The peak rates represent the highest value over the previous ten seconds.
• the iomean rate represents the combined input and output average per second calculated over the last ten seconds.

When you tune the server performance, it is the iomean that you should be aiming to improve.

7. Tuning FAQ

• How do I write my own test scripts? Answer: use the PAL scripting language that is included with OpenAMQ.