.. include:: ../../../router.1.0/srcDoc/vars.rst

.. _section-record_configuration:

Configuration
=============

When you start *Recording Service*, you can specify a configuration file
in XML format.  In that file, you can set properties that
control the behavior of the service. This section describes how to
write a configuration file.



How to Load the XML Configuration
---------------------------------

*Recording Service* loads its XML configuration from multiple
locations. Here are the various sources of configuration files, listed
in load order:

- ``[working directory]/USER_RECORDING_SERVICE.xml``
  This file is loaded automatically if it exists.
- ``[NDDSHOME]/resource/xml/RTI_RECORDING_SERVICE.xml``
  This file is loaded automatically if it exists.
- One or more files (semicolon-separated) specified using the command-line 
  parameter ``-cfgFile``.

.. note::

    ``[working directory]`` indicates the path to the current working
    directory from which you run *Recording Service*.

    ``[NDDSHOME]`` indicates the path to your *Connext DDS* installation.
    See :numref:`section-doc-paths`.

You may use a combination of the above sources and load multiple
configuration files.

Here is an example configuration file.  You will learn the meaning of
each line as you read the rest of this section.

.. code-block:: xml

    <?xml version="1.0" encoding="UTF-8"?>
    <dds xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
         xsi:noNamespaceSchemaLocation="../schema/rti_recording_service.xsd">
        <!-- Qos Library -->
        <qos_library name="MyQosLib">
            <qos_profile name="ReliableQos" >
                <datareader_qos>
                    <reliability>
                        <kind>RELIABLE_RELIABILITY_QOS</kind>
                    </reliability>
                </datareader_qos>
            </qos_profile>
        </qos_library>
        <!--  A definition of a Recording Service instance to run -->
        <recording_service name="MyRecorderService">
            <!--  Storage settings -->
            <storage>
                <sqlite>
                    <storage_format>XCDR_AUTO</storage_format>
                    <file>rti_recorder_default</file>
                    <file_suffix>dat</file_suffix>
                </sqlite>
            </storage>
            <!--  Top-level domain settings -->
            <domain_participant name="Participant0">
                <domain_id>0</domain_id>
            </domain_participant>
            <!-- Recording Session -->
            <session name="DefaultSession" >
                <!-- Group of topics to record -->
                <topic_group name="RecordAll" participant_ref="Participant0">
                    <allow_topic_name_filter>*</allow_topic_name_filter>
                    <allow_type_name_filter>*</allow_type_name_filter>
                    <!-- DDS input -->
                    <datareader_qos base_name="MyQosLib::ReliableQos" />
                </topic_group>
            </session>
        </recording_service>      
    </dds>

XML Syntax and Validation
-------------------------

The XML representation of DDS-related resources must follow these syntax
rules:

-  It shall be a well-formed XML document according to the criteria
   defined in clause 2.1 of
   :link_xml_spec:`the Extensible Markup Language standard <>`.
-  It shall use UTF-8 character encoding for XML elements and values.
-  It shall use ``<dds>`` as the root tag of every document.

To validate the loaded configuration, *Recording Service* relies on an XSD
file that describes the format of the XML content. We recommend
including a reference to this document in the XML file that contains the
service’s configuration; this document provides helpful features in code
editors such as Visual Studio®, Eclipse®, and NetBeans®, including
validation and auto-completion while you are editing the XML file.

The XSD definitions of the XML elements are in
``$NDDSHOME/resource/schema/rti_recording_service.xsd``.

To include a reference to the XSD document in your XML file, use the
attribute ``xsi:noNamespaceSchemaLocation`` in the ``<dds>`` tag. For example:

.. code-block:: xml

   <?xml version="1.0" encoding="UTF-8"?>
   <dds xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="[NDDSHOME]/resource/schema/rti_recording_service.xsd">
      <!-- ... -->
   </dds>

.. note::

   ``[NDDSHOME]`` indicates the path to your *Connext DDS* installation.
   See :numref:`section-doc-paths`.


Builtin Configuration of Recording Service
------------------------------------------

*Recording Service* is pre-configured with a builtin configuration. See
:numref:`section-builtin-config-recording-service` for more details.

.. _section-record-config-XML-tags:

XML Tags for Configuring Recording Service
------------------------------------------

This section describes the XML tags you can use in a *Recording Service*
configuration file. The following diagram and table describe
the top-level tags allowed within the root ``<dds>`` tag.

.. figure:: ../static/RecordingServiceTopLevelTags.png
    :alt: Top-Level tags in Recording Service's Configuration File
    :name: FigureTopLevelTag
    :align: center
    :figwidth: 50 %

    Top-level Tags in Recording Service's Configuration File

.. list-table:: Top-level Tags in Recording Service's Configuration File
    :name: TableTopLevelTag
    :widths: 20 70 10
    :header-rows: 1
    :class: longtable

    * - Tags within :litrep:`<dds>`
      - Description
      - Multiplicity
    * - :litrep:`<qos_library>`
      - Specifies a QoS library and profiles. The contents of this tag are
        specified in the same manner as for the *Connext DDS* QoS profile
        file—see
        :link_xml_qos_config:`Configuring QoS with XML in the RTI Connext
        DDS Core Libraries User's Manual <>`.
      - 0..*
    * - :litrep:`<types>`
      - Defines types that can be used by *Recording Service*. This is needed
        if data types are not available through discovery, or when using a
        transformation. The type description is done using the
        *Connext DDS* XML format for type definitions.
        See :link_userman_types_in_xml:`Creating User Data Types with
        Extensible Markup Language (XML), in the RTI Connext DDS
        Core Libraries User's Manual <>`.
      - 0..*
    * - :litrep:`<plugin_library>`
      - Contains a list of libraries that can be used to:

         - Plug in custom storage, such as custom databases.
           For more information, see :numref:`section-record-custom-storage`.
         - Transform data after it is received from *Connext DDS* and before
           it is stored. For more on using transformations, see
           :link_router_manual_config_transformation:`Data Transformation,
           in the RTI Routing Service User’s Manual. <>`.

           See :numref:`section-Record-Config-Plugins`

      - 0..*
    * - :litrep:`<recording_service>`
      - **Required.** |br|
        Specifies a *Recording Service* configuration.
        See :numref:`section-config-recording-service-tag`.

        Attributes
            - ``name``: Uniquely identifies a service configuration.
              **Required**.

        Example
            .. code-block:: xml

                <recording_service name="RecordAll">
                    <!-- your service settings ... -->
                </recording_service>

      - 1..*

