3.1. Usage

This section explains how to run Recording Service from a command line. In particular, it describes:

Recording Service can also be deployed as a native library linked into your application on select architectures. For details on using Recording Service as a library, see Section 3.6.3.

3.1.1. Starting Recording Service

Recording Service runs as a separate application. The script to run the executable is in <NDDSHOME>/bin. (See Section 1.3 for the path to NDDSHOME.)

To start Recording Service with a default configuration, enter:

rtirecordingservice

This command will run Recording Service indefinitely until you stop it.

You can run Recording Service using the command-line parameters defined below.

Recording Service is pre-loaded with a builtin configuration that has default settings. See Section 3.3.14.

Note

To run Recording Service on a target system (not your host development platform), you must first select the target architecture. To do so, either:

  • Set the environment variable CONNEXTDDS_ARCH to the name of the target architecture. (Do this for each command shell you will be using.)

  • Or set the variable connextdds_architecture in the file rticommon_config.[sh/bat] to the name of the target architecture. (The file is resource/scripts/rticommon_config.sh on Linux or macOS systems, resource/scripts/rticommon_config.bat on Windows systems.) If the CONNEXTDDS_ARCH environment variable is set, the architecture in this file will be ignored.

3.1.2. Stopping Recording Service

To stop Recording Service, press Ctrl-c. Recording Service will perform a clean shutdown.

3.1.3. Recording Service Command-Line Parameters

The following table describes all the command-line parameters available in Recording Service. To list the available parameters, run rtirecordingservice -help.

All command-line parameters are optional; if specified, they override the values of any corresponding settings in the loaded XML configuration. See Section 3.3.2 for the XML elements that can be overridden with command-line parameters.

Table 3.1 Recording Service Command-Line Parameters

Parameter

Description

-appName <string>

Application name used to identify this execution for remote administration and to name the Connext DDS participant.

-cfgFile <string>

Semicolon-separated list of configuration file paths.
Default: unspecified

-cfgName

Configuration name used to find a <recording_service> matching tag in the configuration file.

-domainIdBase <int>

This value is added to the domain IDs in the <domain_participant> tag in the configuration file. For example, if you set -domainIdBase to 50 and use domain IDs 0 and 1 in the configuration file, then Recording Service will use domains 50 and 51 for recording (though the recorded data will appear as though it was recorded in domains 0 and 1).
Default: 0

-D<name>=<value>

Defines a variable that can be used as an alternate replacement for XML environment variables, specified in the form $(VAR_NAME).
Note that definitions in the environment take precedence over these definitions.

-help

Shows this help.

-heapSnapshotDir

Output directory where the heap monitoring snapshots are dumped. The filename format is:
RTI_heap_<appName>_<processId>_<index>.log

-heapSnapshotPeriod <sec>

Period at which heap monitoring snapshots are dumped. Enables heap monitoring if > 0.
Default: 0 (disabled)

-logFormat <format>

A mask to configure the format of the log messages for both Recording Service and Connext DDS:

  • DEFAULT - Print message, method name, and activity context

  • TIMESTAMPED - Print message, method name, activity context, and timestamp

  • MINIMAL - Print only message number and method name

  • MAXIMAL - Print all available fields

Default: DEFAULT

-maxObjectsPerThread <int>

Maximum number of thread-specific objects that can be created.
Default: 1024.

-remoteAdministrationDomainId <int>

Enables remote administration and sets the domain ID for communication.
Default: Remote administration is not enabled.

-remoteMonitoringDomainId <int>

Enables remote monitoring and sets the domain ID for status publication.
Default: Remote monitoring is not enabled.

-verbosity <service_level>[:<dds_level>]

Controls what type of messages are logged.
<service_level> is the verbosity level for the service logs and <dds_level> is the verbosity level for the DDS logs. Both can take any of the following values:

  • SILENT

  • ERROR

  • WARN

  • LOCAL

  • REMOTE

  • ALL

Default: ERROR:ERROR

-version

Prints the program version and exits.

3.1.4. Controlling Recording Service’s Operation Mode

Recording Service can operate in different modes, regarding when data are written into disk.

In standard operation mode, Recording Service will store samples as they arrive. This is a purely reactive model. This mode is the default mode and is the best mode for scalability. To further improve performance and scalability, standard operation mode can be used in combination with the <thread_pool> settings for Sessions (see Section 3.3.8 for more information). These settings allow you to control the number of worker threads that process the data events, as well as the thread priorities, mask, etc.

In flush mode, you can define a flush period (see Section 3.3.6.1 for more information on how to enable it). When a flush period is defined, Recording Service will operate in a periodic fashion. This means that user-data samples will be written to disk only every time the flush period elapses.

The third operation mode is called buffering mode. This mode is controlled by setting the <enable_buffering_mode> in the storage configuration of the service (see Section 3.3.6.1). Unlike the other modes above, when operating in buffering mode, Recording Service will not do any writing to disk automatically. Instead, it will buffer samples in memory and wait for remote administration flush() commands to actually write them to disk.

3.1.4.1. Controlling Buffer Size in Buffering Mode

As mentioned above, there is an operation mode in Recording Service called buffering mode. This mode will not perform any automatic writing of samples to disk. Instead, this mode will wait for the reception of remote flush() commands that you send on demand.

Note: Recording Service will still write DDS discovery information automatically, even if buffering mode is enabled. This is done to ensure compatibility with Replay Service and Converter, by making sure no discovery samples are missing in the database files. Replay Service and Converter rely on this information to be able to function properly.

In between reception of flush commands, Recording Service will buffer samples in RAM memory, using the sample caches in its DataReaders. This buffering can lead to situations of unlimited memory growth. To avoid this problem, there are two options:

  • Issue remote flush commands at a rate that allows Recorder’s writing to disk to keep up with the sample read rate. This rate is complex to calculate in many scenarios; if you find that you are sending flushing commands periodically, then it’s better to just use the <flush_period> setting and operate in periodic mode.

  • Limit the size of the DataReader caches. This will allow the caches to work as a configurable, finite circular buffer with a fixed, immutable, oldest-first replacement policy. The following section explains the QoS properties used to control the DataReader’s cache.

3.1.4.2. Configuring In-Memory Buffer Size

The most important policy to work with is the History QoS policy. There are optional settings that can help improve the performance or that can affect the History QoS. Assuming that the intent is to configure Recording Service to keep a buffer of size N, the following table shows the DataReader QoS settings that should be used or are desirable (defined as optional):

Table 3.2 Recording Service Buffer Size Control

QoS Policy

Value

History.kind

KEEP_LAST

History.depth

N

(Optional) ResourceLimits.max_samples

N

(Optional) ResourceLimits.max_instances

N

(Optional) ResourceLimits.max_samples_per_instance

N

(Optional) ResourceLimits.initial_samples

N

(Optional) ResourceLimits.initial_instances

N

Setting initial samples and instances is optional but recommended for performance because setting these properties will force the DataReader queue to start with a size of N samples directly, avoiding memory allocations during Recording Service’s operation.

Another important setting to take into account is ReaderResourceLimits.max_samples_per_read. This setting defines the maximum number of samples that a single read or take operation can return in one go. This setting will interact with the size of the buffer when a flush remote command is issued. When this setting is smaller than the buffer’s size, N, then Recording Service will need to generate several writing events, until N is reached or until there are no more samples to read.

See the following sections in the RTI Connext DDS Core Libraries User’s Manual for more information on these settings:

3.2. Operating System Daemon

See generic instructions in How to Run as an Operating System Daemon.