Configuration Options

Martin Thompson edited this page Feb 22, 2017 · 66 revisions

Aeron provides a number of configuration options to control its behaviour at runtime. There are 3 major ways by which configuration options can be applied with the following order of precedence.

  1. Channel URI Params: Parameters applied to the end of the URI string when adding Publications or Subscriptions.
  2. Context Object Properties: Properties on the context object when creating the Aeron Client or MediaDriver programatically.
  3. System Properties: Properties defined on the command line or loaded from properties files.

Here is a full listing of configurations options. Well it will be when I finish updating the page :)

Channel URI Params

When adding Publications or Subscriptions via the client, URI params can be appended to the channel string which will override system wide configuration options. Over time more options will be available via this mechanism.

  • ttl: Sets the Time To Live for multicast datagrams, e.g. aeron:udp?endpoint=224.0.1.1:40456|ttl=16

Context Object Properties

The Aeron client and MediaDriver can be programmatically launched with a context object provided for configuration. If properties are set on the context object before it is concluded then they will take precedence over system properties. The Aeron Client and MediaDriver have their own context objects. Properties can be set via a fluent API and then passed in when launching the client or media driver.

Configuring a client example.

    final Aeron.Context ctx = new Aeron.Context();
    if (EMBEDDED_MEDIA_DRIVER)
    {
        ctx.aeronDirectoryName(driver.aeronDirectoryName());
    }

    try (Aeron aeron = Aeron.connect(ctx);
         Publication publication = aeron.addPublication(CHANNEL, STREAM_ID))
    {
        // use publication
    }

Configuring a driver example.

/**
 * Sample setup for a {@link MediaDriver} that is configured 
 * for low latency communications.
 */
public class LowLatencyMediaDriver
{
    public static void main(final String[] args) throws Exception
    {
        MediaDriver.loadPropertiesFiles(args);

        final MediaDriver.Context ctx = new MediaDriver.Context()
            .threadingMode(ThreadingMode.DEDICATED)
            .conductorIdleStrategy(new BusySpinIdleStrategy())
            .receiverIdleStrategy(new BusySpinIdleStrategy())
            .senderIdleStrategy(new BusySpinIdleStrategy());

        try (MediaDriver ignored = MediaDriver.launch(ctx))
        {
            new SigIntBarrier().await();

            System.out.println("Shutdown Driver...");
        }
    }
}

System Properties

The most common way of configuring Aeron is via systems properties. System properties can be set on the Java command line by prefixing the property with -D followed by the property name equals property value as in the following example

$ java -cp aeron-samples/build/libs/samples.jar \
    -Daeron.mtu.length=16384 \
    io.aeron.driver.MediaDriver

It is often more convenient packaging up a set of properties into a properties file. Aeron can load a list of properties files passed in as command line arguments to the MediaDriver. Each will be loaded in turn adding to the set of system properties. Some sample properties files are provided as resources in the driver module.

The filenames will be treated as a URI and the driver will attempt to load the properties as resources, local files, and remotely via HTTP in that order. The following is an example of using multiple configuration properties.

$ java -cp aeron-samples/build/libs/samples.jar \
    -Daeron.mtu.length=16384 \
    io.aeron.driver.MediaDriver \
    aeron-throughput.properties \
    http://config.server.local/aeron-deployment.properties \
    ~/conf/aeron/my-test.properties

Options List

  1. Common Options
  2. Aeron Client Options
  3. Media Driver Options
  4. Channel Endpoint Extension Options

Common Options

Common options are those used both by the Aeron client and the Media Driver.

Aeron Directory
Description Directory under which the driver will store all its files.
Type String
Default The users TMP/TEMP directory if not Linux otherwise /dev/shm, i.e. resulting in <java.io.tmp>/aeron-<user.name> when driver launched standalone, and <java.io.tmp>/aeron-<user.name>-<randomUUID>.
System Property aeron.dir
Context CommonContext.aeronDirectoryName()
URI Param N/A
Driver Timeout
Description The timeout in milliseconds after which the driver is considered dead if it does not update its C'n'C timestamp.
Type int64
Default 10000
System Property N/A
Context CommonContext.driverTimeoutMs()
URI Param N/A