.. _section-config-recording-service-tag:

Recording Service Tag
---------------------

A configuration file must have at least one ``<recording_service>`` tag.
This tag is used to configure an execution of *Recording Service*.

A configuration file may contain multiple ``<recording_service>`` tags.
When you start *Recording Service*, you can use the ``-cfgName`` 
command-line parameter to specify which ``<recording_service>`` tag to use
to configure the service. This means one file can be used to configure multiple
*Recording Service* executions.

The following diagram and :numref:`TableRecordingServiceTag` describe the
tags allowed within a ``<recording_service>`` tag.

.. figure:: ../static/RecordingServiceTags.png
    :alt: Tags used to configure a *Recording Service* instance
    :name: FigureRecordingServiceTag
    :align: center
    :figwidth: 50 %

    Tags used to configure a *Recording Service* instance

.. list-table:: Recording Service Tags in Recording Service's Configuration File
    :name: TableRecordingServiceTag
    :widths: 20 70 10
    :header-rows: 1
    :class: longtable

    * - Tags within :litrep:`<recording_service>`
      - Description
      - Multiplicity
    * - :litrep:`<administration>`
      - Enables remote administration.

        When administration is enabled, monitoring is also enabled by default.
        If no domain ID is specified for monitoring,
        *Recording Service* will use the same domain as
        administration by default.
        See :numref:`section-config-administration-tag`.
      - 0..1
    * - :litrep:`<monitoring>`
      - Enables monitoring for the recording service, including statistics.
        See :numref:`section-config-monitoring-tag`.
      - 0..1
    * - :litrep:`<storage>`
      - Describes how the data will be stored. If this is not specified,
        data will be stored in a SQLite file using the default name
        "rti_recorder_default.dat".
        See :numref:`section-record-config-storage-tag`.
      - 0..1
    * - :litrep:`<domain_participant>`
      - **Required**. |br|
        Specifies a DomainParticipant to use to record data.

        Attributes
            - ``name``: Uniquely defines a DomainParticipant. **Required**.

        Example
            .. code-block:: xml

                <domain_participant name="Participant3">
                    <domain_id>3</domain_id>
                    <!-- Participant QoS -->
                </domain_participant>

        See :numref:`section-config-domainparticipant-tag`.
      - 1..*
    * - :litrep:`<session>`
      - **Required**. |br|
        Active component of *Recording Service* for recording data. Contains
        one or more threads that can be used for recording.

        Attributes
            - ``name``: Uniquely defines a recording session. **Required**.
            - ``default_participant_ref``: Specifies a default
              DomainParticipant to be used by children of this recording
              session. Children can override this by specifying their own
              participant.

        Example
            .. code-block:: xml

              <session name="Session" default_participant_ref="Participant3">
                  <!-- ... topics /   groups of topics to record -->
              </session>

        See :numref:`section-config-session-tag`.

      - 1..*

Example:  Specify a Recording Service Configuration in XML
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: xml

    <dds>
        <recording_service name="MyRecorderService">
            <!-- ... Required entities -->
        </recording_service>
    </dds>

Starting a *Recording Service* instance with the following command will use the
``<recording_service>`` tag with the name "MyRecorderService":

.. code-block:: bash

    $NDDSHOME/bin/rtirecordingservice -cfgFile file.xml -cfgName MyRecorderService



.. _section-config-administration-tag:

Administration
--------------

The ``<administration>`` tag allows you to enable and configure remote
administration of *Recording Service*, including stopping, starting,
and pausing recording.

See :numref:`section-record_administration` for details on
using remote administration.

.. list-table:: Administration Tags in Recording Service's Configuration File
    :name: TableAdministrationTag
    :widths: 20 70 10
    :header-rows: 1
    :class: longtable

    * - Tags within :litrep:`<administration>`
      - Description
      - Multiplicity
    * - :litrep:`<domain_id>`
      - Domain ID used for remote administration.  Also used for monitoring
        by default.
      - 0..1
    * - :litrep:`<participant_qos>`
      - QoS used by the administration DomainParticipant.
        If the tag is not defined, *Connext DDS* defaults will be used.
      - 0..1
    * - :litrep:`<publisher_qos>`
      - QoS used by the administration Publisher.
        If the tag is not defined, *Connext DDS* defaults will be used.
      - 0..1
    * - :litrep:`<subscriber_qos>`
      - QoS used by the administration Subscriber.
        If the tag is not defined, *Connext DDS* defaults will be used.
      - 0..1
    * - :litrep:`<datawriter_qos>`
      - QoS used by administration DataWriter(s).
        If the tag is not defined, *Connext DDS* defaults will be used,
        with the following changes:

          - history.kind = DDS_KEEP_ALL_HISTORY_QOS
          - resource_limits.max_samples = 32

      - 0..1
    * - :litrep:`<datareader_qos>`
      - Quality of Service (QoS) used by administration DataReader(s).
        If the tag is not defined, the *Connext DDS* defaults will be used,
        with the following changes:

          - reliability.kind = DDS_RELIABLE_RELIABILITY_QOS (this value cannot
            be changed)
          - history.kind = DDS_KEEP_ALL_HISTORY_QOS
          - resource_limits.max_samples = 32

      - 0..1
    * - :litrep:`<distributed_logger>`
      - When you enable *Distributed Logger*, *Recording Service*
        will publish its Log messages to *Connext DDS*.
        See :numref:`section-config-enabling-distributed-logger`.
      - 0..1

