Aeron Archive
10,000 ft overview
Aeron Archive adds a durable message store to Aeron Transport. It is an application that can listen to the streams of messages that pass through the Aeron Transport shared memory buffers and record them to disk. These recorded messages can then be replayed back into a shared memory buffer and received by an application in the same way that the original messages were received.
Use the tabs above to step through the animation.
Application 1 sends a message by writing it to a shared memory buffer, as it did before. Aeron Archive is another application that is running, which also uses Aeron Transport, so it also uses the Aeron Transport Client API code (in blue).
The Media Driver reads the message in the shared memory buffer and sends it over the network, as it did before. But in addition, Aeron Archive also reads the message. It writes it into a Recording, which is a file on disk. The format is not changed - it is written as is.
The receiving machine reads the original message into a shared memory buffer, as it did before.
The receiving Application receives the original message using a Subscription, as it did before.
But now, Aeron Archive can be asked to Replay the messages it stored. Application 1 does not need to be running. The messages are read from the Recording and written to the shared memory buffer, in the same format they were originally written in.
The Media Driver reads the replay message in the shared memory buffer and sends it over the network, as it did for the original message. There is no difference between the original and replay message.
The receiving machine reads the message into a shared memory buffer, as it did before.
The receiving Application receives the message using a Subscription, as it did before.
Aeron Archive Location
In the above diagram, Aeron Archive is running on the sending machine. It could equally run on the receiving machine, reading messages from the shared memory there instead. It can run at whichever location best suits your needs, but obviously could not run on a third machine, as it needs access to the shared memory that the messages are passing through.
Control Requests
Aeron Archive needs instructing to Record or Replay streams of messages. It does not automatically record all messages that pass through the shared memory buffers. These instructions are called Control Requests and are sent to it using Aeron Transport, just like the application messages that are sent from Application 1 to Application 2 above.
For example, Application 1 could send a Control Request message to Aeron Archive to tell it to Record the application messages that it is going to send to Application 2. A more accurate picture including Control Request messages would look like this:
Use the tabs above to step through the animation.
Application 1 is now using two API client libraries. The blue one is the same as before, for sending messages over Aeron Transport. The orange one is an Aeron Archive client library, for sending Aeron Archive messages over Aeron Transport. Application 1 calls a method on the Aeron Archive client library to request a Recording and the library publishes a StartRecording Control Request message.
The StartRecording message is read by Aeron Archive. This is communicating over IPC, as Aeron Archive is on the same machine, so the StartRecording message does not need sending over the network. Aeron Archive also supports receiving Control Request messages over the network.
Aeron Archive prepares to Record the stream of messages that Application 1 is going to send to Application 2. Other streams of messages would not be recorded. Aeron Archive returns an OK response.
Application 1 receives the OK response, so now it can start sending messages to Application 2.
Application 1 publishes a message to Application 2.
Aeron Archive knows that it needs to record this message and does so.
Control Session
In fact, the above diagram is still a simplification. The first Control Request message that Application 1 needs to send to Aeron Archive is a Connect message. This sets up a Control Session, where Authentication can be performed (if configured). Once a Control Session has been established, then the StartRecording message can be sent.