bag-play

Synopsis

bag-play [OPTIONS] LOGFILE [URI]

Description

The bag-play program can be used to publish RSB events from a log file of recorded events. Replaying event flows as closely to the original as possible or with certain modifications can be very useful when debugging components, doing performance or regressions tests or testing the influence of parameters.

See also

Common Commandline Options
The usual RSB-related commandline options are accepted.
Replay-related Options
The usual replay-related commandline options are accepted.

Playback of All Recorded Channels

To play all recorded events of a log file on their original channels, two commandline arguments have to be specified:

  1. The log file from which events should be read
  2. The “base” scope to which events should be published

For details regarding the URI syntax involved in transport and channel specifications, see URIs.

Selective Playback

The default behavior of bag-play is to play back all channels found in the given file. However, when only a subset of the recorded channels should be played back, the --channel commandline option can be used to select channels for playback.

The default behavior of bag-play is to play back all events of the selected channels ordered by timestamp, from earliest to latest. However, it is possible to select a subset of these events by specifying temporal or index-based intervals. The --start-index, --end-index, --start-time and --end-time commandline options allow specifying these restrictions.

Playback Timing

Different strategies for controlling the replay timing can be used. Strategies and their parameters are specified using the --replay-strategy commandline option. The default replay strategy tries to mimic the original timing.

Other strategies include

  • Replay events as fast as possible
  • Replay events at a fixed rate

In addition, some strategies permit modification of their behavior via parameters. For example:

-r 'fixed-rate :rate 20'
-r 'recorded-timing :speed 1.5'

Tip

Available strategies and their parameters are described in the output of bag-play --help.

Adjusting Timestamps during Replay

The replay strategies as-fast-as-possible, fixed-rate and recorded-timing accept an :adjustments LIST-OF-ADJUSTMENTS argument where LIST-OF-ADJUSTMENTS is of the form ((TIMESTAMP EXPRESSION) ...). Examples:

-r 'recorded-timing :adjustments ((:create :now))'
-r 'recorded-timing :adjustments ((:create (:delta 120)))'
-r 'recorded-timing :adjustments ((:my-timestamp (:copy :create)) (:create (:delta 120)))'

The first example will replace the recorded create timestamp with the time at which the event is replayed.

The second example will add 120 seconds to the recorded create timestamp.

The third example copies the recorded create timestamp into a new timestamp named my-timestamp and then adjusts the create timestamp as in the second example.

Interactive Playback

TODO

-r 'interactive'

Remote-controlled Playback

bag-play can expose an RPC interface that allows navigating the log file being played back and controlling emission of events. An URI has to be supplied as the :uri argument of the --replay-strategy option to configure the scope and transport through which the RPC interface should be exposed. The full syntax of the commandline option therefore is

-r 'remote-controlled :uri "URI"'

An example for URI could be the RSB URI socket:/remotecontrol.

The interface consists of the following methods:

length()
Returns uint64:length of the sequence of all events

Return the length of the sequence of all events.

relativelength()
Returns uint64:length of the replayed (sub-)sequence of all events

Return the length of the replayed (sub-)sequence of all events.

index()
Returns uint64:current position in the replayed sequence

Return the current position in the replayed sequence.

relativeindex()
Returns uint64:current position relative to the start of the replayed (sub-)sequence

Return the current position relative to the start of the replayed (sub-)sequence.

next()
Returns uint64:new index

Move the replay cursor to the next entry.

previous()
Returns uint64:new index

Move the replay cursor to the previous entry.

seek()
Arguments:
  • position (uint64) – new replay cursor position.

Position the replay cursor at position.

emit()

Publish the entry at which the replay cursor is currently positioned.

emitandnext()
Returns uint64:new index

Publish the entry at which the replay cursor is currently positioned, advance to the next entry.

get()
Returns bytes:the serialized entry

Return the entry at which the replay cursor is currently positioned. Do not emit or change anything.

quit()

Terminate the replay.

Examples

  • $ bag-play /tmp/nao.tide 'spread://remote:4803'
    

    In the above example, the specified scope is / which causes all events to be played on their original scopes since recorded event scopes are appended to the specified base scope.

  • $ bag-play -c 'vision' -c 'audio' /tmp/nao.tide 'spread:?name=5555'
    

    The above command plays all channels of the log file /tmp/nao.tide whose names match one of the regular expressions vision and audio.

  • $ bag-play --start-index 1000 /tmp/nao.tide 'spread:?name=5555'
    

    The above command replays the events of the log file /tmp/nao.tide starting with the 1000-th event.