The contents of the tags for configuring QoS are specified in the same
manner as for the *Connext DDS* QoS profile file. See
:link_xml_qos_config:`Configuring QoS with XML, in the RTI Connext
DDS Core Libraries User's Manual <>`.

.. _section-config-monitoring-tag:

Monitoring
----------

The ``<monitoring>`` tag allows you to enable and configure remote
monitoring of *Recording Service*.
See :numref:`section-Recorder-Monitoring`.

.. list-table:: Monitoring Tags in Recording Service's Configuration File
    :name: TableMonitoringTag
    :widths: 20 70 10
    :header-rows: 1
    :class: longtable

    * - Tags within :litrep:`<monitoring>`
      - Description
      - Multiplicity
    * - :litrep:`<enabled>`
      - Whether to enable monitoring of the service.

        Default: Disabled, unless administration is enabled.
      - 0..1
    * - :litrep:`<domain_id>`
      - Domain ID used for monitoring.

        Default: The domain ID specified for monitoring.
      - 0..1
    * - :litrep:`<datawriter_qos>`
      - QoS used by monitoring DataWriter(s)
      - 0..1
    * - :litrep:`<publisher_qos>`
      - QoS used by monitoring Publisher(s)
      - 0..1
    * - :litrep:`<participant_qos>`
      - QoS used by monitoring DomainParticipant
      - 0..1
    * - :litrep:`<statistics_sampling_period>`
      - How frequently to sample the service's statistics, using the tags <sec>
        or <nanosec>. For example, <sec>1</sec> samples the service's
        statistics every second.
      - 0..1
    * - :litrep:`<status_publication_period>`
      - How frequently to publish the service status, using the tags <sec>
        or <nanosec>. For example, <sec>1</sec> publishes the service's status
        every second.
      - 0..1

The contents of the tags for configuring QoS are specified in the same
manner as for the *Connext DDS* QoS profile file. See
:link_xml_qos_config:`Configuring QoS with XML, in the RTI Connext
DDS Core Libraries User's Manual <>`.



.. _section-record-config-storage-tag:

Storage
-------

The ``<storage>`` tag allows you to configure the storage to which data will be
written. You can choose between using the builtin SQLite storage or
implementing your own storage plugin. You can also specify the *flush period* of
the service, defined as the time interval between consecutive writings of samples
to disk. Within <storage>, *Recording Service* can also be set in *buffering mode*.
This mode disables all automatic storage to disk and just writes the data to
disk upon reception of a remote `flush()` command.

.. list-table:: Storage Tags in Recording Service's Configuration File
    :name: TableRecorderStorageTag
    :widths: 20 70 10
    :header-rows: 1

    * - Tags within :litrep:`<storage>`
      - Description
      - Multiplicity
    * - :litrep:`<sqlite>`
      - Enables storing data in a SQLite database file.
        See :numref:`section-record-config-sqlite-tag`.
      - 0..1
    * - :litrep:`<plugin>`
      - Enables storing data in an external library that you specify.

        Attributes

            - ``plugin_name``: Name of the plug-in that creates a storage
              plugin object. This name shall refer to a registered storage plug-in.
              See :numref:`section-Common-PluginManagement` for details on how
              the options of how to register plugins).

        See :numref:`section-Record-Config-Storage-Plugin-Tag` for more about using
        this tag.

        See :numref:`section-record-custom-storage` for a tutorial on
        plugging in custom storage.
      - 0..1


.. _section-record-config-sqlite-tag:

SQLite
^^^^^^

The ``<sqlite>`` tag allows you to specify the name and file extension of a
SQLite file in which to write data. It also allows you to choose the storage
format in which to store the data. The default format, XCDR_AUTO, records
data without deserializing it from the network format, so it is the most
efficient way to store data; however, it is a binary format that cannot be
queried without using *Converter* to convert it to a readable JSON_SQLITE
format. The JSON_SQLITE format is slower to record, because it requires
deserializing the data, but it can be queried using SQLite tools.

