Introduction
************

.. _section-introduction:

Introduction
============

*RTI Recording Service* includes the following tools:

-  *Recording Service*, an *RTI Connext DDS* application that records Topics and
   discovery data. *Recording Service* records updates to data along
   with a timestamp, so you can view or replay updates to data in your
   system as they occur over time. Recorded data is stored in SQLite®
   files by default. *Recording Service* also has an API to record
   to a custom data store.
-  *Replay Service*, an application that can play back data recorded by
   *Recording Service*. *Replay Service* also has an API to allow plugging
   in custom storage.
-  *Converter*, an application that converts binary (serialized)
   recorded data to deserialized data that can be viewed and queried.
   The most efficient way to record data is in serialized form.
   *Converter* allows data to be recorded efficiently, then post-processed
   into a queryable form. *Converter* also provides APIs to plug in custom
   storage.

The Basics
==========

*Recording Service* is used when you need to record updates to system data
over a period of time, and to access that data by time. One example of
when you might use the *Recording Service:*  if you are testing your
system, you can use *Recording Service* to record all DDS data updates
that occur during a particular test run. Then you can use a database
tool or *Replay Service* to view what happened at specific times during your
test.

*Recording Service’s* builtin database is a SQLite file.
*Recording Service* can store data in the SQLite database
in two formats:

-  CDR serialized format: This is the format in which data is sent over
   the network, so it is the most efficient way to store data. It is
   binary, so it is not queryable.
-  JSON format:  To store data this way, *Recording Service* must convert
   between the network format and the JSON format. This is queryable,
   but comes at a performance cost.

*Recording Service* also provides an API that allows you to implement your
own storage backend.  You will receive the data in serialized format,
then use *Connext DDS* dynamic-data APIs to deserialize the data.

.. figure:: ./static/image2.png
    :figwidth: 80 %
    :alt: Recording Service Overview
    :name: FigureRecordOverview
    :align: center

    *Recording Service* receives DDS samples over the network and
    records them to storage, based on their timestamps

*Replay Service* works with data recorded by *Recording Service*. It
uses the timestamps of the recorded data to replay the data back into a
DDS system at the original offsets between recorded timestamps. *Replay
Service* also offers an API to retrieve your data from the storage of
your choice to be replayed.

.. figure:: ./static/image8.png
    :figwidth: 80 %
    :alt: Replay Service Overview
    :name: FigureReplayOverview
    :align: center

    *Replay Service* retrieves stored data samples from storage and replays it
    over DDS, maintaining the original timing of the data


*Converter* is a tool that can convert between the data formats used by
*Recording Service*. Currently, the only builtin formats supported by
*Recording Service* are the CDR and JSON formats described above, within
a SQLite database. *Converter* allows you to record data in the efficient
CDR format and later convert to a queryable JSON format.

.. figure:: ./static/image7.png
    :figwidth: 80 %
    :alt: Replay Service Overview
    :name: FigureConverterOverview
    :align: center

    *Converter* takes serialized (binary() data and converts it to
    deserialized JSON data

.. _section-doc-paths:

Paths Mentioned in Documentation
================================

This documentation refers to:

- ``<NDDSHOME>`` This refers to the installation directory for *Connext DDS*.

  The default installation paths are:

  - Mac® OS X® systems:
    ``/Applications/rti_connext_dds-version``
  - UNIX®-based systems, non-root user:
    ``/home/your user name/rti_connext_dds-version``
  - UNIX-based systems, root user:
    ``/opt/rti_connext_dds-version``
  - Windows® systems, user without Administrator privileges:
    ``<your home directory>\rti_connext_dds-version``
  - Windows systems, user with Administrator privileges:
    ``C:\Program Files\rti_connext_dds-version``

  You may also see ``$NDDSHOME`` or ``%NDDSHOME%``, which refers to an
  environment variable set to the installation path.

  Whenever you see ``<NDDSHOME>`` used in a path, replace it with your
  installation path.

  **Note for Windows Users:** When using a command prompt to enter a command
  that includes the path ``C:\Program Files`` (or any directory name that
  has a space), enclose the path in quotation marks. For example:
  ``“C:\Program Files\rti_connext_dds-version\bin\rticlouddiscoveryservice.bat”``

  Or if you have defined the ``NDDSHOME`` environment variable:
  ``"%NDDSHOME%\bin\rticlouddiscoveryservice.bat"``

- ``<path to examples>`` By default, examples are copied into your home
  directory the first time you run *RTI Launcher* or any script in
  ``<NDDSHOME>/bin``. This document refers to the location of the copied
  examples as ``<path to examples>``.

  Wherever you see ``<path to examples>``, replace it with the appropriate path.

  Default path to the examples:

  - Mac OS X systems:
    ``/Users/your user name/rti_workspace/version/examples``
  - UNIX-based systems:
    ``/home/your user name/rti_workspace/version/examples``
  - Windows systems:
    ``your Windows documents folder\rti_workspace\version\examples``.
    Where ``'your Windows documents folder'`` depends on your version of
    Windows. For example, on Windows 10 systems, the folder is
    ``C:\Users\your user name\Documents``.