bag record¶
Synopsis¶
bag record [OPTIONS] -o OUTPUT [URI1] [URI2 ...]
Description¶
The bag record program can be used to capture certain RSB events in a running system and store them into a log file for later analysis, further processing or replay.
See also
- Common Commandline Options
- The usual RSB-related commandline options are accepted.
- IDL-related Commandline Options
- The usual IDL-related commandline options are accepted.
-
--output-file
OUTPUT
,
-o
OUTPUT
¶ Write captured events to log file
OUTPUT
. The file format is determined based on the file type (which is determined based on the file extension).Examples of supported formats and corresponding file extensions are
.tide
: TIDELog.eaf
: Elan
Tip
The output of
common --help-for
all
includes a list of supported file formats.
-
--force
¶
Should
OUTPUT
be overwritten in case it already exists?
-
index-timestamp
NAME
¶ Use the timestamp named
NAME
to index events in the created log file. The default timestamp is “send”.
-
--channel-allocation
SPEC
,
-a
SPEC
¶ Allocate channels for received events in the output log file according to the strategy designated by
SPEC
which has to be of the form:KIND KEY1 VALUE1 KEY2 VALUE2 ...
where keys and values depend on
KIND
and are optional in most cases. The default channel allocation strategy isscope-and-type
.The following strategies are currently supported:
scope-and-type
This strategy allocates a separate channel for each combination of scope and wire schema as events are received: the channel allocation for a given combination is performed when the first event exhibiting that combination is received. Channel names produced by this strategy are of the form
SCOPE:TYPE
whereSCOPE
is the scope string of the events scope andTYPE
is the wire schema string, i.e. a string designating the type of the event payload (See Types).For example, an event on scope
/foo/bar/
with a protocol buffer payload and wire schema.rst.vision.Image
would be stored in a channel called/foo/bar/:.rst.vision.Image
.Examples:
-a scope-and-type
Tip
Use the
common --help-for
channel-strategies
orcommon --help-for
all
options to display the full help text, including available strategies and their respective parameters, for this item.
-
--flush-strategy
SPEC
¶ Flush buffers (e.g. event and indices) according strategy designated by
SPEC
which has to be of one of the forms:KIND KEY1 VALUE1 KEY2 VALUE2 ... OR (SPEC) (SPEC) ... AND (SPEC) (SPEC) ... NOT (SPEC)
where keys and values depend on
KIND
and are optional in most cases. The default flushing strategy isproperty-limit :property :length/bytes :limit 33554432
which corresponds to flushing buffers once they reach a size of 32 MB.Examples:
--flush-strategy 'property-limit :property :length/bytes :limit 16777216'
Flush buffers once they reach a size of 16 MB.
--flush-strategy 'property-limit :property :length/entries :limit 100'
Flush buffers once they reach 100 entries.
--flush-strategy 'property-limit :property :time-to-last-write :limit 5'
Flush buffers when the most recent write was 5 or more seconds ago.
--flush-strategy 'or (:property-limit :property :time-to-last-write :limit 5) (:property-limit :property :length/bytes :limit 33554432)'
Flush buffers when they reach a size of 32 MB or the most recent write was 5 or more seconds ago.
Tip
Use the
common --help-for
flush-strategies
orcommon --help-for
all
options to display the full help text, including available strategies and their respective parameters, for this item.
-
--control-uri
URI
,
-c
URI
¶ Expose an RPC interface for remote-controlling the recording process under
URI
. See Remote Control for details.Important
Supplying this option causes bag record to start in a suspended state. The recording has to be started using the
start()
.
-
--introspection-survey
BOOLEAN
¶ Perform an introspection survey at the beginning of the Recording to ensure it contains a complete snapshot of the system structure from which incremental changes can be tracked.
Recording Events¶
Some general remarks regarding recording of RSB events using bag record:
- The specified output file into which events should
be recorded, should not already exist
- If an empty file of the given name exists, it will be used for recording
- If a non-empty file of the given name exists, it will be extended as long as it does not already contain any of the channels being recorded
- The recording process can be terminated gracefully by sending one of
SIGINT
andSIGTERM
to the bag record process
Remote Control¶
bag record can expose an RPC interface that allows
starting, stopping and terminating the recording process. This feature
is enabled using the --control-uri
commandline option. An
URI has to be supplied as an argument of the option to configure the
scope and transport through which the RPC interface
should be exposed. The interface consists of the following methods:
-
isstarted
()¶ Return
true
if a log file has been opened for recording and recording is currently in progress andfalse
otherwise.
-
start
()¶ Restart recording - initially or after it has been stopped.
Only applicable if a log file has been opened.
-
stop
()¶ Stop recording allowing it to be restarted later.
Only applicable if a log file has been opened.
-
isopen
()¶ If a log file has been opened for recording, return its path as a string. Otherwise return
false
.
-
open
()¶ Arguments: - filename (string) – name of the log file into which the recording should write.
Open
filename
and prepare recording events. However, do not actually start recording untilstart
is called.Only applicable if no log file is currently open.
-
terminate
()¶ Terminate the recording process and the program.
Examples¶
$ bag record -o /tmp/nao.tide 'spread:/nao/vision/top?name=4803' 'spread:/nao/audio/all?name=4803' 'spread:/nao/proprioception?name=4803'
The resulting log file will (unless a different channel allocation is specified) contain one channel for each of the three RSB scopes.
$ bag record -c 'spread:/control' -o /tmp/everything.tide spread:
The above command starts a bag record process configured to record events into the log file
/tmp/everything.tide
. Since the--control-uri
commandline option has been used, bag record does not record immediately after starting, but wait for instructions via RPC . Therefore, without terminating the above bag record process, the call program can be used to issue commands:$ call 'spread:/control/start()' # start recording [...] $ call 'spread:/control/stop()' # stop recording $ call 'spread:/control/terminate()' # terminate bag record
$ bag record --output-file /tmp/nao.tide --on-error continue --flush-strategy '(:property-limit :property :time-to-last-write :limit 1)' 'socket:/camera1'
The above example demonstrates non-default error and flushing behavior: bag record is instructed to continue in case of errors and flush buffers every second. Something like this could make sense when the recorded data is hard to produce.