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:
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
.
Handling of Event IDs during Replay¶
The replay strategies
as-fast-as-possible
, fixed-rate
and recorded-timing
accept
an :event-id MODE
argument where MODE
is either
:keep
Send events with the event ids stored in the respective log file.
- cause vectors remain meaningful among the replayed events
- sequence numbers may repeat and start at arbitrary values
- events appear to originate from participants that cannot be found in the current system
:replace
Send events with new event ids replacing the ones stored in the respective log file. The new event ids correspond to the participants actually sending the events.
- cause vectors become meaningless among the replayed events
- sequence numbers generally do not repeat and start at 0
- events originate from participants that are part of the current system
The default behavior is :replace
.
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.
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 expressionsvision
andaudio
.$ 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.