Aeron Client Options

Within the client process there are a small number of available options. The goal is to keep this list to a minimum with instruction taken from the Media Driver.

Client Error Handler
Description The error handler to be called by the client conductor when it detects and issue with the driver. It is recommended that users set their own error handler.
Type org.agrona.ErrorHandler
Default Prints a stack trace to STDERR and then exits.
System Property N/A
Context Aeron.Context.errorHandler()
URI Param N/A
Client Keepalive Interval
Description The interval time in nanoseconds for which the client will send a keepalive messages on the control protocol to the driver to indicate it is still here.
Type int64
Default 500_000_000 (500ms)
System Property N/A
Context Aeron.Context.keepAliveInterval()
URI Param N/A
Client Interservice Timeout
Description The timeout in nanoseconds that if exceeded by client conductor duty cycles the client will consider itself a zombie and self suicide by closing publications and images then invoking the error handler.
Type int64
Default 10_000_000_000 (10 seconds)
System Property N/A
Context Aeron.Context.interServiceTimeout()
URI Param N/A
Publication Connection Timeout
Description Timeout in nanoseconds since the last status message after which a Publication will be considered not connected.
Type int64
Default 5_000_000_000 (5 seconds)
System Property N/A
Context Aeron.Context.publicationConnectionTimeout()
URI Param N/A
Client Conductor Idle Strategy
Description Idle strategy to be used by the Client Conductor.
Type org.agrona.concurrent.IdleStrategy
Default org.agrona.concurrent.SleepingIdleStrategy (4 milliseconds)
System Property N/A
Context Aeron.Context.idleStrategy()
URI Param N/A
Available Image Handler
Description Callback handler to be notified when an Image becomes available.
Type io.aeron.AvailableImageHandler
Default No Op
System Property N/A
Context Aeron.Context.availableImageHandler()
URI Param N/A
Unavailable Image Handler
Description Callback handler to be notified when an Image becomes unavailable.
Type io.aeron.UnavailableImageHandler
Default No Op
System Property N/A
Context Aeron.Context.unavailableImageHandler()
URI Param N/A

Media Driver Options

The bulk of configuration is for the Media Driver. Most options have defaults which the end user should not need to change. Socket buffers and flow control windows are the exception when throughput performance is directly influenced by Bandwidth Delay Product (BDP) which needs to be considered. Idle and threading strategies are useful to trading CPU usage for throughput and latency.

