Normally, all objects are allocated from Java's heap memory. Once, nothing references an object it is cleaned up by the Java Garbage Collector and it's memory returned to the heap. This works fine for most use cases. However, when interacting with other parts of the operating system using Java's heap is not ideal. This is where the so called direct memory comes into play.

The world outside of the JVM, in particular the operating system (OS), does not know about Java heap memory and uses other structures like C arrays. In order to interact with these systems Java needs to copy data between its own heap memory and these native structures. This can become a bottle neck when there is a lot of exchange between Java and the OS like in I/O (both disk and network) heavy applications. Java's solution to this is to allow programmers to request ByteBuffers from so called direct memory. This is an opaque structure that might have an underlying implementation that makes it efficient to interact with the OS. Unfortunately, the GC is not good at tracking direct memory and in general it is inadvisable to use direct memory for regular objects.

The broker itself uses a moderate amount of heap memory (≈15 MB). However, each connection and session comes with a heap overhead of about 17 kB and 15 kB respectively. In addition, each connection reserves 512 kB direct memory for network I/O.

The amount of memory a Virtual Host uses depends on its type. For a JSON Virtual Host Node with a BDB Virtual Host the heap memory usage is approximately 2 MB. However, each BDB Virtual Hosts has a mandatory cache in heap memory which has an impact on performance. See below for more information.

Messages and their headers are kept in direct memory and have an additional overhead of approximately 1 kB heap memory each. This means that most brokers will want to have more direct memory than heap memory. When many small messages accumulate on the broker the 1 kB heap memory overhead can become a limiting factor.

When the broker is running low on direct memory it will evict enqueued messages from memory and flow them to disk. For persistent messages this only means freeing the direct memory representation because they always have an on-disk representation to guard against unexpected failure (e.g., a power cut). For transient messages this implies additional disk I/O. After being flowed to disk messages need to be re-read from disk before delivery.

Please, note that messages from uncommitted transactions are not flowed to disk as part of running into low direct memory conditions, as they are not enqueued yet. The Connection has its own threshold for keeping messages from uncommitted transactions in memory. Only when Connection threshold is breached, the uncommitted messages on the connection are flowed to disk.

Qpid uses Jetty for the HTTP Management (both REST and Web Management Console). When the management plugin is loaded it will allocate the memory it needs and should not require more memory during operation and can thus be largely ignored.

When the broker runs low on heap memory performance will degrade because the JVM will trigger full garbage collection (GC) events in a struggle to free memory. These full GC events are also called stop-the-world events as they completely halt the execution of the Java application. Stop-the-world-events may take any where from a couple of milliseconds up to several minutes. Should the heap memory demands rise even further the JVM will eventually throw an OutOfMemoryError which will cause the broker to shut down.

When the broker detects that it uses 75% of available direct memory it will start flowing incoming transient messages to disk and reading them back before delivery. This will prevent the broker from running out of direct memory but may degrade performance by requiring disk I/O.

Most of these options are implementation specific. It is assumed you are using Oracle Java 11.

We developed a simple formula which estimates the minimum memory usage of the broker under certain usage. These are rough estimate so we strongly recommend testing your configuration extensively. Also, if your machine has more memory available by all means use more memory as it can only improve the performance and stability of your broker. However, remember that both heap and direct memory are served from your computer's physical memory so their sum should never exceed the physically available RAM (minus what other processes use).

Where N denotes the total number of connections/sessions/messages on the broker. Furthermore, for direct memory only the messages that have not been flowed to disk are relevant.