4.2. Configuration¶
When you start Replay Service, you can specify a configuration file in XML format. In that file, you can specify the properties that control the behavior of the service. This section describes how to write a configuration file.
4.2.1. How to Load the XML Configuration¶
Replay Service loads its XML configuration from multiple locations. Here are the various sources of configuration files, listed in load order:
[working directory]/USER_REPLAY_SERVICE.xml
This file is loaded automatically if it exists.[NDDSHOME]/resource/xml/RTI_REPLAY_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 the Replay 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"?>
<!-- All of our files start with a dds tag -->
<dds xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../schema/rti_replay_service.xsd">
<!-- Qos Library -->
<qos_library name="MyQosLib">
<qos_profile name="DurableQos">
<datawriter_qos>
<reliability>
<kind>RELIABLE_RELIABILITY_QOS</kind>
</reliability>
</datawriter_qos>
</qos_profile>
</qos_library>
<!-- Replay service instance -->
<replay_service name="MyReplayService">
<!-- Input file to use when replaying -->
<storage>
<sqlite>
<database_dir>.</database_dir>
</sqlite>
</storage>
<!-- Select the begin and end time of the data to replay -->
<data_selection>
<time_range>
<begin_time>
<sec>200</sec>
<nanosec>2000000</nanosec>
</begin_time>
</time_range>
</data_selection>
<!-- Domain Participant for replaying data -->
<domain_participant name="Participant0">
<domain_id>0</domain_id>
</domain_participant>
<!-- The session that is replaying the data. Contains configuration
for publishers, threading, group of topics to replay. -->
<session name="Session" default_participant_ref="Participant0">
<!-- Topics to replay in this session -->
<topic_group name="RecordAll">
<!-- Topics to replay -->
<allow_topic_name_filter>*</allow_topic_name_filter>
</topic_group>
</session>
</replay_service>
</dds>
4.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, Replay 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_replay_service.xsd
.
(See Section 1.3 for the path to NDDSHOME.)
To include a reference to the XSD document in your XML file, use the
attribute xsi:noNamespaceSchemaLocation
in the <dds>
tag. For example:
<dds xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../schema/rti_recording_service.xsd">
<!-- ... -->
</dds>
4.2.3. XML Tags for Configuring Replay Service¶
This section describes the XML tags you can use in a Replay Service
configuration file. Figure 4.1 and
Table 4.2 describe the
top-level tags allowed within the root <dds>
tag.
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 a 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 Replay Service. This tag 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..* |
<replay_service> | Required.
|
1..* |
4.2.4. Replay Service Tag¶
A configuration file must have at least one <replay_service>
tag. This
tag is used to configure an execution of Replay Service.
A configuration file may contain multiple <replay_service>
tags. When
you start Replay Service, you can specify which <replay_service>
tag to use to configure the service using the -cfgName command-line
parameter. This means one file can be used to configure multiple
Replay Service executions.
Figure 4.2 and Table 4.3
describe the tags allowed within a <replay_service>
tag.
Tags within <replay_service> | Description | Multiplicity |
---|---|---|
<administration> | Enables remote administration. When administration is enabled, monitoring is also enabled by default. See Section 4.2.5. |
0..1 |
<monitoring> | Enables monitoring for Replay Service, including statistics. See Section 4.2.6. | 0..1 |
<storage> | Describes how the data will be loaded from storage. See Section 4.2.7. If this is not specified, data will be loaded from the current working directory. |
0..1 |
<playback> | Specifies the timing rules for how data is played back. See Section 4.2.11. | 0..1 |
<data_selection> | Enables selection of a subset of data to replay. Supports selecting replay data by time (or tagged time). See Section 4.2.12. | 0..1 |
<domain_participant> | Required.
See Section 4.2.10.
|
1..* |
<session> | Required.
|
1..* |
4.2.4.1. Example: Specify a Replay Service Configuration in XML¶
<dds>
<replay_service name="MyReplayService">
<!-- ... Required entities -->
</replay_service>
</dds>
Starting a Replay Service with the following command will use the
<replay_service>
tag with the name “MyReplayService”.
$NDDSHOME/bin/rtireplayservice -cfgFile file.xml -cfgName MyReplayService
Replay Service uses the Topic names and domain IDs specified in the
configuration file to determine which data to replay. To replay data into
a different domain than the one it was recorded from, use the
-domainIdBase
command-line parameter to change the output domain ID.
4.2.5. Administration¶
The <administration>
tag allows you to enable and configure remote
administration of Replay Service, including stopping, starting, and
pausing replay.
See Section 4.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, Replay Service will publish its Log messages to Connext DDS. See Section 3.2.15. | 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.
4.2.6. Monitoring¶
The <monitoring>
tag allows you to enable and configure remote
monitoring of Replay Service.
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: Use 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.
4.2.7. Storage¶
The <storage>
tag allows you to configure the storage from which data will
be read. You can choose between using the builtin SQLite storage or
implementing your own storage plugin.
Tags within <storage> | Description | Multiplicity |
---|---|---|
<sqlite> | Enables replaying data from an SQLite database file See Section 4.2.7.1. | 0..1 |
<plugin> | Enables storing data in an external library that you specify. Attributes
See Section 4.2.7.2 for more about using this tag. See Section 4.5.3 for a tutorial on plugging in custom storage. |
0..1 |
4.2.7.1. SQLite¶
The <sqlite>
tag allows you to specify a SQLite formatted file to read
data from for replay.
Tags within <sqlite> | Description | Multiplicity |
---|---|---|
<storage_format> | The storage format of the user data files found in the database directory. If not specified, XCDR_AUTO is assumed. The options are:
Default: XCDR_AUTO. |
0..1 |
<database_dir> | The directory where to look for a recorded database.
The directory must contain a valid metadata file, as
well as a discovery file and one or many user data
files. Default: the current directory. |
0..1 |
<sql_initialization_string> | Allows configuring an SQLite SQL expression to use when establishing SQLite connections using this plugin. You can add an index to a table to speed up replay, but this must be done for each table you want to index. Note that you can perform this step using an SQLite client.
Note: when using Recorder and Replay at the same time for the same DB
file(s), or for that matter, any other SQLite application accessing the
data, we recommend using SQLite’s WAL (write-ahead logging) mode. This
can be done by adding Default:
|
0..1 |
4.2.8. Legacy¶
Tags within <legacy> | Description | Multiplicity |
---|---|---|
<file_path> | Path to the legacy format recorded file. File set and version properties will be obtained automatically from the file itself. | 0..1 |
<domain_mapping> | This tag allows you to link legacy domain names with domain IDs. See Section 4.2.9. | 0..1 |
4.2.9. Domain Mapping¶
When converting a legacy database, the domain may not have been recorded. This tag provides a way to map a table with a domain ID.
Later versions of the old Recorder database allowed you to use field filters. By default, the domain ID field was not recorded (it was filtered out by default). Thus, there is no information available in these legacy databases to relate the domain name used to record the data with a domain ID. This tag allows you to link legacy domain names with domain IDs.
Tags within <domain_mapping> | Description | Multiplicity |
---|---|---|
<domain_map> | Required.
|
1..* |
4.2.10. DomainParticipant¶
The <domain_participant>
tag allows you to specify the
DomainParticipants and domain IDs you want to query from the database
for replay. You can replay in the same domain you used to record, or
you can use the -domainIdBase
command-line parameter to replay in a
different domain.
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.
Tags within <domain_participant> | Description | Multiplicity |
---|---|---|
<domain_id> | The domain ID of tables loaded from the database. This is used
(in conjunction with the -domainIdBase command-line parameter) to
choose which domain to replay into. |
1 |
<participant_qos> | QoS used by this DomainParticipant. | 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
|
0..* |
4.2.11. Playback¶
The <playback>
tag allows you to specify the timing rules for how the
data is played back, such as the time on the local machine to start the
replay, if it is not started immediately.
Tags within <playback> | Description | Multiplicity |
---|---|---|
<start_replay_local_time> | Selects the local time when Replay Service should start
publishing samples. Specified in hours, minutes, and seconds. Specifying a full date is not currently supported, so if you specify a time that happened in the past (which Replay Service interprets as in the past today), replay will start immediately. Default: Replay will start immediately |
0..1 |
<fidelity> | Specifies the fidelity of the replayed data. Samples whose timestamp distance is less than the fidelity period may be published together in the same batch. For example, if your fidelity is 100 ms, data stored in your database within a 100 ms time period may be published together.
|
0..1 |
<rate> | Specifies the rate to replay data, as a double. For example, to play data at half speed, use 0.5. Default: 1 (normal speed) | 0..1 |
<enable_looping> | Plays the data in a repeating loop, until Replay Service is stopped.
Note that this means that only a termination signal or a remote shutdown
command will make it stop replaying data. When no time range data selection has been specified (see Section 4.2.12) then Replay will replay the whole contents of the database file(s) and when it’s time to loop, it will start from the very beginning of the file or files. However, when a specific time range has been specified for replay, the looping will respect the time range and will restart at the specified start time and end at the specified end time. Note: in our default SQLite implementation, Replay is able to check if new data has been written by Recorder (or any application) for every given stream being replayed, since the start of the service. This feature is generally not supported when looping without specifying a time range and may yield unexpected results. Default: false. |
0..1 |
4.2.12. Data Selection¶
Selection of data to replay from the database. Currently only supports selection using a time range.
Tags within <data_selection> | Description | Multiplicity |
---|---|---|
<time_range> | Select data to replay from the database, based on start and end times. See Section 4.2.13. | 0..1 |
4.2.13. Time Range¶
The <time_range>
tag allows you to specify the begin and end times
of the data you want to replay. This can be specified either as timestamps
or as symbolic timestamps called “timestamp tags.” These tags may have
been added to the recording through remote administration, and can be viewed
using the script rtirecordingservice_list_tags
(see Section 3.5.7).
Tags within <time_range> | Description | Multiplicity |
---|---|---|
<begin_time> | Select data to replay from the database, with a timestamp beginning at
this time. Specify the time in seconds and nanoseconds. Default: 0, start at beginning of the file. |
0..1 |
<begin_tag> | Can be used instead of begin_time. Select data to start replaying
from the database by specifying the string name of a timestamp tag.
Timestamp tags associate a timestamp with a name. Then you
can refer to a timestamp by that name.
The timestamp must have been tagged with that name during recording.
See Section 3.5.6. Default: Start at beginning of the file. |
0..1 |
<end_time> | Select data to replay from the database, with a timestamp ending at this
time. Specify the time in seconds and nanoseconds. Default: Stop at end of file. |
0..1 |
<end_tag> | Can be used instead of end_time. Select when to stop replaying data
by specifying the string name of a timestamp tag.
Timestamp tags associate a timestamp with a name. Then you
can refer to a timestamp by that name.
The timestamp must have been tagged with that name during recording.
See Section 3.5.6. Default: Stop at end of file. |
0..1 |
4.2.14. Session¶
The <session>
tag configures the threads that will be used to replay
data. You also specify the Topics and groups of Topics to replay inside the
<session> tag.
Tags within <session> | Description | Multiplicity |
---|---|---|
<publisher_qos> | Specifies the QoS of the Publisher that will be used by the
contained <topic> and <topic_group> . For information on
configuring Pubscriber QoS with XML, 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 replay. See Section 4.2.16.
|
0..* |
<topic_group> | Specifies a group of Topics to replay. See Section 4.2.15.
|
0..* |
4.2.15. Topic Group¶
The <topic_group>
tag allows you to replay a group of Topics,
using regular expressions to describe which Topics to replay.
Tags within <topic_group> | Description | Multiplicity |
---|---|---|
<allow_topic_name_filter> | A regular expression (fnmatch) describing which Topics are allowed to be
replayed.
You may use a comma-separated list to specify more than one filter.
|
0..1 |
<deny_topic_name_filter> | A regular expression (fnmatch) describing which Topics are not allowed to be
replayed. This is applied after the allow_topic_name_filter .
You may use a comma-separated list to specify more than one filter. |
0..1 |
<allow_type_name_filter> | A regular expression (fnmatch) describing the names of data types that are allowed to be replayed. You may use a comma-separated list to specify more than one filter. | 0..1 |
<deny_type_name_filter> | A regular expression (fnmatch) describing the names of data types that are
not allowed to be replayed. This is applied after the
allow_type_name_filter .
You may use a comma-separated list to specify more than one filter. |
0..1 |
<datawriter_qos> | The DataWriter’s QoS to use when replaying this data. For information on configuring QoS with XML, see Configuring QoS with XML, in the RTI Connext DDS Core Libraries User’s Manual. | 0..1 |
4.2.16. Topic¶
The <topic>
tag specifies an individual Topic to replay.
Tags within <topic> | Description | Multiplicity |
---|---|---|
<topic_name> | The name of the DDS topic to be replayed. If this tag is not present,
the name attribute of the <topic> will be used. 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 Replay to fail when found in the topic name attribute. |
0..1 |
<registered_type_name> | The name of the data type that will be replayed for this topic. Required. | 1 |
<transformation> | The transformation library to be applied to this Topic’s data when replaying. This is a user library that can modify the data after it is received from storage and before it is sent via Connext DDS. 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 |
<datawriter_qos> | The DataWriter QoS to use when replaying this data. For information on configuring QoS with XML, see Configuring QoS with XML, in the RTI Connext DDS Core Libraries User’s Manual. | 0..1 |
4.2.17. Plugins¶
All the pluggable components specific to Recording Service are configured
within the <plugin_library>
tag. Table 4.18 describes the
available tags.
Plug-ins are categorized and configured based on the source language. Replay Service supports C/C++ plugins.
Tags within <plugin_library> | Description | Multiplicity |
---|---|---|
<storage_plugin> | Specifies a C/C++ Storage plugin. See Table 7.16 and Section 3.2.8. |
0..* |
<transformation_plugin> | Specifies a C/C++ Transformation plugin. See Table 7.16 and Section 3.2.12. |
0..* |