.. list-table:: SQLite Tags in Recording Service's Configuration File
    :name: TableSqliteTag
    :widths: 20 70 10
    :header-rows: 1
    :class: longtable

    * - Tags within :litrep:`<sqlite>`
      - Description
      - Multiplicity
    * - :litrep:`<fileset>`
      - Set of files to write to, and parameters for creating files and
        directories in that set.

        See :numref:`section-config-fileset-tag`.
      - 0..1
    * - :litrep:`<file>`
      - File to write to. |br|

        Default: rti_recorder_default
      - 0..1
    * - :litrep:`<overwrite_policy_kind>`
      - Whether *Recording Service* is allowed to overwrite files.
        The options are OVERWRITE or DO_NOT_TOUCH. When DO_NOT_TOUCH is
        selected, *Recording Service* cannot overwrite an existing file,
        even if the rollover functionality is enabled.

        Default: OVERWRITE

      - 0..1
    * - :litrep:`<storage_format>`
      - Specifies what format the data is stored in.  |br|

        The options are:

        - XCDR_AUTO: This is the binary format used by *Connext DDS* when
          sending data over the network. This has the highest performance
          for recording, but
          can only be viewed by using *Converter* to convert the data to a
          readable format, or by using *Replay* to replay the data.  This will
          internally store data in XCDR or XCDR2 depending on the format received.

        - JSON_SQLITE: This format can be queried, but recording in this format has
          lower performance because data must be deserialized before it can be
          stored.

        - XCDR: The format to use when communicating with *Connext DDS* before 6.0.0.

        - XCDR2: More efficient than XCDR, used by *Connext DDS* 6.0.0 and later.

        Default: XCDR_AUTO

      - 0..1
    * - :litrep:`<sql_initialization_string>`
      - Specifies a SQLite SQL expression to use when establishing sqlite
        connections using this plugin.  This can be used to change the pragmas
        used by SQLite, or to do other database operations. |br|

        **Note**: when using *Recording Service* and another application (either
        *Replay Service* or another SQLite application) at the same time to
        access the same database files, we recommend using SQLite's WAL
        (write-ahead logging) mode. This can be done by adding
        ``PRAGMA JOURNAL_MODE = WAL;`` to this configuration setting. More
        information about SQLite's WAL mode can be found `here
        <http://www.sqlite.org/wal.html>`_.

        Default:
        PRAGMA SYNCHRONOUS = OFF; PRAGMA JOURNAL_MODE = MEMORY;
      - 0..1
    * - :litrep:`<flush_period>`
      - Defined as a duration (seconds and nanoseconds), <flush_period>
        represents the rate at which user-data samples will be written to disk.
        When this tag is present, *Recording Service* will work in a purely
        periodic fashion. If no  remote *flush()* command is received, data will
        be written to disk only when this period elapses.

        This tag cannot be used at the same time as the
        :litrep:`<enable_buffering_mode>` tag.

        Default: no default. If not set, *Recording Service* will work in a
        purely reactive way.
      - 0..1
    * - :litrep:`<enable_buffering_mode>`
      - When set to true, *Recording Service* will run in buffering mode. This mode
        is a listening-only mode and will not output data to disk automatically.
        Instead, *Recording Service* will wait continously for remote `flush()`
        commands to trigger the storage to disk (see section
        :numref:`section_record_remote_storage` for more information about the
        remote `flush` command).

        *Recording Service* will buffer samples using the caches in the DataReaders
        it creates, so it is important that the size of the caches is
        controlled so memory doesn't grow indefinitely. The size can be controlled
        by controlling the size of the queue (see section
        :numref:`section-recording-service-operation-mode`) or by ensuring that
        the rate at which `flush` remote commands are sent matches the sample
        rate. The general recommendation is to define a buffer size for all
        Topics and Topic Groups in the configuration.

        This tag cannot be used at the same time as the :litrep:`<flush_period>`
        tag.

        This feature *requires* remote administration to be enabled. If remote
        administration isn't enabled in the configuration, *Recording Service*
        will enable it automatically.

        Default: false (service will start in normal operation mode).
      - 0..1


.. _section-config-fileset-tag:

Fileset
'''''''

The ``<fileset>`` tag allows you to specify a set of files for *Recording
Service* to write to.  This lets you specify behaviors such as "create a new
directory with each run of *Recording Service* based on the timestamp when the
tool was started" or "create a new file every time *Recording Service* is
started, incrementing an integer in the filename."

The ``<fileset>`` tag is also where the rollover behavior is specified.