Media Driver Error Handler
Description The error handler to be called when an exception occurs in the driver. Only override this with a specific usecase in mind.
Type org.agrona.ErrorHandler
Default Records to the DistinctErrorLog.
System Property N/A
Context Aeron.Context.errorHandler()
URI Param N/A
Term Buffer Max Length
Description Maximum length in bytes of a publication buffer to hold a term of messages. It must be a power of 2 and be in the range of 64KB to 1GB.
Type int32
Default 1024 * 1024 * 1024 (1GB)
System Property aeron.term.buffer.max.length
Context MediaDriver.Context.maxTermBufferLength()
URI Param N/A
Term Buffer Length
Description The length in bytes of a publication buffer to hold a term of messages. It must be a power of 2 and be in the range of 64KB to 1GB.
Type int32
Default 16 * 1024 * 1024
System Property aeron.term.buffer.length
Context MediaDriver.Context.publicationTermBufferLength()
URI Param term-length
IPC Term Buffer Length
Description The length in bytes of a IPC publication buffer to hold a term of messages. It must be a power of 2 and be in the range of 64KB to 1GB.
Type int32
Default 64 * 1024 * 1024
System Property aeron.ipc.term.buffer.length
Context MediaDriver.Context.ipcTermBufferLength()
URI Param term-length
Conductor Idle Strategy
Description Idle strategy to be used by the Driver Conductor agent in the media driver when in ThreadingMode.DEDICATED or ThreadingMode.SHARED_NETWORK.
Type org.agrona.concurrent.IdleStrategy
Default org.agrona.concurrent.BackoffIdleStrategy
System Property aeron.conductor.idle.strategy
Context MediaDriver.Context.conductorIdleStrategy()
URI Param N/A
Sender Idle Strategy
Description Idle strategy to be used by the Sender agent in the media driver when in ThreadingMode.DEDICATED.
Type org.agrona.concurrent.IdleStrategy
Default org.agrona.concurrent.BackoffIdleStrategy
System Property aeron.sender.idle.strategy
Context MediaDriver.Context.senderIdleStrategy()
URI Param N/A
Receiver Idle Strategy
Description Idle strategy to be used by the Sender agent in the media driver when in ThreadingMode.DEDICATED.
Type org.agrona.concurrent.IdleStrategy
Default org.agrona.concurrent.BackoffIdleStrategy
System Property aeron.receiver.idle.strategy
Context MediaDriver.Context.receiverIdleStrategy()
URI Param N/A
Shared Network Idle Strategy
Description Idle strategy to be used by the Sender and Receiver agents in the media driver when in ThreadingMode.SHARED_NETWORK.
Type org.agrona.concurrent.IdleStrategy
Default org.agrona.concurrent.BackoffIdleStrategy
System Property aeron.sharednetwork.idle.strategy
Context MediaDriver.Context.sharedNetworkIdleStrategy()
URI Param N/A
Shared Idle Strategy
Description Idle strategy to be used by the all agents in the media driver when in ThreadingMode.SHARED.
Type org.agrona.concurrent.IdleStrategy
Default org.agrona.concurrent.BackoffIdleStrategy
System Property aeron.shared.idle.strategy
Context MediaDriver.Context.sharedIdleStrategy()
URI Param N/A
Use sparse files for term buffers
Description Should term buffers be created as sparse files. If a platform supports sparse files then log buffer creation is faster with pages being allocated as needed. This can help for large numbers of channels/streams but can result in latency pauses.
Type Boolean
Default false
System Property aeron.term.buffer.sparse.file
Context MediaDriver.Context.termBufferSparseFile()
URI Param N/A
Low File Store Warning Threshold
Description Threshold in bytes below which driver will warn to STDERR that file space is running low.
Type int64
Default 10 times the aeron.term.buffer.length
System Property aeron.low.file.store.warning.threshold
Context N/A
URI Param N/A
Conductor command buffer length
Description Length in bytes for the clients to driver conductor command buffer.
Type int32
Default (1024 * 1024) + RingBufferDescriptor.TRAILER_LENGTH
System Property aeron.conductor.buffer.length
Context N/A
URI Param N/A
To clients broadcast buffer length
Description Length in bytes for broadcasting events from the driver to clients.
Type int32
Default (1024 * 1024) + BroadcastBufferDescriptor.TRAILER_LENGTH
System Property aeron.clients.buffer.length
Context N/A
URI Param N/A
Counters buffer length
Description Length in bytes for the buffer containing counters. May need to increase for large numbers of streams or subscriptions. Each counter requires 128 bytes to avoid false sharing.
Type int32
Default 1024 * 1024
System Property aeron.counters.buffer.length
Context N/A
URI Param N/A
Error Buffer Length
Description Length in bytes for the buffer containing recorded errors. May need to increase if many different distinct exception traces are observed.
Type int32
Default 1024 * 1024
System Property aeron.error.buffer.length
Context N/A
URI Param N/A
Loss Report Buffer Length
Description Length in bytes for the buffer containing recorded loss entries. Once full no more loss will be recorded. Disable by setting the value to zero.
Type int32
Default 1024 * 1024
System Property aeron.loss.report.buffer.length
Context MediaDriver.Conext.lossReport()
URI Param N/A
Initial Receiver Window Length
Description Window for flow control of in-flight bytes between sender and receiver on a stream. This needs to be sufficient for BDP (Bandwidth Delay Product) and be greater than MTU.
Type int32
Default 128 * 1024
System Property aeron.rcv.initial.window.length
Context MediaDriver.Context.initialWindowLength()
URI Param N/A
Receiver Status Message Timeout
Description Timeout after which a status message will be sent if one has not been triggered by data flow.
Type int64
Default 200_000_000 (200 milliseconds)
System Property aeron.rcv.status.message.timeout
Context MediaDriver.Context.statusMessageTimeout()
URI Param N/A
Receive socket buffer length
Description Length in bytes for the SO_RCVBUF, 0 means use OS default. This needs to be larger than Receiver Window.
Type int32
Default 128 * 1024
System Property aeron.socket.so_rcvbuf
Context N/A
URI Param N/A
Sender socket buffer length
Description Length in bytes for the SO_SNDBUF, 0 means use OS default. This needs to be larger than Receiver Window.
Type int32
Default 0
System Property aeron.socket.so_sndbuf
Context N/A
URI Param N/A
Publication Term Window Length
Description Length of the flow control window between Publishers and the Sender. If zero then defaults to half a term length. If set to larger than half of a term length then it will be reduced to half a term length.
Type int32
Default 0
System Property aeron.publication.term.window.length
Context N/A
URI Param N/A
IPC Publication Term Window Length
Description Length of the flow control window between Publishers and the Subscribers. If zero then defaults to a full term length. If set to larger than a full term length then it will be reduced a term length.
Type int32
Default 0
System Property aeron.ipc.publication.term.window.length
Context N/A
URI Param N/A
Multicast Time To Live (TTL)
Description Number of hops multicast will be allowed to propagate, zero means use OS default.
Type int32
Default 0
System Property aeron.socket.multicast.ttl
Context N/A
URI Param ttl
Publication linger timeout
Description Timeout in nanoseconds for a publication to linger after it is closed so it can respond to NAKs.
Type int64
Default 5_000_000_000 (5 seconds)
System Property aeron.publication.linger.timeout
Context N/A
URI Param N/A
Client liveness timeout
Description Timeout in nanoseconds after which a driver has not had keepalive messages from a client before it considers the client dead.
Type int64
Default 5_000_000_000 (5 seconds)
System Property aeron.client.liveness.timeout
Context MediaDriver.Context.clientLivenessTimeoutNs()
URI Param N/A
Image liveness timeout
Description Timeout in nanoseconds for each the INACTIVE and LINGER stages an image will be retained for when it is no longer referenced.
Type int64
Default 10_000_000_000 (10 seconds)
System Property aeron.image.liveness.timeout
Context MediaDriver.Context.imageLivenessTimeoutNs()
URI Param N/A
Unicast Flow Control Strategy
Description Strategy to be employed for flow control on UDP unicast streams which is loaded by the default supplier.
Type io.aeron.driver.FlowControl
Default io.aeron.driver.UnicastFlowControl
System Property aeron.unicast.flow.control.strategy
Context N/A
URI Param N/A
Unicast Flow Control Strategy Supplier
Description Supplier of UDP unicast flow control strategies.
Type io.aeron.driver.FlowControlSupplier
Default io.aeron.driver.DefaultUnicastFlowControlSupplier
System Property aeron.unicast.FlowControl.supplier
Context MediaDriver.Context.unicastFlowControlSupplier()
URI Param N/A
Multicast Flow Control Strategy
Description Strategy to be employed for flow control on UDP multicast streams which is loaded by the default supplier.
Type io.aeron.driver.FlowControl
Default io.aeron.driver.MaxMulticastFlowControl
System Property aeron.multicast.flow.control.strategy
Context N/A
URI Param N/A
Multicast Flow Control Strategy Supplier
Description Supplier of UDP multicast flow control strategies.
Type io.aeron.driver.FlowControlSupplier
Default io.aeron.driver.DefaultMulticastFlowControlSupplier
System Property aeron.multicast.FlowControl.supplier
Context MediaDriver.Context.multicastFlowControlSupplier()
URI Param N/A
MTU (Maximum Transmission Unit) Length
Description Maximum length of a message fragment including Aeron data frame header for transmission in a network packet. This can be a larger than an Ethernet MTU provided it is smaller than the maximum UDP payload length. Larger lengths enable batching and reducing syscalls at the expense of more likely loss.
Type int32
Default 4096
System Property aeron.mtu.length
Context MediaDriver.Context.mtuLength()
URI Param mtu
Threading Mode for the Driver
Description DEDICATED is a thread for each of the Conductor, Sender, and Receiver Agents. SHARED is one thread for all three Agents. SHARED_NETWORK is one thread for the conductor and one shared for the Sender and Receiver Agents.
Type ThreadingMode
Default DEDICATED
System Property aeron.threading.mode
Context MediaDriver.Context.threadingMode()
URI Param N/A
Send to Status Poll Ratio
Description Ratio of maximum number of data packets sent per publication to poll actions for control messages.
Type int32
Default 4
System Property aeron.send.to.status.poll.ratio
Context N/A
URI Param N/A

