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.
• File 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.

Figure 4.1 Top-level Tags in the Replay Configuration File

Table 4.2 Top-Level Tags in Replay 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 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: Plug in custom storage, such as custom databases. For more information, see Section 4.5.3. Transform data after it is received from Connext DDS and before it is placed in storage. For more information, see Data Transformation, in the RTI Routing Service User’s Manual..	0..*
<replay_service>	Required. Specifies a Replay Service configuration. See Section 4.2.4. Attributes name: uniquely identifies a service configuration. Required. Example <replay_service name="ReplayAll"> <!-- your service settings ... --> </replay_service>	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.

Figure 4.2 Tags used to configure a Replay Service instance

Table 4.3 Replay Service Tags in Replay Service’s Configuration File

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.13.	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.14.	0..1
<domain_participant>	Required. Specifies a DomainParticipant to use to replay data. The domain ID specified for the DomainParticipant will be used to determine which domains to select from the database and (combined with the domainIdBase) which domains to replay the data into. For example, if data was originally recorded in domains 0 and 1, and you want to replay in domains 50 and 51, you must: Specify <domain_participant> tags with <domain_id> tags set to 0 and 1 in your configuration file. Use -domainIdBase 50 to specify that the domain IDs the data will actually be written into is offset by 50. See Section 4.2.12. Attributes: name: Uniquely defines a DomainParticipant. Required. Example <domain_participant name="Participant3"> <domain_id>3</domain_id> <!-- Participant QoS --> </domain_participant>	1..*
<session>	Required. Active component of Replay Service for replaying data. Contains one or more threads that can be used for replay. See Section 4.2.16. Attributes name: Uniquely defines a replay session. Required. default_participant_ref: Specifies a default DomainParticipant to be used by topics and topic groups belonging to this replay session. Children can override this by specifying their own participant. Example <session name="Session" default_participant_ref="Participant3"> <!-- ... topics / groups of topics to record --> </session>	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.

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.

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.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.

Table 4.4 Administration Tags in Replay Service’s Configuration File

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: history.kind = DDS_KEEP_ALL_HISTORY_QOS resource_limits.max_samples = 32	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: 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
<distributed_logger>	When you enable Distributed Logger, Replay 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.

4.2.6. Monitoring

The <monitoring> tag allows you to enable and configure remote monitoring of Replay Service.

Table 4.5 Monitoring Tags in Replay Service’s Configuration File

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.

Table 4.6 Storage Tags in Replay Service’s Configuration File

Tags within <storage>	Description	Multiplicity
<sqlite>	Enables replaying data from an SQLite database file See Section 4.2.8.	0..1
<plugin>	Enables replaying data from an external library that you specify. See Section 4.2.9 for more about using this tag. See Section 4.5.3 for a tutorial on plugging in custom storage. Attributes plugin_name: The name of the plugin to use from the plugin_library. This is the name of the plugin to load, qualified by the plugin library name.	0..1
<legacy>	Enables replaying data from a legacy (pre-6.0.0) database file. See Section 4.2.10.	0..1

4.2.8. SQLite

The <sqlite> tag allows you to specify a SQLite formatted file to read data from for replay.

Table 4.7 SQLite Tags in Replay Service’s Configuration File

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: 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
<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. This field is optional. When not included, the current directory will be used. 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. Example: <sql_initialization_string> CREATE INDEX IF NOT EXISTS pingtopic_0_by_rcp_timestamp ON 'PingTopic@0' (SampleInfo_reception_timestamp); </sql_initialization_string> 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 PRAGMA JOURNAL_MODE = WAL; to this configuration setting. More information about SQLite’s WAL mode can be found here. Default: PRAGMA SYNCHRONOUS = OFF; PRAGMA JOURNAL_MODE = MEMORY;	0..1

4.2.9. Plugin

This tag allows you to specify a plugin library that you can use to replay data from storage of your choice.

See Section 4.5.3 for a tutorial on plugging in custom storage.

