3.3. Configuration

This section provides a reference for the XML elements that comprise a Recording Service configuration. For details on how to provide XML configurations to Recording Service. refer to Configuring RTI Services. This chapter describes how to compose an XML configuration.

Note

Recording Service makes use of XSD files to validate the XML configuration files used to configure Recording Service. Due to the restrictions imposed by XSD schemas for XML 1.0, some of the tags used in the configuration must be grouped in order. This behavior is intended; Recording Service validates the XML files before parsing them to catch as many parsing errors as possible beforehand.

3.3.1. Builtin Configuration of Recording Service

Recording Service is pre-configured with a builtin configuration. See Section 3.3.15 for more details.

3.3.2. XML Tags for Configuring Recording Service

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

Figure 3.1 Top-level Tags in Recording Service’s Configuration File

Table 3.3 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: Plug in custom storage, such as custom databases. For more information, see Section 3.6.4. Transform data after it is received from Connext DDS and before it is stored. For more on using transformations, see Data Transformation, in the RTI Routing Service User’s Manual. See Section 3.3.12	0..*
<recording_service>	Required. Specifies a Recording Service configuration. See Section 3.3.3. Attributes name: Uniquely identifies a service configuration. Required. Example <recording_service name="RecordAll"> <!-- your service settings ... --> </recording_service>	1..*

3.3.3. 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.4 describe the tags allowed within a <recording_service> tag.

Figure 3.2 Tags used to configure a Recording Service instance

Table 3.4 Recording Service Tags in Recording Service’s Configuration File

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.3.4.	0..1
<monitoring>	Enables monitoring for the recording service, including statistics. See Section 3.3.5.	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.db”. See Section 3.3.6.	0..1
<domain_participant>	Required. Specifies a DomainParticipant to use to record data. Attributes name: Uniquely defines a DomainParticipant. Required. Example <domain_participant name="Participant3"> <domain_id>3</domain_id> <!-- Participant QoS --> </domain_participant> See Section 3.3.7.	1..*
<session>	Required. Active component of Recording Service for recording data. Contains one or more threads that can be used for recording. Attributes name: Uniquely defines a recording session. Required. default_participant_ref: Specifies a default DomainParticipant to be used by children of this recording session. Children can override this by specifying their own participant. Example <session name="Session" default_participant_ref="Participant3"> <!-- ... topics / groups of topics to record --> </session> See Section 3.3.8.	1..*

3.3.3.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.3.4. Administration

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

See Section 3.4 for details on using remote administration.

Table 3.5 Administration Tags in Recording 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
<domain_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, Recording 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.

3.3.5. Monitoring

The <monitoring> tag allows you to enable and configure remote monitoring of Recording Service. See Section 3.5.

Table 3.6 Monitoring Tags in Recording 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: 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
<domain_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.

3.3.6. Storage

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

Table 3.7 Storage Tags in Recording Service’s Configuration File

Tags within <storage>	Description	Multiplicity
<sqlite>	Enables storing data in a SQLite database file. See Section 3.3.6.1.	0..1
<plugin>	Enables storing data in an external library that you specify. Attributes plugin_name: Name of the plug-in that creates a storage plugin object. This name shall refer to a registered storage plug-in. See Section 10.5 for details on how the options of how to register plugins). See Section 3.3.6.2 for more about using this tag. See Section 3.6.4 for a tutorial on plugging in custom storage.	0..1
<flush_period>	Defined as a duration (seconds and nanoseconds), <flush_period> represents the rate at which user-data samples will be written to disk. When this tag is present, Recording Service will work in a purely periodic fashion. If no remote flush() command is received, data will be written to disk only when this period elapses. This tag cannot be used at the same time as the <enable_buffering_mode> tag. Default: no default. If not set, Recording Service will work in a purely reactive way.	0..1
<enable_buffering_mode>	When set to true, Recording Service will run in buffering mode. This mode is a listening-only mode and will not output data to disk automatically. Instead, Recording Service will wait continously for remote flush() commands to trigger the storage to disk (see Section 3.4.5 for more information about the remote flush command). Recording Service will buffer samples using the caches in the DataReaders it creates, so it is important that the size of the caches is controlled so memory doesn’t grow indefinitely. The size can be controlled by controlling the size of the queue (see Section 3.1.4) or by ensuring that the rate at which flush remote commands are sent matches the sample rate. The general recommendation is to define a buffer size for all Topics and Topic Groups in the configuration. This tag cannot be used at the same time as the <flush_period> tag. This feature requires remote administration to be enabled. If remote administration isn’t enabled in the configuration, Recording Service will enable it automatically. Default: false (service will start in normal operation mode).	0..1
<instance_indexing>	When this setting is enabled, Recording Service will keep an internal index about instances and their values. It will also store this instance to disk once Recording Service shuts down. This can affect the recording performance. However, Replay Service startup time will be improved when the Instance History Replay setting is enabled (see Section 4.3.9). If this setting is not enabled, Replay will build the indexes while starting up, delaying the startup process. Indexing can also be done offline, see Section 8. See Section 3.3.6.3 for more details on instance indexing configuration.	0..1

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