Event Logging Options

Debug Logging can be enabled in the driver via a Java agent which performs bytecode weaving. Aeron pays zero penalty for logging when it is not enabled.

Event Buffer Length
Description Length of the ring buffer into which events are captured for hand off to the logger.
Type uint32
Default 2 * 1024 * 1024
System Property aeron.event.buffer.length
Context N/A
URI Param N/A
Enabled Event Codes
Description Comma separated list of event codes that should be logged from the EventCode enum.
Type String
Default null
System Property aeron.event.log
Context N/A
URI Param N/A

Channel Endpoint Extension Options

Aeron is designed for extension. One good example is how the interaction with the network media layer can be extended for interaction on the sender or receiver side. Channel endpoints can sub-classed by configured suppliers. Examples are provided for testing and debugging that introduce packet loss.

Send Channel Endpoint Supplier
Description Supplier of custom behaviour for SendChanneEndpoints to override interaction with the network.
Type io.aeron.driver.SendChannelEndpointSupplier
Default io.aeron.driver.DefaultSendChannelEndpointSupplier
System Property aeron.SendChannelEndpoint.supplier
Context MediaDriver.Context.sendChannelEndpointSupplier()
URI Param N/A
Receive Channel Endpoint Supplier
Description Supplier of custom behaviour for ReceiveChanneEndpoints to override interaction with the network.
Type io.aeron.driver.ReceiveChannelEndpointSupplier
Default io.aeron.driver.DefaultReceiveChannelEndpointSupplier
System Property aeron.ReceiveChannelEndpoint.supplier
Context MediaDriver.Context.receiveChannelEndpointSupplier()
URI Param N/A
Send Data Loss Rate
Description Factor for the rate at which data packets should be discarded to simulate loss on send end of channel.
Type double
Default 0.0
System Property aeron.debug.send.data.loss.rate
Context N/A
URI Param N/A
Send Data Loss Seed
Description Seed for the random number generator for data packet loss.
Type uint64
Default 0.0
System Property aeron.debug.send.data.loss.seed
Context N/A
URI Param N/A
Send Control Loss Rate
Description Factor for the rate at which control packets should be discarded to simulate loss on send end of channel.
Type double
Default 0.0
System Property aeron.debug.send.control.loss.rate
Context N/A
URI Param N/A
Send Control Loss Seed
Description Seed for the random number generator for control packet loss.
Type uint64
Default 0.0
System Property aeron.debug.send.control.loss.seed
Context N/A
URI Param N/A
Receive Data Loss Rate
Description Factor for the rate at which data packets should be discarded to simulate loss on receive end of channel.
Type double
Default 0.0
System Property aeron.debug.receive.data.loss.rate
Context N/A
URI Param N/A
Receive Data Loss Seed
Description Seed for the random number generator for data packet loss.
Type uint64
Default 0.0
System Property aeron.debug.receive.data.loss.seed
Context N/A
URI Param N/A
Receive Control Loss Rate
Description Factor for the rate at which control packets should be discarded to simulate loss on receive end of channel.
Type double
Default 0.0
System Property aeron.debug.receive.control.loss.rate
Context N/A
URI Param N/A
Receive Control Loss Seed
Description Seed for the random number generator for control packet loss.
Type uint64
Default 0.0
System Property aeron.debug.receive.control.loss.seed
Context N/A
URI Param N/A