.. list-table:: Fileset Tags in Recording Service's Configuration File
    :name: TableFilesetTag
    :widths: 20 70 10
    :header-rows: 1
    :class: longtable

    * - Tags within :litrep:`<fileset>`
      - Description
      - Multiplicity
    * - :litrep:`<workspace_dir>`
      - Base directory where the database files for an instance of *Recording
        Service* (including discovery and user data files) will be stored.
        Depending on the value of the <execution_dir_expression> tag, this
        will either contain a set of files or a set of directories.

        Default: The current working directory.
      - 0..1
    * - :litrep:`<execution_dir_expression>`
      - When *Recording Service* starts, it will use this expression to
        create the directory where output files will be stored. Every
        time *Recording Service* starts, it will evaluate this expression
        to decide on its output
        directory. Stopping and restarting remotely will cause *Recording
        Service* to re-evaluate this expression and possibly change its output
        directory.

        This execution directory is a parameterisable expression.
        In it, it accepts text and any combination of the following:

          - Autonumeric. **Format: %auto:M-N%.** This parameter
            describes an integer that auto-increments every
            time *Recording Service* starts. The numeric
            sequence is restarted when *Recording Service*
            is manually shut down and restarted. M must be lower
            than N; together they define a numeric range, both inclusive.
            N can be omitted (%auto:M%), resulting in an
            unlimited sequence of numbers starting at M.

            Example:
              .. code-block:: xml

                <execution_dir_expression>
                  test_run_%auto:0-3%
                </execution_dir_expression>

            This example will create directories named test_run_0, test_run_1,
            test_run_2, and test_run_3.
          - Timestamp. **Format: %ts%.** This parameter will take
            the current timestamp in the system (the time
            represented as number of seconds since Epoch).
          - Time. **Format: %T%.** Current time expressed in ISO
            8601 time format (HH:MM:SS). Example: 14:55:02.
            This parameter uses the strftime() parameter %T.
          - Short date. **Format: %F%**. Short date in YYYY-MM-DD
            format. Example: 2001-08-23.
            This parameter uses the strftime() parameter %F.
          - Date and time. **Format: %c%**. Date and time
            representation, locale-dependent.
            This parameter uses the strftime() parameter %c.

        **Note**: Using parameters, *Recording Service* will check if the
        possible execution directories exist before overwriting any directory.
        If the execution directories exist, *Recording Service's* behavior
        will be affected by the value of the <overwrite_policy_kind> tag.
        If <overwrite_policy_kind> is set to OVERWRITE, *Recording Service*
        will overwrite the first directory. Otherwise, *Recording Service*
        will not delete any of the old directories and will just exit.

        Using no parameters will yield the same execution
        directory every time the service is started. In this case, if
        the directory already contains database files, they may
        be overwritten (see the <overwrite> tag).

        Default: %ts% (current timestamp number since Epoch).
      - 0..1
    * - :litrep:`<filename_expression>`
      - Once *Recording Service* knows the exact directory in which to put the
        database files, it will use this parameter to determine
        the name(s) of the user data file(s) to be created.
        Right before the recording starts and every time
        *Recording Service* has to change its current file to a new one, it
        will use this parameterisable expression to generate the
        next file's name.
        This setting accepts text and any combination of the
        following parameters:

          - Autonumeric. **Format: %auto:M-N%.** This parameter
            describes an integer that auto-increments every
            time *Recording Service* is started. However, the numeric
            sequence is restarted with every execution of the
            *Recording Service* application. M must be lower than N;
            together M and N define a numeric range, both inclusive.
            N may be omitted (%auto:M%), resulting in an unlimited
            sequence of numbers starting at M.

            Example:
              .. code-block:: xml

                <filename_expression>
                  test_files_%auto:0-2%.dat
                </filename_expression>

            This will create files named test_files_0.dat, test_files_1.dat,
            and test_files_2.dat.  When a rollover event occurs, *Recording
            Service* will either create one of these files, or overwrite the
            next file in the sequence. When *Recording Service* is restarted,
            this will start over with overwriting test_files_0.dat.
          - Timestamp. **Format: %ts%.** This parameter will take
            the current timestamp in the system (the time
            represented as number of seconds since Epoch).
          - Time. **Format: %T%.** Current time expressed in ISO
            8601 time format (HH:MM:SS). Example: 14:55:02.
            This parameter uses the strftime() parameter %T.
          - Short date. **Format: %F%.** Short date in YYYY-MM-DD
            format. Example: 2001-08-23.
            This parameter uses the strftime() parameter %F. |br|
            **Note:** This parameter will not vary in 24 hours, so
            use with caution in combination with the rollover
            time limit feature (time limit should be greater
            than 1 day; otherwise, you may overwrite the same
            file continously).
          - Date and time. **Format: %c%.** Date and time
            representation, locale-dependent.
            This parameter uses the strftime() parameter %c.

        **Note:** Using no parameters will yield the same file name
        every time. Therefore, if a file rollover command is
        received or scheduled, *Recording Service* will be
        stopped (no more data can be stored without overwriting
        the current, and only, file).
        Default: rti_recorder_default_%auto:0%.dat (auto-numeric
        starting at zero, unlimited).
      - 0..1
    * - :litrep:`<rollover>`
      - Configuration for rolling over the file after a size or time limit
        is reached.
        See :numref:`section-config-rollover-tag`.
      - 0..1


.. _section-config-rollover-tag:

Rollover
''''''''

Rollover enables *Recording Service* to overwrite the oldest
data file created by the current execution of the service when the last file
in the set has reached a maximum size, or when a time limit is reached.

**Note:** In this release, rollover is only supported when the
<filename_expression> tag specifies an auto-numeric filename.
(See example below.)

.. code-block:: xml

    <recording_service name="RolloverExample">
        <storage>
            <sqlite>
                <storage_format>JSON_SQLITE</storage_format>
                <fileset>
                    <workspace_dir>output_dir</workspace_dir>
                    <execution_dir_expression></execution_dir_expression>
                    <!-- Rollover file when the size hits 50 KB.  Files will
                         be numbered 0-9. -->
                    <filename_expression>file_rollover_%auto:0-9%.dat
                    </filename_expression>
                    <rollover>
                        <enabled>true</enabled>
                        <file_size_limit unit="KILOBYTES">50</file_size_limit>
                    </rollover>
                </fileset>
            </sqlite>
        </storage>
    </recording_service>

.. list-table:: Rollover Tags in Recording Service's Configuration File
    :name: TableRolloverTag
    :widths: 20 70 10
    :header-rows: 1

    * - Tags within :litrep:`<rollover>`
      - Description
      - Multiplicity
    * - :litrep:`<enabled>`
      - Whether *Recording Service* will roll over files when a limit is
        reached. |br|
        Default: False.
      - 0..1
    * - :litrep:`<file_size_limit>`
      -  The maximum allowed size for a file in a set.
         Note that setting this to a very low value
         (e.g., 1 KB) may yield unexpected behavior, because
         SQLite will take up more than that for even the simplest
         file. |br|
         **Note:** The unit refers to the decimal prefix and not the
         binary prefix of the number, meaning 1 MEGABYTES =
         1000 KB (and not 1024 KB). This
         is usually the standard way to refer to storage size.

         Attributes:
           - :litrep:`unit`: (Optional) The unit in which the size is expressed.
             The following values are allowed (Default: ``KILOBYTES``):

             - ``BYTES``
             - ``KILOBYTES``
             - ``MEGABYTES``
             - ``GIGABYTES``

      - 0..1
    * - :litrep:`<time_limit>`
      -  The maximum amount of time *Recording Service* can record to a file
         in a set.  Specified with tags <days>, <hours>, <minutes>, <seconds>.

         Attributes:
           - start_time: The time to do the first rollover.  After that,
             rollover will be done when the time_limit or file_size_limit is
             reached.
      - 0..1

