Skip to content

Starting a Recording

After connecting to Aeron Archive, a User Application can send Control Requests to it, like asking it to start recording a Publication. Let's use the Market Data Collector example from the Detailed Overview. The Market Data Collector publishes Market Data messages on a UDP Market Data Channel. Let's update it to instruct Aeron Archive to record the messages from the publishing end of the Market Data Channel. This will use a Spy Subscription, as shown in this diagram. The high level workflow becomes:

  1. Create the Market Data Publication
  2. Connect to Aeron Archive using the Archive Client (new step)
  3. Instruct Aeron Archive to start recording the Publication (new step)
  4. Continue with its main function of collecting and publishing market data

Connecting to Aeron Archive was covered in the previous section. This diagram starts from step 3, after creating the Market Data Publication and connecting to Aeron Archive:

Aeron Archive Recorder Archive Conductor Replayer Transport Client Market Data Collector Transport Client Archive Client Sub Sub Control Response Channel Sub Control Request Channel Pub startRecording() StartRecordingRequest Pub ControlSession ControlSessionDemuxer Sub ControlResponse(OK) Pub Market Data Channel (UDP) Control Channel (UDP) Local Control Channel (IPC) Catalog RecordingDescriptor cnc.dat rec-pos RecordingSession RecordingSignalEvent(START)

Use the tabs above to step through the animation.


The Market Data Collector calls AeronArchive.startRecording(), passing in the Market Data Channel URI and StreamId. These are sent to Aeron Archive (along with the controlSessionId, which is stored in the Archive Client) in a StartRecordingRequest message, published on the Control Request Channel.

The ControlSessionDemuxer reads the message, looks up the ControlSession using the controlSessionId, then calls ControlSession.onStartRecording(), which calls ArchiveConductor.startRecording(). The ArchiveConductor creates a Spy Subscription to the Market Data Channel (as described earlier), also registering an AvailableImageHandler. It then returns a ControlResponse message with an OK response code on the Control Response Channel.

When the Spy Subscription was created, it would have 'connected' immediately with the Market Data Publication, as it's in the same Media Driver. The AvailableImageHandler that was registered would be called, where the Image is the Publication Log Buffer that needs recording. The handler calls ArchiveConductor.startRecordingSession(), which starts by adding a new RecordingDescriptor to the Catalog.

ArchiveConductor.startRecordingSession() then creates a RecordingPosition (rec-pos) counter and sets it to the Image's join position. Join position will be the consumer (Sender) position in the Publication's Log Buffer at the point at which the Spy Subscription was created. This will be zero in this example, as nothing has been published yet.

ArchiveConductor.startRecordingSession() creates a RecordingSession and gives it the rec-pos counter. The RecordingSession is then given to the Recorder. Finally, a RecordingSignalEvent message is sent on the Control Response Channel containing RecordingSignal.START to indicate that recording has started.

RecordingSession

Here's an alternative view of what just happened, from the point of view of the Detailed Overview diagram:

Media Driver Sender Conductor Receiver Market Data Collector Pub Pub Machine 1 Aeron Archive Spy Sub Recording

When the Spy Subscription (circled 'Sub') was created and the AvailableImageHandler was called, the Image (which is just a Java object in the Aeron Client that refers to a Log Buffer) was for the Publication's Log Buffer (circled 'Pub'). The RecordingSession in Aeron Archive was created specifically for that Image.

Remember that if other Publications were created for the same Channel and StreamId, they could have their own Log Buffers, which means the Subscription could have many Images (Log Buffers) associated with it. That's not the case in this example though.

The RecordingSession polls directly from the Image, not the Subscription. If a second Image did become available, a second RecordingSession would be created, so each Log Buffer would be recorded independently.

Recorder

The RecordingSession is owned by the Recorder component within Aeron Archive. The Recorder's job is to loop around, calling doWork() on each of its RecordingSessions. Within doWork(), the RecordingSession would poll its Image, looking for new messages to record.

By default, the Recorder runs on its own thread, so it would be dedicated to shuffling bytes from Images to Recording files, while the ArchiveConductor does all the admin work.