.. _bag-record:

============
 bag-record
============

.. program:: bag-record

Synopsis
========

:samp:`bag-record {[OPTIONS]} -o {OUTPUT} {[URI1]} {[URI2 ...]}`

Description
===========

The :program:`bag-record` program can be used to capture certain RSB
:term:`events` in a running system and store them into a :term:`log
file` for later analysis, further processing or replay.

The :ref:`usual commandline options <common-options>` and
:ref:`IDL-related options <idl-options>` are accepted. Specialized
commandline options:

.. option:: --output-file OUTPUT, -o OUTPUT

   Write captured events to file :samp:`{OUTPUT}`. The file format is
   determined based on the file type (which is determined based on the
   file extension).

   .. tip::

      The output of :option:`common --help-for` ``all`` includes a
      list of supported file formats.

.. option:: --channel-allocation SPEC, -a SPEC

   Allocate channels for received events in the output bag file
   according to the strategy designated by :samp:`{SPEC}` which has to
   be of the form::

     KIND KEY1 VALUE1 KEY2 VALUE2 ...

   where keys and values depend on :samp:`{KIND}` and are optional in
   most cases. The default channel allocation strategy is
   ``scope-and-type`` which creates on the fly based on events scopes
   and types according to the following scheme::

     SCOPE:TYPE

   Examples (note that the single quotes have to be included only when
   used within a shell)

   .. code-block:: sh

      -a scope-and-type

   .. tip::

      Use the :option:`common --help-for` ``channel-strategies`` or
      :option:`common --help-for` ``all`` options to display the full
      help text, including available strategies and their respective
      parameters, for this item.

.. option:: --control-uri URI, -c URI

   Expose an RPC interface for remote-controlling the recording
   process under :samp:`{URI}`. See `Remote Control`_ for details.

   .. important::

      Supplying this option causes :program:`bag-record` to start in a
      suspended state. The recording has to be started using the
      :function:`start`.

Recording Events
================

Some general remarks regarding recording of RSB :term:`events` using
:program:`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`` and ``SIGTERM`` to the :program:`bag-record` process

.. tip::

   For details regarding the URI syntax involved in :term:`transport`
   and :term:`channel` specifications, see :ref:`uri-schema`.

Remote Control
==============

:program:`bag-record` can expose an `RPC
<http://en.wikipedia.org/wiki/Remote_procedure_call>`_ interface that
allows starting, stopping and terminating the recording process. This
feature is enabled using the :option:`--control-uri` commandline
option. An URI has to be supplied as an argument of the option to
configure the :term:`scope` and :term:`transport` through which the
RPC interface should be exposed. The interface consists of the
following methods:

.. js:function:: start()

   Restart recording after it has been stopped.

.. js:function:: stop()

   Stop recording allowing it to be restarted later.

.. js:function:: terminate()

   Terminate the recording process and the program.

Examples
========

* .. code-block:: sh

     $ 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 file will (unless a different :term:`channel`
  allocation is specified) contain one :term:`channel` for each of the
  three RSB :term:`channels`.

* .. code-block:: sh

     $ bag-record -o /tmp/nao.tide
                  'spread://remote:4803/nao/vision/top'
                  'spread://remote:4803/nao/audio/all'
                  'spread://remote:4803/nao/proprioception'

* .. code-block:: sh

     $ bag-record -c 'spread:/control' -o /tmp/everything.tide spread:

  Then, without terminating the above :program:`bag-record` process,
  the :ref:`call` program can be used to issue commands:

  .. code-block:: sh

     $ call 'spread:/control/terminate()'