.. _section-Record-Config-Storage-Plugin-Tag:

Plugin
^^^^^^

.. list-table:: Storage plugin Tag in the Configuration File
    :name: RecordTableStoragePluginTag
    :widths: 20 70 10
    :header-rows: 1

    * - Tags within :litrep:`<plugin>`
      - Description
      - Multiplicity
    * - :litrep:`<property>`
      - Name/value pairs of properties to pass to a storage plugin.
      - 0 or 1

.. _section-config-domainparticipant-tag:

DomainParticipant
-----------------

.. list-table:: DomainParticipant Tags in Recording Service's Configuration File
    :name: TableDomainParticipantTag
    :widths: 20 70 10
    :header-rows: 1
    :class: longtable

    * - Tags within :litrep:`<domain_participant>`
      - Description
      - Multiplicity
    * - :litrep:`<domain_id>`
      - **Required**. |br|
        DDS domain ID used for recording.
      - 1
    * - :litrep:`<participant_qos>`
      - QoS used by this DomainParticipant.
        See :link_xml_qos_config:`Configuring QoS with XML, in the RTI Connext
        DDS Core Libraries User's Manual <>`.
      - 0..1
    * - :litrep:`<memory_management>`
      - Configures certain aspects of how *Connext DDS* allocates internal
        memory. The configuration is per DomainParticipant and therefore
        affects all the contained DDS entities. |br|

        Example:
            .. code-block:: xml

                <memory_management>
                    <sample_buffer_min_size>
                       1024
                    </sample_buffer_min_size>
                    <sample_buffer_trim_to_size>
                       true
                    </sample_buffer_trim_to_size>
                </memory_management>

        Tags within this tag:
            -   :litrep:`<sample_buffer_min_size>`:  For all DataWriters and
                DataReaders, the way *Connext DDS* allocates memory for samples
                is as follows:
                *Connext DDS* pre-allocates space for samples up to size X in the
                DataWriter and DataReader queues. If a sample has an actual size greater
                than X, the memory is allocated dynamically for that sample.
                The default size is 64KB. This is the maximum amount of
                pre-allocated memory. Dynamic memory allocation may occur
                when necessary if samples require a bigger size.
            -   :litrep:`<sample_buffer_trim_to_size>`: If set to true, after allocating
                dynamic memory for very large samples, that memory will be
                released when possible. If false, that memory will not be
                released but kept for future samples if needed.
                The default is false.

        This feature is useful when a data type has a very high maximum size
        (e.g., megabytes) but most of the samples sent are much smaller than
        the maximum possible size (e.g., kilobytes). In this case, the memory
        footprint is reduced dramatically, while still correctly handling the
        rare cases in which very large samples are published.
      - 0..1
    * - :litrep:`<register_type>`
      - Registers a type name and associates it with a type representation.
        When you define a type in the configuration file, you have to
        register the type in order to use it in a ``<topic>``.

        Attributes:
          - ``name``: Name that the data type is registered with if no
            :litrep:`<registered_name>`  is specified. The same data type may be
            registered with different names. **Required**.
          - ``type_ref``: Definition of this data type. It must refer to one of
            the defined types in the ``<types>`` section by specifying the fully
            qualified name.

        Tags within this tag:
          - :litrep:`<registered_name>`: Name the data type is registered with.
            The same data type may be registered with different names. Not
            required.
      - 0..*


.. _section-config-session-tag:

Session
-------

The ``<session>`` tag configures the threads that will be used to record
data.  You also specify the Topics and groups of Topics to record inside the
``<session>`` tag.

.. list-table:: Session Tags in Recording Service's Configuration File
    :name: TableRecordingSessionTag
    :widths: 20 70 10
    :header-rows: 1
    :class: longtable

    * - Tags within :litrep:`<session>`
      - Description
      - Multiplicity
    * - :litrep:`<subscriber_qos>`
      - Specifies the QoS of DDS subscribers that will be used by the
        contained ``<topic>`` and ``<topic_group>``.  See
        :link_xml_qos_config:`Configuring QoS with XML, in the RTI Connext
        DDS Core Libraries User's Manual <>`.
      - 0..1
    * - :litrep:`<thread_pool>`
      - Defines the number of threads used by this session
        to process Topics and Topic Groups and allows you to set the mask,
        priority, and stack size of each thread.

        This setting can improve the reactiveness and scalability of the running
        *Recording Service* when there are multiple Topics and Topic Groups
        associated with the same session.

          Example:
              .. code-block:: xml

                  <thread_pool>
                      <mask>MASK_DEFAULT</mask>
                      <priority>THREAD_PRIORITY_DEFAULT</priority>
                      <stack_size>
                          THREAD_STACK_SIZE_DEFAULT
                      </stack_size>
                  </thread_pool>

          Default values:
              - **size**: 1
              - **mask**: MASK_DEFAULT
              - **priority**: THREAD_PRIORITY_DEFAULT
              - **stack_size**: THREAD_STACK_SIZE_DEFAULT

      - 0..1
    * - :litrep:`<topic>`
      - Specifies an individual Topic to record.

        Attributes:
          - name: The name of the Topic to record.  This name is also used when
            monitoring and administering each Topic.
          - participant_ref: A DomainParticipant to use when
            recording this Topic.  If the parent ``<session>``
            specifies a default_participant_ref, this attribute is optional.

        See :numref:`section-config-topic-tag`.

      - 0..*
    * - :litrep:`<topic_group>`
      - Specifies a group of Topics to record.

        Attributes:
          - name: The name of the Topic group. This name is also used when
            monitoring and administering each Topic group.
          - participant_ref: Specifies a DomainParticipant to use when
            recording this topic group. If the parent
            ``<session>`` specifies a default_participant_ref, this
            attribute is optional.

        See :numref:`section-config-topicgroup-tag`.

      - 0..*


