4.3. Configuration¶
This section provides a reference for the XML elements that comprises a Replay Service configuration. For details on how to provide XML configurations to Replay Service. refer to Configuring RTI Services. This chapter describes how to compose an XML configuration.
4.3.1. 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.
![Top-Level Tags in Replay Service's Configuration File](../_images/ReplayTopLevelTags.png)
Figure 4.1 Top-level Tags in the Replay 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 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.3.2. 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 used to configure a |REPS| instance](../_images/ReplayServiceTags.png)
Figure 4.2 Tags used to configure a Replay Service instance¶
Tags within <replay_service> |
Description |
Multiplicity |
---|---|---|
<administration> |
Enables remote administration. |
0..1 |
<monitoring> |
Enables monitoring for Replay Service, including statistics. See Section 4.3.4. |
0..1 |
<storage> |
Describes how the data will be loaded from storage. |
0..1 |
<playback> |
Specifies the timing rules for how data is played back. See Section 4.3.9. |
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.3.10. |
0..1 |
<domain_participant> |
Required.
See Section 4.3.8.
|
1..* |
<session> |
Required.
|
1..* |
4.3.2.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.
![Domain ID Mapping Between the XML, the Database, and the DDS Domain](../_images/ReplayDomainUsage.png)
Figure 4.3 The domain ID specified inside a DomainParticipant, in combination with
the Topic name, is used to load data from recorded tables. In this case,
the DomainParticipant’s domain ID is set to 3.
The topic_group
specifies all topics.¶
![-domainIdBase on Command Line Affects Output DDS Domain](../_images/ReplayDomainUsageWithBase.png)
Figure 4.4 To replay data in a different domain than where it was
recorded, use the -domainIdBase
command-line parameter to
specify a base ID for the replay domain. Here, by specifying
a domainIdBase of 2, all Topics will be replayed in their original
domain, plus 2.¶
4.3.3. Administration¶
The <administration>
tag allows you to enable and configure remote
administration of Replay Service, including stopping, starting, and
pausing replay.
See Section 4.4 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.3.13. |
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.3.4. 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. Default: 1 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. Default: 5 seconds |
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.3.5. 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.3.5.1. |
0..1 |
<plugin> |
Enables storing data in an external library that you specify. Attributes
See Section 4.3.5.2 for more about using this tag. See Section 4.6.3 for a tutorial on plugging in custom storage. |
0..1 |
4.3.5.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 This scenario is not fully supported. Please be aware that the WAL file will grow without bounds during the replay operation. This implies that the database file will not be updated with the WAL contents until all the Replay instances finish executing. Default:
|
0..1 |
4.3.5.2. Plugin¶
Tags within <plugin> |
Description |
Multiplicity |
---|---|---|
<property> |
Name/value pairs of properties to pass to a storage plugin.
|
0 or 1 |
4.3.6. 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.3.7. |
0..1 |
4.3.7. 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.3.8. 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 |
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.3.9. 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.
The example above indicates that Replay Service will will start the replay at 14:30 pm. 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. |
0..1 |
<reverse_mode> |
Plays the data in reverse, while maintaining the fidelity of the recorded
database. Replay Service will start its replay with the last sample recorded
and it will finish with the first sample recorded. Replay Service will discover
all the StreamReaders at the beginning of the Replay in this mode. |
0..1 |
<sample_order> |
Specifies the timestamp kind to replay data. If not specified, RECEPTION_TIMESTAMP is assumed. The options are:
Note: For more information about source timestamp and reception timestamp, please see Section 4.1.6. Default: RECEPTION_TIMESTAMP. |
0..1 |
<instance_history_replay> |
Specifies whether Instance History Replay (state of the world publication) is enabled. See Section 4.1.7 for a description of the feature.
|
0..1 |
4.3.9.1. Debug mode¶
The <debug_mode>
tag allows you to enable the debug mode, such as
set the slice period and the initial list of breakpoints.
Tags within <debug_mode> |
Description |
Multiplicity |
---|---|---|
<enabled> |
Enables debug mode. |
0..1 |
<slice_period> |
Specifies the slice period of the replay. It will determine the replay period when you use a next_slice or continue operation. After that period of time Replay Service will pause the replay. Default: 1 s |
0..1 |
<initial_breakpoints> |
Specifies an initial list of breakpoints. Those breakpoints will be set once the replay start.
|
0..1 |
4.3.10. 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.3.11. |
0..1 |
4.3.11. 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.6.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. |
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.6.6. |
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. |
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.6.6. |
0..1 |
4.3.12. 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 |
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.3.14.
|
0..* |
<topic_group> |
Specifies a group of Topics to replay. See Section 4.3.13.
|
0..* |
4.3.13. 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 |
---|---|---|
<publish_with_original_info> |
Writes the data sample as if it came from its original writer. |
0..1 |
<publish_with_original_timestamp> |
Indicates if the data samples are written with their original source
timestamp. |
0..1 |
<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 |
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
|
0..1 |
<on_delete_wait_for_ack_timeout> |
Specifies a period for which the StreamWriter will wait for acknowledgment before its elimination. See Waiting for Acknowledgments in a DataWriter, in the Connext DDS Core Libraries User’s Manual. Default: 0 (no wait for acknowledgment)
The example above indicates that StreamWriter will wait one second for acknowledgment of the samples. |
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.3.14. 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 |
<publish_with_original_info> |
Writes the data sample as if it came from its original writer. |
0..1 |
<publish_with_original_timestamp> |
Indicates if the data samples are written with their original source
timestamp. |
0..1 |
<on_delete_wait_for_ack_timeout> |
Specifies a period for which the StreamWriter will wait for acknowledgment before its elimination. See Waiting for Acknowledgments in a DataWriter, in the Connext DDS Core Libraries User’s Manual. Default: 0 (no wait for acknowledgment)
The example above indicates that StreamWriter will wait one second for acknowledgment of the samples. |
0..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.3.15. Plugins¶
All the pluggable components specific to Recording Service are configured
within the <plugin_library>
tag. Table 4.19 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. |
0..* |
<transformation_plugin> |
Specifies a C/C++ Transformation plugin. |
0..* |