Table 4.8 Plugin Tags in Replay Service’s Configuration File

Tags within <plugin>	Description	Multiplicity
<property>	Name/value pairs of properties to pass to a storage plugin.	0..1

4.2.10. Legacy

Table 4.9 Legacy Tags in the Configuration File

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.11.	0..1

4.2.11. 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.

Table 4.10 Domain Mapping Tags in the Configuration File

Tags within <domain_mapping>	Description	Multiplicity
<domain_map>	Required. A link between a recorded legacy domain name and a domain ID. Attributes: legacy_domain_name: Name of the recorded domain name as specified in the old Recording Service domain tag, for example: <domain name=”domain0”>. participant_ref: The name of a DomainParticipant specified below using a <domain_participant> tag. This DomainParticipant will be used to replay data specified by the legacy domain name.	1..*

4.2.12. 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.

Table 4.11 DomainParticipant Tags in Replay Service’s Configuration File

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. Example: <memory_management> <sample_buffer_min_size> 1024 </sample_buffer_min_size> <sample_buffer_trim_to_size> true </sample_buffer_trim_to_size> </memory_management> This tag includes the following tags: 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. 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
<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..*

4.2.13. 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.

Table 4.12 Playback Tags in Replay Service’s Configuration File

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.	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.14) 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.	0..1

4.2.14. Data Selection

Selection of data to replay from the database. Currently only supports selection using a time range.

Table 4.13 Data Selection Tags in Replay Service’s Configuration File

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.15.	0..1

4.2.15. 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).

Table 4.14 Time Range Tags in Replay Service’s Configuration File

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.16. 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.

Table 4.15 Session Tags in Replay Service’s Configuration File

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. Example: <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
<topic>	Specifies an individual Topic to replay. See Section 4.2.18. Attributes: name: The name of the Topic to replay. This name is also used when monitoring and administering each Topic. participant_ref: A DomainParticipant to use when replaying this Topic. If the parent <session> specifies a default_participant_ref, this attribute is optional.	0..*
<topic_group>	Specifies a group of Topics to replay. See Section 4.2.17. Attributes: name: The name of the topic group. This name is used when monitoring and administering each topic group. participant_ref: A DomainParticipant to use when replaying this topic group. If the parent <session> specifies a default_participant_ref, this attribute is optional.	0..*

4.2.17. Topic Group

The <topic_group> tag allows you to replay a group of Topics, using regular expressions to describe which Topics to replay.

Table 4.16 Topic Group Tags in Replay Service’s Configuration File

Tags within <topic_group>	Description	Multiplicity
<allow_topic_name_filter>	A regular expression describing which Topics are allowed to be replayed. Example: <topic_group name="ReplayAll"> <allow_topic_name_filter>*</allow_topic_name_filter> </topic_group>	0..1
<deny_topic_name_filter>	A regular expression describing which Topics are not allowed to be replayed. This is applied after the allow_topic_name_filter.	0..1
<allow_type_name_filter>	A regular expression describing the names of data types that are allowed to be replayed.	0..1
<deny_type_name_filter>	A regular expression describing the names of data types that are not allowed to be replayed. This is applied after the allow_type_name_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.18. Topic

The <topic> tag specifies an individual Topic to replay.

Table 4.17 Topic Tags in Replay Service’s Configuration File

Tags within <topic>	Description	Multiplicity
<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: Data Transformation Tutorials Attributes: plugin_name: The name of the plugin to load, qualified by the plugin library name. Example: <dds> <plugin_library name="ReplayTransformations"> <transformation_plugin name="ModifyTestID"> <create_function>ModifyTestID_create</create_function> <dll>modify_test_id_library</dll> </transformation_plugin> </plugin_library> <!-- ... --> <replay_service> <!-- ... --> <topic name="TestTopic"> <transformation plugin_name="ReplayTransformations::ModifyTestID" /> </topic> </replay_service> </dds>	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