.. _section-config-topicgroup-tag:

Topic Group
-----------

You can record a group of Topics, using regular expressions to
describe which Topics to record.

.. list-table:: Topic Group Tags in Recording Service's Configuration File
    :name: TableTopicGroupTag
    :widths: 20 70 10
    :header-rows: 1
    :class: longtable

    * - Tags within :litrep:`<topic_group>`
      - Description
      - Multiplicity
    * - :litrep:`<allow_topic_name_filter>`
      - A regular expression (fnmatch) describing which Topics are allowed to be
        recorded.
        You may use a comma-separated list to specify more than one filter. |br|

        Example:
            .. code-block:: xml

              <topic_group name="RecordAll">
                  <allow_topic_name_filter>CONTROL_*,DATA_*</allow_topic_name_filter>
              </topic_group>
      - 0..1
    * - :litrep:`<deny_topic_name_filter>`
      - A regular expression (fnmatch) describing which Topics are not allowed to be
        recorded. This tag is applied after the ``allow_topic_name_filter`` tag.
        You may use a comma-separated list to specify more than one filter.
      - 0..1
    * - :litrep:`<allow_type_name_filter>`
      - A regular expression (fnmatch) describing the names of data types that are
        allowed to be recorded.
        You may use a comma-separated list to specify more than one filter.
      - 0..1
    * - :litrep:`<deny_type_name_filter>`
      - A regular expression (fnmatch) describing the names of data types that are
        not allowed to be recorded. This tag is applied after the
        ``allow_type_name_filter`` tag.
        You may use a comma-separated list to specify more than one filter.
      - 0..1
    * - :litrep:`<datareader_qos>`
      - The DataReader's QoS to use when recording data.
      - 0..1
    * - :litrep:`<content_filter>`
      - A ContentFilteredTopic to use when recording data.
        See :link_xml_cft_config:`ContentFilteredTopics, in the RTI Connext
        DDS Core Libraries User's Manual <>`.

        This allows you to record data samples only if their contents pass a
        filter that you specify in your configuration.
        The filter looks like a SQL WHERE clause. Note that XML
        reserved characters must be converted to their escape values; for
        example, > and < (greater than and less than signs) must be
        converted to &lt; and &gt; as shown in the example below.

        Example:
            .. code-block:: xml

              <topic_group name="RecordAll">
                  <content_filter>
                      <!-- Data will only be recorded when x is greater than
                           100 -->
                      <expression>x &gt; 100</expression>
                  </content_filter>
              </topic_group>
      - 0..1


.. _section-config-topic-tag:

Topic
-----

The ``<topic>`` tag specifies an individual Topic to record.

.. list-table:: Topic Tags in Recording Service's Configuration File
    :name: TableTopicTag
    :widths: 20 70 10
    :header-rows: 1
    :class: longtable

    * - Tags within :litrep:`<topic>`
      - Description
      - Multiplicity
    * - :litrep:`<topic_name>`
      - The name of the DDS topic to be recorded. If this tag is not present,
        the name attribute of the `<topic>` will be used. |br|

        *Note*: we recommend using this tag to define the topic name. There may
        be characters that cause the XML validation to fail if they are part of
        the topic name attribute. Also, the '/' character and '::' separator may
        cause Recorder to fail when found in the topic name attribute.
      - 0..1
    * - :litrep:`<registered_type_name>`
      - **Required**. |br|
        The name of the data type that will be recorded for this topic.
      - 1
    * - :litrep:`<transformation>`
      - The transformation library to be applied to this Topic's data when
        recording.  This is a user library that can modify the data after
        it is received by *Connext DDS* and before it is stored in the database.
        Transformations implement APIs identical to *Routing Service*'s
        transformations.

        For more on using transformations, see these sections in the
        *RTI Routing Service User's Manual*:

        - :link_router_manual_config_transformation:`Data Transformation <>`
        - :link_router_manual_tutorials:`Tutorials <>`

        Attributes:
          - plugin_name: The name of the plugin to load, qualified by the
            plugin library name.

        Example:
            .. code-block:: xml

              <dds>
                  <plugin_library name="RecordTransformations">
                      <transformation_plugin name="ModifyTestID">
                          <create_function>ModifyTestID_create</create_function>
                          <dll>modify_test_id_library</dll>
                      </transformation_plugin>
                  </plugin_library>
                  <!-- ... -->
                  <recording_service>
                      <!-- ... -->
                      <topic name="TestTopic">
                          <transformation plugin_name="RecordTransformations::ModifyTestID" />
                      </topic>
                  </recording_service>
              </dds>
      - 0..1
    * - :litrep:`<datareader_qos>`
      - The DataReader QoS to use when recording this data.
      - 0..1
    * - :litrep:`<content_filter>`
      - A ContentFilteredTopic to use when recording data.
        See :link_xml_cft_config:`ContentFilteredTopics <>`, in the *RTI Connext
        DDS Core Libraries User's Manual*. |br|

        Example of how to set a content filter expression:
            .. code-block:: xml

              <topic_group name="RecordAll">
                  <content_filter>
                      <!-- Data will only be recorded when x is greater than
                           100 -->
                      <expression>x &gt; 100</expression>
                  </content_filter>
              </topic_group>
      - 0..1



.. _section-Config-EnablingLargedataFeatures:

