Aeron Documentation

aeron-archive is a module for recording and replaying Aeron data streams from durable storage.

Key capabilities include:

• Record: Capture a specific subscription (<channel, streamId>). Local network publications use the spy feature for efficiency. If no subscribers are active, you can advance the stream by setting the system property aeron.spies.simulate.connection=true.
• Extend: Append data to an existing recording.
• Replay: Replay a recordingId from a specific position for a given length. Using Aeron.NULL_VALUE for length results in an open-ended replay that stops at the recording's stop position.
• Query: Access the catalog for existing recordings and check the recorded position of active recordings.
• Truncate: Shorten a stopped recording. Truncating to the start position effectively deletes the recording.
• Replay Merge: Allows a late-joining subscriber to replay a recording and then merge with the live stream.
• Replicate: Copy recordings from a source to a destination archive. When using replication, configure the destination channel using aeron.archive.replication.channel.
• Storage Maintenance: Perform purge, detach, delete, attach, and migrate operations on recording segments.

Aeron is a high-performance, reliable messaging transport system designed for high throughput and low, predictable latency. It supports:

• Transport Types: UDP unicast, UDP multicast, and IPC (Inter-Process Communication).
• Client Support: Java, C, and C++ clients are available in this repository. A .NET client is available separately.
• Interoperability: Clients can exchange messages across different machines or on the same machine via IPC.
• Persistence: The aeron-archive module allows recording message streams to persistent storage for later or real-time replay.
• Fault Tolerance: aeron-cluster provides support for fault-tolerant services using replicated state machines based on the Raft consensus algorithm.

Aeron integrates with Simple Binary Encoding (SBE) for optimal message encoding/decoding performance and utilizes Agrona for many of its underlying data structures.

Starting with Aeron 1.48.0, AeronCluster includes a state machine to track connection status. This state machine is updated during:

• Poll operations (AeronCluster#pollEgress and AeronCluster#controlledPollEgress)
• Sending data to the Cluster (AeronCluster#offer, AeronCluster#tryClaim, AeronCluster#sendKeepAlive)

If a communication break lasts longer than AeronCluster.Context#newLeaderTimeoutNs(), the AeronCluster will close itself.

Default Timeout Behavior:

• If newLeaderTimeoutNs() is not set, it waits for double the leadership timeout from an actual Cluster.
• If the Cluster is running an older Aeron version and the leadership timeout is unavailable, it defaults to 10 seconds (resulting in a 20-second wait).

Manual Updates Required: If you use AeronCluster#ingressPublication or AeronCluster#egressSubscription directly, you must manually call the following to update the connection tracking state machine:

1. After every offer or tryClaim on AeronCluster#ingressPublication, call AeronCluster#trackIngressPublicationResult.
2. Every time AeronCluster#egressSubscription is polled, call AeronCluster#pollStateChanges.

Aeron Cluster can be deployed in several configurations depending on your requirements:

• Single Node: Suitable for development and debugging, or when a single-node sequenced and archived log is sufficient.
• Appointed Leader: A leader is specified via configuration. This avoids elections but requires manual intervention to appoint a new leader if the current one fails. This is not the recommended production configuration.
• Automatic Elections (Default): The cluster automatically elects a leader from the members with the most up-to-date log. This is the most reliable method for production.

Cluster Sizing Note:

• Typical cluster sizes are 3 or 5 nodes to ensure a majority for consensus.
• 2-node clusters are supported, but both members must agree on the log. If one fails, the remaining member must be manually reconfigured as a single-node cluster to continue progressing.