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.

3.3.1. Builtin Configuration of Recording Service

Recording Service is pre-configured with a builtin configuration. See Section 3.3.14 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.

Top-Level tags in Recording Service's Configuration File

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:

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.

Tags used to configure a |RECS| instance

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>output_dir</workspace_dir>
                <execution_dir_expression></execution_dir_expression>
                <!-- Rollover file when the size hits 50 KB.  Files will
                     be numbered 0-9. -->
                <filename_expression>file_rollover_%auto:0-9%.db
                </filename_expression>
                <rollover>
                    <enabled>true</enabled>
                    <file_size_limit unit="KILOBYTES">50</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:

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.

To enable Recording Service to work with RTI FlatData and Zero-copy transfer over shared memory, you will need to manually define the type in the XML configuration with the proper annotations, and then register this type manually in each DomainParticipant. You can use each of these capabilities separately or together.

For further information about these capabilities, see the Sending Large Data section in the RTI Connext 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 DDS but it is not supported on all platforms; see the RTI Connext DDS Core Libraries Platform Notes for the set of platforms that support Distributed Logger.

When you enable Distributed Logger, the Service will publish its log messages to Connext DDS. Then you can use RTI Admin Console to visualize the log message data. Since the data is provided in a topic, you can also use rtiddsspy or even write your own visualization tool.

To enable Distributed Logger, use the tag <distributed_logger> within <adminstration>. For example:

<recording_service name="RecordAll">
      <administration>
            ...
            <distributed_logger>
                <enabled>true</enabled>
            </distributed_logger>
        </administration>
        ...
</recording_service>

For more details, see Enabling Distributed Logger in RTI Services, in the RTI Connext DDS Core Libraries User’s Manual.

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