Support for RTI FlatData and Zero Copy Transfer Over Shared Memory
------------------------------------------------------------------

*Recording Service* supports communication with applications that use
RTI FlatData™ and Zero Copy transfer over shared memory. You can configure
*Recording Service* to enable these capabilities for data reception.

To enable *Recording Service* to work with RTI FlatData and Zero-copy transfer
over shared memory, you will need to manually define the type in the XML
configuration with the proper annotations, and then register this type manually
in each |DP|. You can use each of these capabilities separately or together.

For further information about these capabilities, see the
:link_userman_largedata:`Sending Large Data <>` section in the
|RTI_CONNEXT| *User's Manual*.


Example: Configuration to enable both FlatData and Zero Copy transfer over shared memory
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


.. code-block:: xml

    <dds>
        <types>
            <struct name="Point"
                    transferMode="shmem_ref"
                    languageBinding="flat_data"
                    extensibility= "final">
                <member name="x" type="long"/>
                <member name="y" type="long"/>
            </struct>
        </types>

        <qos_library name="MyQosLib">
            <qos_profile name="ShmemOnly">
                <participant_qos>
                    <discovery>
                        <initial_peers>
                            <element>shmem://</element>
                        </initial_peers>
                    </discovery>
                    <transport_builtin>
                        <mask>SHMEM</mask>
                    </transport_builtin>
                </participant_qos>
            </qos_profile>
        </qos_library>

        <recording_service name="FlatDataWithZeroCopy">

            <domain_participant name="RecordDomain">
                <domain_id>0</domain_id>
                <participant_qos base_name="MyQosLib::ShmemOnly"/>
                <register_type name="Point" type_ref="Point"/>
            </domain_participant>

            <session default_participant_ref="RecordDomain">
                <topic name="PointTopic">
                    <registered_type_name>Point</registered_type_name>
                </topic>
            </session>
        </recording_service>

    </dds>


.. _section-Record-Config-Plugins:

Plugins
-------

All the pluggable components specific to *Recording Service* are configured
within the ``<plugin_library>`` tag. :numref:`TableRecordPluginLibraryTag` describes the
available tags.

Plug-ins are categorized and configured based on the
source language. *Recording Service* supports C/C++ plug-ins.


.. list-table:: Configuration tags for plug-in libraries
    :name: TableRecordPluginLibraryTag
    :widths: 30 60 10
    :header-rows: 1
    :class: longtable

    * - Tags within :litrep:`<plugin_library>`
      - Description
      - Multiplicity
    * - :litrep:`<storage_plugin>`
      - Specifies a C/C++ *Storage* plug-in. |br|
        See :numref:`TableNativePluginTag` and :numref:`section-record-config-storage-tag`.
      - 0..*
    * - :litrep:`<transformation_plugin>`
      - Specifies a C/C++ |TRANSF| plug-in. |br|
        See :numref:`TableNativePluginTag` and :numref:`section-config-topic-tag`.
      - 0..*

.. _section-config-enabling-distributed-logger:

Enabling Distributed Logger
---------------------------

*Distributed Logger* is included in *Connext DDS*
but it is not supported on all platforms;
see the *RTI Connext DDS Core Libraries Platform Notes* for the set of
platforms that support *Distributed Logger*.

When you enable *Distributed Logger*, the Service will publish its log
messages to *Connext DDS*.
Then you can use *RTI Admin Console* to visualize the log message data. Since
the data is provided in a topic, you can also use *rtiddsspy* or even write
your own visualization tool.

To enable *Distributed Logger*, use the tag ``<distributed_logger>`` within
``<adminstration>``. For example:

    .. code-block:: xml

        <recording_service name="RecordAll">
              <administration>
                    ...
                    <distributed_logger>
                        <enabled>true</enabled>
                    </distributed_logger>
                </administration>
                ...
        </recording_service>

For more details, see
:link_userman_distlog_in_services:`Enabling Distributed Logger in RTI Services,
in the RTI Connext DDS Core Libraries User's Manual <>`.


.. _section-builtin-config-recording-service:

Recording Service Builtin Configuration Details
-----------------------------------------------

The *Recording Service* builtin configuration specifies:
    - Recording all non-RTI Topics
    - In domain 0
    - Into a SQLite file named rti_recorder_default.dat
    - In the efficient XCDR format

.. code-block:: xml

    <?xml version="1.0" encoding="UTF-8"?>

    <dds xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../schema/rti_recording_service.xsd">

        <!-- Qos Library -->
        <qos_library name="QosLib">
            <qos_profile name="ReliableQos" >
                <datareader_qos>
                    <reliability>
                        <kind>RELIABLE_RELIABILITY_QOS</kind>
                    </reliability>
                    <history>
                        <kind>KEEP_ALL_HISTORY_QOS</kind>
                    </history>
                </datareader_qos>
            </qos_profile>
        </qos_library>

        <recording_service name="RecorderService">
            <!--  Top-level storage settings -->
            <storage>
                <sqlite>
                    <file>rti_recorder_default</file>
                    <file_suffix>dat</file_suffix>
                    <storage_format>XCDR_AUTO</storage_format>
                </sqlite>
            </storage>

            <!--  Top-level domain settings -->
            <domain_participant name="Participant0">
                <domain_id>0</domain_id>
            </domain_participant>

            <session name="DefaultSession">
                <topic_group name="RecordAll" participant_ref="Participant0">
                    <allow_topic_name_filter>*</allow_topic_name_filter>
                    <deny_topic_name_filter>rti/*</deny_topic_name_filter>
                    <datareader_qos base_name="QosLib::ReliableQos" />
                </topic_group>
            </session>
        </recording_service>

    </dds>