3.2. 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.
3.2.1. 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.- File 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 Section 1.3.
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.
<?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>
3.2.2. 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 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:
<?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 Section 1.3.
3.2.3. Builtin Configuration of Recording Service¶
Recording Service is pre-configured with a builtin configuration. See Section 3.2.18 for more details.
3.2.4. 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.
![Top-Level tags in Recording Service's Configuration File](../_images/RecordingServiceTopLevelTags.png)
Figure 3.1 Top-level Tags in Recording Service’s Configuration File
Tags within <dds> | Description | Multiplicity |
---|---|---|
<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 Configuring QoS with XML in the RTI Connext DDS Core Libraries User’s Manual. | 0..* |
<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 Creating User Data Types with Extensible Markup Language (XML), in the RTI Connext DDS Core Libraries User’s Manual. | 0..* |
<plugin_library> | Contains a list of libraries that can be used to:
|
0..* |
<recording_service> | Required.
|
1..* |
3.2.5. 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 Table 3.3 describe the
tags allowed within a <recording_service>
tag.
![Tags used to configure a Recording Service instance](../_images/RecordingServiceTags.png)
Figure 3.2 Tags used to configure a Recording Service instance
Tags within <recording_service> | Description | Multiplicity |
---|---|---|
<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 Section 3.2.6. |
0..1 |
<monitoring> | Enables monitoring for the recording service, including statistics. See Section 3.2.7. | 0..1 |
<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 Section 3.2.8. | 0..1 |
<domain_participant> | Required.
See Section 3.2.13. |
1..* |
<session> | Required.
See Section 3.2.14. |
1..* |
3.2.5.1. Example: Specify a Recording Service Configuration in 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”:
$NDDSHOME/bin/rtirecordingservice -cfgFile file.xml -cfgName MyRecorderService
3.2.6. Administration¶
The <administration>
tag allows you to enable and configure remote
administration of Recording Service, including stopping, starting,
and pausing recording.
See Section 3.3 for details on using remote administration.
Tags within <administration> | Description | Multiplicity |
---|---|---|
<domain_id> | Domain ID used for remote administration. Also used for monitoring by default. | 0..1 |
<participant_qos> | QoS used by the administration DomainParticipant. If the tag is not defined, Connext DDS defaults will be used. | 0..1 |
<publisher_qos> | QoS used by the administration Publisher. If the tag is not defined, Connext DDS defaults will be used. | 0..1 |
<subscriber_qos> | QoS used by the administration Subscriber. If the tag is not defined, Connext DDS defaults will be used. | 0..1 |
<datawriter_qos> | QoS used by administration DataWriter(s). If the tag is not defined, Connext DDS defaults will be used, with the following changes:
|
0..1 |
<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:
|
0..1 |
<distributed_logger> | When you enable Distributed Logger, Recording Service will publish its Log messages to Connext DDS. See Section 3.2.17. | 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 Configuring QoS with XML, in the RTI Connext DDS Core Libraries User’s Manual.
3.2.7. Monitoring¶
The <monitoring>
tag allows you to enable and configure remote
monitoring of Recording Service.
See Section 3.4.
Tags within <monitoring> | Description | Multiplicity |
---|---|---|
<enabled> | Whether to enable monitoring of the service. Default: Disabled, unless administration is enabled. |
0..1 |
<domain_id> | Domain ID used for monitoring. Default: The domain ID specified for monitoring. |
0..1 |
<datawriter_qos> | QoS used by monitoring DataWriter(s) | 0..1 |
<publisher_qos> | QoS used by monitoring Publisher(s) | 0..1 |
<participant_qos> | QoS used by monitoring DomainParticipant | 0..1 |
<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 |
<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 Configuring QoS with XML, in the RTI Connext DDS Core Libraries User’s Manual.
3.2.8. 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.
Tags within <storage> | Description | Multiplicity |
---|---|---|
<sqlite> | Enables storing data in a SQLite database file. See Section 3.2.9. | 0..1 |
<plugin> | Enables storing data in an external library that you specify. See Section 3.2.12 for more about using this tag. See Section 3.5.4 for a tutorial on plugging in custom storage. |
0..1 |
3.2.9. 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.
Tags within <sqlite> | Description | Multiplicity |
---|---|---|
<fileset> | Set of files to write to, and parameters for creating files and directories in that set. See Section 3.2.10. |
0..1 |
<file> | File to write to. Default: rti_recorder_default |
0..1 |
<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 |
<storage_format> | Specifies what format the data is stored in. The options are:
Default: XCDR_AUTO |
0..1 |
<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. 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
Default: PRAGMA SYNCHRONOUS = OFF; PRAGMA JOURNAL_MODE = MEMORY; |
0..1 |
3.2.10. 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.
Tags within <fileset> | Description | Multiplicity |
---|---|---|
<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 |
<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:
Note: 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 |
<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:
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 |
<rollover> | Configuration for rolling over the file after a size or time limit is reached. See Section 3.2.11. | 0..1 |
3.2.11. 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.)
<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>
Tags within <rollover> | Description | Multiplicity |
---|---|---|
<enabled> | Whether Recording Service will roll over files when a limit is
reached. Default: False. |
0..1 |
<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. 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. |
0..1 |
<time_limit> | The maximum amount of time Recording Service can record to a file in a set. Specified with tags <days>, <hours>, <minutes>, <seconds>.
|
0..1 |
3.2.12. Plugin¶
Tags within <plugin> | Description | Multiplicity |
---|---|---|
<property> | Name/value pairs of properties to pass to a storage plugin. | 0 or 1 |
3.2.13. DomainParticipant¶
Tags within <domain_participant> | Description | Multiplicity |
---|---|---|
<domain_id> | Required. DDS domain ID used for recording. |
1 |
<participant_qos> | QoS used by this DomainParticipant. See Configuring QoS with XML, in the RTI Connext DDS Core Libraries User’s Manual. | 0..1 |
<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.
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 |
<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> . |
0..* |
3.2.14. 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.
Tags within <session> | Description | Multiplicity |
---|---|---|
<subscriber_qos> | Specifies the QoS of DDS subscribers that will be used by the
contained <topic> and <topic_group> . See
Configuring QoS with XML, in the RTI Connext
DDS Core Libraries User’s Manual. |
0..1 |
<thread_pool> | Defines the number of threads used by this session to process Topics and Topic Groups and sets the mask, priority, and stack size of each thread.
|
0..1 |
<topic> | Specifies an individual Topic to record.
See Section 3.2.16. |
0..* |
<topic_group> | Specifies a group of Topics to record.
See Section 3.2.15. |
0..* |
3.2.15. Topic Group¶
You can record a group of Topics, using regular expressions to describe which Topics to record.
Tags within <topic_group> | Description | Multiplicity |
---|---|---|
<allow_topic_name_filter> | A regular expression describing which Topics are allowed to be recorded.
|
0..1 |
<deny_topic_name_filter> | A regular expression describing which Topics are not allowed to be
recorded. This tag is applied after the allow_topic_name_filter tag. |
0..1 |
<allow_type_name_filter> | A regular expression describing the names of data types that are allowed to be recorded. | 0..1 |
<deny_type_name_filter> | A regular expression describing the names of data types that are
not allowed to be recorded. This tag is applied after the
allow_type_name_filter tag. |
0..1 |
<datareader_qos> | The DataReader’s QoS to use when recording data. | 0..1 |
<content_filter> | A ContentFilteredTopic to use when recording data. See 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 < and > as shown in the example below.
|
0..1 |
3.2.16. Topic¶
The <topic>
tag specifies an individual Topic to record.
Tags within <topic> | Description | Multiplicity |
---|---|---|
<registered_type_name> | Required. The name of the data type that will be recorded for this topic. |
1 |
<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:
|
0..1 |
<datareader_qos> | The DataReader QoS to use when recording this data. | 0..1 |
<content_filter> | A ContentFilteredTopic to use when recording data.
See ContentFilteredTopics, in the RTI Connext
DDS Core Libraries User’s Manual.
|
0..1 |
Support for RTI FlatData and Zero Copy Transfer Over Shared Memory ——————————————————————s
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 DomainParticipant. You can use each of these capabilities separately or together.
For further information about these capabilities, see the Sending Large Data section in the RTI Connext DDS User’s Manual.
3.2.17. 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:
<recording_service name="RecordAll"> <administration> ... <distributed_logger> <enabled>true</enabled> </distributed_logger> </administration> ... </recording_service>
For more details, see Enabling Distributed Logger in RTI Services, in the RTI Connext DDS Core Libraries User’s Manual.
3.2.18. 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
<?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>