Table 3.8 SQLite Tags in Recording Service’s Configuration File

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.3.6.1.1.	0..1
<file>	File to write to. Default: rti_recorder_default	0..1
<file_suffix>	Allows you to add a suffix to the end of a filename.	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: 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
<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 PRAGMA JOURNAL_MODE = WAL; to this configuration setting. More information about SQLite’s WAL mode can be found here. 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: PRAGMA SYNCHRONOUS = OFF; PRAGMA JOURNAL_MODE = MEMORY;	0..1

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

Table 3.9 Fileset Tags in Recording Service’s Configuration File

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: Autonumeric. Format: %auto:M-N%. This parameter describes an integer that auto-increments every time Recording Service starts. The numeric sequence is restarted when Recording Service is manually shut down and restarted. M must be lower than N; together they define a numeric range, both inclusive. N can be omitted (%auto:M%), resulting in an unlimited sequence of numbers starting at M. Example: <execution_dir_expression> test_run_%auto:0-3% </execution_dir_expression> This example will create directories named test_run_0, test_run_1, test_run_2, and test_run_3. Timestamp. Format: %ts%. This parameter will take the current timestamp in the system (the time represented as number of seconds since Epoch). Time. Format: %T%. Current time expressed in ISO 8601 time format (THHMMSS). Example: T145502 This parameter uses the strftime() parameter %T. Short date. Format: %F%. Short date in YYYY-MM-DD format. Example: 2001-08-23. This parameter uses the strftime() parameter %F. Date and time. Format: %c%. Date and time representation, locale-dependent. This parameter is based on the strftime() parameter %c but we use the time expressed in ISO 8601 format (THHMMSS). Example: Thu Aug 23 T145502 2001 Note: Using parameters, Recording Service will check if the possible execution directories exist before overwriting any directory. If the execution directories exist, Recording Service’s behavior will be affected by the value of the <overwrite_policy_kind> tag. If <overwrite_policy_kind> is set to OVERWRITE, Recording Service will overwrite the first directory. Otherwise, Recording Service will not delete any of the old directories and will just exit. Using no parameters will yield the same execution directory every time the service is started. In this case, if the directory already contains database files, they may be overwritten (see the <overwrite> tag). Default: %ts% (current timestamp number since Epoch).	0..1
<filename_expression>	Once Recording Service knows the exact directory in which to put the database files, it will use this parameter to determine the name(s) of the user data file(s) to be created. Right before the recording starts and every time Recording Service has to change its current file to a new one, it will use this parameterisable expression to generate the next file’s name. This setting accepts text and any combination of the following parameters: Autonumeric. Format: %auto:M-N%. This parameter describes an integer that auto-increments every time Recording Service is started. However, the numeric sequence is restarted with every execution of the Recording Service application. M must be lower than N; together M and N define a numeric range, both inclusive. N may be omitted (%auto:M%), resulting in an unlimited sequence of numbers starting at M. Example: <filename_expression> test_files_%auto:0-2%.db </filename_expression> This will create files named test_files_0.db, test_files_1.db, and test_files_2.db. When a rollover event occurs, Recording Service will either create one of these files, or overwrite the next file in the sequence. When Recording Service is restarted, this will start over with overwriting test_files_0.db. Timestamp. Format: %ts%. This parameter will take the current timestamp in the system (the time represented as number of seconds since Epoch). Time. Format: %T%. Current time expressed in ISO 8601 time format (THHMMSS). Example: T145502. This parameter uses the strftime() parameter %T. Short date. Format: %F%. Short date in YYYY-MM-DD format. Example: 2001-08-23. This parameter uses the strftime() parameter %F. Note: This parameter will not vary in 24 hours, so use with caution in combination with the rollover time limit feature (time limit should be greater than 1 day; otherwise, you may overwrite the same file continously). Date and time. Format: %c%. Date and time representation, locale-dependent. This parameter is based on the strftime() parameter %c but we use the time expressed in ISO 8601 format (THHMMSS). Example: Thu Aug 23 T145502 2001 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%.db (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.3.6.1.2.	0..1

3.3.6.1.2. 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>cdr_recording</workspace_dir>
                <execution_dir_expression></execution_dir_expression>
                <!-- Files will be numbered 0-9. -->
                <filename_expression>file_rollover_%auto:0-9%.db</filename_expression>
                <rollover>
                    <enabled>true</enabled>
                    <!-- Rollovers have been enabled, but the first one won't happen -->
                    <!-- until the local time passes 11:30. After that, they will -->
                    <!-- happen when one of two conditions is met first: -->
                    <time_limit start_time="11:30:00">
                        <!-- (1) When five seconds pass since the latest rollover -->
                        <seconds>5</seconds>
                    </time_limit>
                    <!-- (2) When the current recording file size reaches 256KB -->
                    <file_size_limit unit="KILOBYTES">256</file_size_limit>
                </rollover>
            </fileset>
        </sqlite>
    </storage>
</recording_service>

Table 3.10 Rollover Tags in Recording Service’s Configuration File

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. Attributes: unit: (Optional) The unit in which the size is expressed. The following values are allowed (Default: KILOBYTES): BYTES KILOBYTES MEGABYTES GIGABYTES	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>. Attributes: start_time: The time to do the first rollover. After that, rollover will be done when the time_limit or file_size_limit is reached.	0..1

3.3.6.2. Plugin

Table 3.11 Storage plugin Tag in the Configuration File

Tags within <plugin>	Description	Multiplicity
<property>	Name/value pairs of properties to pass to a storage plugin. Example: <property> <value> <element> <name>Name</name> <value>Value</value> </element> </value> </property>	0 or 1

3.3.6.3. Instance Indexing

Table 3.12 Instance Indexing Tag in the Configuration File

Tags within <instance_indexing>	Description	Multiplicity
<enabled>	Set this to true to enable instance indexing. It’s recommended to enable instance indexing only when Replay Service is going to use Instance History Replay mode. You can also perform instance indexing offline, see Section 8. Default: false.	0 or 1
<timestamps>	The type of timestamp (reception, source or both) to use when building the instance history index. The options are: RECEPTION: Create the index based on the time the DDS sample was received by the DataReader. SOURCE: Create the index based on the time the DDS sample was written by the DataWriter. BOTH: Create the index based on both the source timestamp and the reception timestamp. Default: RECEPTION.	0 or 1

3.3.7. DomainParticipant

Table 3.13 DomainParticipant Tags in Recording Service’s Configuration File

Tags within <domain_participant>	Description	Multiplicity
<domain_id>	Required. DDS domain ID used for recording.	1
<domain_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. 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> Tags within this tag: <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>. Attributes: name: Name that the data type is registered with if no <registered_name> is specified. The same data type may be registered with different names. Required. type_ref: Definition of this data type. It must refer to one of the defined types in the <types> section by specifying the fully qualified name. Tags within this tag: <registered_name>: Name the data type is registered with. The same data type may be registered with different names. Not required.	0..*

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

Table 3.14 Session Tags in Recording Service’s Configuration File

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 allows you to set the mask, priority, and stack size of each thread. This setting can improve the reactiveness and scalability of the running Recording Service when there are multiple Topics and Topic Groups associated with the same session. Example: <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 record. Attributes: name: The name of the Topic to record. This name is also used when monitoring and administering each Topic. participant_ref: A DomainParticipant to use when recording this Topic. If the parent <session> specifies a default_participant_ref, this attribute is optional. See Section 3.3.10.	0..*
<topic_group>	Specifies a group of Topics to record. Attributes: name: The name of the Topic group. This name is also used when monitoring and administering each Topic group. participant_ref: Specifies a DomainParticipant to use when recording this topic group. If the parent <session> specifies a default_participant_ref, this attribute is optional. See Section 3.3.9.	0..*

3.3.9. Topic Group

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

Table 3.15 Topic Group Tags in Recording Service’s Configuration File

Tags within <topic_group>	Description	Multiplicity
<allow_topic_name_filter>	A regular expression (fnmatch) describing which Topics are allowed to be recorded. You may use a comma-separated list to specify more than one filter. Example: <topic_group name="RecordAll"> <allow_topic_name_filter>CONTROL_*,DATA_*</allow_topic_name_filter> </topic_group>	0..1
<deny_topic_name_filter>	A regular expression (fnmatch) describing which Topics are not allowed to be recorded. This tag is applied after the allow_topic_name_filter tag. You may use a comma-separated list to specify more than one filter.	0..1
<allow_type_name_filter>	A regular expression (fnmatch) describing the names of data types that are allowed to be recorded. You may use a comma-separated list to specify more than one filter.	0..1
<deny_type_name_filter>	A regular expression (fnmatch) describing the names of data types that are not allowed to be recorded. This tag is applied after the allow_type_name_filter tag. You may use a comma-separated list to specify more than one filter.	0..1
<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 &lt; and &gt; as shown in the example below. Example: <topic_group name="RecordAll"> <content_filter> <!-- Data will only be recorded when x is greater than 100 --> <expression>x &gt; 100</expression> </content_filter> </topic_group>	0..1

3.3.10. Topic

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

Table 3.16 Topic Tags in Recording Service’s Configuration File

Tags within <topic>	Description	Multiplicity
<topic_name>	The name of the DDS topic to be recorded. If this tag is not present, the name attribute of the <topic> will be used. Note: we recommend using this tag to define the topic name. There may be characters that cause the XML validation to fail if they are part of the topic name attribute. Also, the ‘/’ character and ‘::’ separator may cause Recorder to fail when found in the topic name attribute.	0..1
<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: Data Transformation Tutorials Attributes: plugin_name: The name of the plugin to load, qualified by the plugin library name. Example: <dds> <plugin_library name="RecordTransformations"> <transformation_plugin name="ModifyTestID"> <create_function>ModifyTestID_create</create_function> <dll>modify_test_id_library</dll> </transformation_plugin> </plugin_library> <!-- ... --> <recording_service> <!-- ... --> <topic name="TestTopic"> <transformation plugin_name="RecordTransformations::ModifyTestID" /> </topic> </recording_service> </dds>	0..1
<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. Example of how to set a content filter expression: <topic_group name="RecordAll"> <content_filter> <!-- Data will only be recorded when x is greater than 100 --> <expression>x &gt; 100</expression> </content_filter> </topic_group>	0..1

3.3.11. Support for RTI FlatData and Zero Copy Transfer Over Shared Memory

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

Warning

Recording Service cannot replay data recorded with RTI FlatData™ and Zero Copy. For further information about this constraint, see the Support for RTI FlatData and Zero Copy Transfer Over Shared Memory section in the RTI Routing Service User’s Manual.

Recording Service can work with RTI FlatData and Zero Copy transfer over shared memory for discovered types and types declared in the XML configuration. If the types are declared in XML, they must be properly annotated and then registered in each DomainParticipant. You can use each of these features separately or together.

For further information about these features, see Sending Large Data in the RTI Connext Core Libraries User’s Manual.

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

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

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

    <recording_service name="FlatDataWithZeroCopy">

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

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

</dds>

3.3.12. Plugins

All the pluggable components specific to Recording Service are configured within the <plugin_library> tag. Table 3.17 describes the available tags.

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

Table 3.17 Configuration tags for plug-in libraries

Tags within <plugin_library>	Description	Multiplicity
<storage_plugin>	Specifies a C/C++ Storage plug-in. See Table 10.18 and Section 3.3.6.	0..*
<transformation_plugin>	Specifies a C/C++ Transformation plug-in. See Table 10.18 and Section 3.3.10.	0..*

3.3.13. Enabling Distributed Logger

Distributed Logger is included in Connext, but it is not supported on all platforms; see the RTI Connext Core Libraries Platform Notes to see which platforms 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.3.14. Support for Security Plugins

Recording Service supports configuring and using Security Plugins. To configure Recording Service securely, you need to configure the appropriate QoS settings in the XML configuration. For more information, see the RTI Security Plugins User’s Manual.

3.3.14.1. Example: Configuring a Recorder Instance using Security

The following example in XML demonstrates how to configure Recording Service to load and use the Security Plugins. The example assumes a path where the user has created the necessary security artifacts (such as permissions files, certificates, and certificate authorities). This path is represented by the SECURITY_ARTIFACTS_PATH environment variable.

Note

The SECURITY_ARTIFACTS_PATH environment variable must include the file: prefix to make sure paths are properly loaded by the Security Plugins.

<dds>
    <qos_library name="SecureQosLibrary">
        <qos_profile name="SecureParticipantQos">
            <domain_participant_qos>
                <property>
                    <value>
                        <element>
                            <name>com.rti.serv.load_plugin</name>
                            <value>com.rti.serv.secure</value>
                        </element>
                        <element>
                            <name>com.rti.serv.secure.library</name>
                            <value>nddssecurity</value>
                        </element>
                        <element>
                            <name>com.rti.serv.secure.create_function</name>
                            <value>RTI_Security_PluginSuite_create</value>
                        </element>
                        <element>
                            <name>dds.sec.auth.identity_ca</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/ecdsa01/ca/ecdsa01RootCaCert.pem</value>
                        </element>
                        <element>
                            <name>dds.sec.auth.identity_certificate</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/ecdsa01/identities/ecdsa01RecordingServiceCert.pem</value>
                        </element>
                        <element>
                            <name>dds.sec.auth.private_key</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/ecdsa01/identities/ecdsa01RecordingServiceKey.pem</value>
                        </element>
                        <element>
                            <name>dds.sec.access.permissions_ca</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/ecdsa01/ca/ecdsa01RootCaCert.pem</value>
                        </element>
                        <element>
                            <name>dds.sec.access.governance</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/signed_Governance.p7s</value>
                        </element>
                        <element>
                            <name>dds.sec.access.permissions</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/signed_PermissionsA.p7s</value>
                        </element>
                    </value>
                </property>
            </domain_participant_qos>
        </qos_profile>
    </qos_library>

    ...

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

        <!--  Top-level domain settings -->
        <domain_participant name="Participant0">
            <!-- Domain Participant in Domain 0 is secured -->
            <domain_id>0</domain_id>
                <domain_participant_qos base_name="SecureQosLibrary::SecureParticipantQos" />
            </participant>
        </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>
            </topic_group>
        </session>
    </recording_service>

</dds>

The above XML example configures a Topic Group that records all data (except RTI topics) from a secured DomainParticipant. The security settings are encapsulated in a QoS Profile called SecureParticipantQos. When secured data reaches the secured endpoint, the Recording Service instance performs all security operations that will be incorporated in the cleartext sample moving into storage. In the current version of the default storage plugins, storage is unsecure.

3.3.14.2. Example: Configuring Recording Service to use a Certificate Revocation List (CRL)

Recording Service can remove a DomainParticipant from the system when its certificate has been revoked. Use Security Plugins to specify a CRL (certificate revocation list) file to track via the authentication.crl property; when the files_poll_interval property is configured in Security Plugins, Recording Service can banish revoked participants by checking the CRL file periodically. For more information, see Properties for Configuring Authentication in the RTI Security Plugins User’s Manual. The following example XML configuration file uses a CRL file to enable Recording Service to remove participants with revoked certificates.

<dds>
    <qos_library name="SecureQosLibrary">
        <qos_profile name="SecureParticipantQos">
            <domain_participant_qos>
                <property>
                    <value>
                        <element>
                            <name>com.rti.serv.load_plugin</name>
                            <value>com.rti.serv.secure</value>
                        </element>
                        <element>
                            <name>com.rti.serv.secure.library</name>
                            <value>nddssecurity</value>
                        </element>
                        <element>
                            <name>com.rti.serv.secure.create_function</name>
                            <value>RTI_Security_PluginSuite_create</value>
                        </element>
                        <element>
                            <name>dds.sec.auth.identity_ca</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/ecdsa01/ca/ecdsa01RootCaCert.pem</value>
                        </element>
                        <element>
                            <name>dds.sec.auth.identity_certificate</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/ecdsa01/identities/ecdsa01RecordingServiceCert.pem</value>
                        </element>
                        <element>
                            <name>dds.sec.auth.private_key</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/ecdsa01/identities/ecdsa01RecordingServiceKey.pem</value>
                        </element>
                        <element>
                            <name>dds.sec.access.permissions_ca</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/ecdsa01/ca/ecdsa01RootCaCert.pem</value>
                        </element>
                        <element>
                            <name>dds.sec.access.governance</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/signed_Governance.p7s</value>
                        </element>
                        <element>
                            <name>dds.sec.access.permissions</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/signed_PermissionsA.p7s</value>
                        </element>
                    </value>
                </property>
            </domain_participant_qos>
        </qos_profile>
        <qos_profile name="SecureParticipantQosWithCrl" base_name="SecureQosLibrary::SecureParticipantQos">
            <domain_participant_qos>
                <property>
                    <value>
                        <element>
                            <name>com.rti.serv.secure.authentication.crl</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/RecordingServiceRevoked.crl</value>
                        </element>
                        <element>
                            <name>com.rti.serv.secure.files_poll_interval</name>
                            <value>1</value>
                        </element>
                    </value>
                </property>
            </domain_participant_qos>
        </qos_profile>
    </qos_library>

    ...

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

        <!--  Top-level domain settings -->
        <domain_participant name="Participant0">
            <!-- Domain Participant in Domain 0 is secured and tracks a CRL file -->
            <domain_id>0</domain_id>
                <domain_participant_qos base_name="SecureQosLibrary::SecureParticipantQosWithCrl" />
            </participant>
        </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>
            </topic_group>
        </session>
    </recording_service>

</dds>

The above configuration in Recording Service reads the CRL file $SECURITY_ARTIFACTS_PATH/RecordingServiceRevoked.crl. In addition, the files_poll_interval element instructs the service to track the file for changes so that participants can be removed dynamically. In this example, the polling of the file happens every 1s.

Note

If the poll period is zero, Recording Service will not track the file continuously.

3.3.14.3. Example: Configuring Recording Service for Dynamic Certificate Renewal

Recording Service can dynamically renew its certificate if it was revoked or it expired. Use Security Plugins to specify a periodic check of the certificate file; when the files_poll_interval property is configured in Security Plugins, Recording Service reloads the certificate if the certificate file changes. For more information, see Properties for Configuring Authentication in the RTI Security Plugins User’s Manual.

The following example XML configuration file defines a 1s period for checking the certificate file for changes.

<dds>
    <qos_library name="SecureQosLibrary">
        <qos_profile name="SecureParticipantQos">
            <domain_participant_qos>
                <property>
                    <value>
                        <element>
                            <name>com.rti.serv.load_plugin</name>
                            <value>com.rti.serv.secure</value>
                        </element>
                        <element>
                            <name>com.rti.serv.secure.library</name>
                            <value>nddssecurity</value>
                        </element>
                        <element>
                            <name>com.rti.serv.secure.create_function</name>
                            <value>RTI_Security_PluginSuite_create</value>
                        </element>
                        <element>
                            <name>dds.sec.auth.identity_ca</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/ecdsa01/ca/ecdsa01RootCaCert.pem</value>
                        </element>
                        <element>
                            <name>dds.sec.auth.identity_certificate</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/ecdsa01/identities/ecdsa01RecordingServiceCert.pem</value>
                        </element>
                        <element>
                            <name>dds.sec.auth.private_key</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/ecdsa01/identities/ecdsa01RecordingServiceKey.pem</value>
                        </element>
                        <element>
                            <name>dds.sec.access.permissions_ca</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/ecdsa01/ca/ecdsa01RootCaCert.pem</value>
                        </element>
                        <element>
                            <name>dds.sec.access.governance</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/signed_Governance.p7s</value>
                        </element>
                        <element>
                            <name>dds.sec.access.permissions</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/signed_PermissionsA.p7s</value>
                        </element>
                    </value>
                </property>
            </domain_participant_qos>
        </qos_profile>
        <qos_profile name="SecureParticipantQosDynamicCert" base_name="SecureQosLibrary::SecureParticipantQos">
            <domain_participant_qos>
                <property>
                    <value>
                        <element>
                            <name>com.rti.serv.secure.files_poll_interval</name>
                            <value>1</value>
                        </element>
                    </value>
                </property>
            </domain_participant_qos>
        </qos_profile>
    </qos_library>

    ...

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

        <!--  Top-level domain settings -->
        <domain_participant name="Participant0">
            <!-- Domain Participant in Domain 0 is secured and tracks a CRL file -->
            <domain_id>0</domain_id>
                <domain_participant_qos base_name="SecureQosLibrary::SecureParticipantQosDynamicCert" />
            </participant>
        </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>
            </topic_group>
        </session>
    </recording_service>

</dds>

The above configuration in Recording Service checks the DomainParticipant certificate file $SECURITY_ARTIFACTS_PATH/ecdsa01/identities/ecdsa01RecordingServiceCert.pem for changes every 1s.

Note

If the poll period is zero, Recording Service will not track the file continuously.

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

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