.. include:: ../../../router.1.0/srcDoc/vars.rst .. _section-usage: .. _section-usage-executable: .. _section-record_usage: Usage ===== This section explains how to run *Recording Service* from a command line. In particular, it describes: - How to Start *Recording Service* (:numref:`section-starting-recording-service`) - How to Stop *Recording Service* (:numref:`section-stopping-recording-service`) - *Recording Service* command-line parameters (:numref:`section-recording-service-command-line-parameters`) .. _section-starting-recording-service: Starting Recording Service -------------------------- *Recording Service* runs as a separate application. The script to run the executable is in ``/bin.`` (See :numref:`section-doc-paths` for the path to NDDSHOME.) To start *Recording Service* with a default configuration, enter: .. code-block:: bash rtirecordingservice This command will run *Recording Service* indefinitely until you stop it. You can run *Recording Service* using the command-line parameters defined below. .. note:: *Recording Service* is pre-loaded with a builtin configuration that has default settings. See :numref:`section-builtin-config-recording-service`. .. _section-stopping-recording-service: Stopping Recording Service -------------------------- To stop *Recording Service*, press Ctrl-c. *Recording Service* will perform a clean shutdown. .. _section-recording-service-command-line-parameters: 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 :numref:`section-record-config-XML-tags` for the XML elements that can be overridden with command-line parameters. .. list-table:: *Recording Service* Command-Line Parameters :name: RecordingServiceHelp :widths: 38 62 :header-rows: 1 :class: longtable * - Parameter - Description * - :litrep:`-appName ` - Application name used to identify this execution for remote administration and to name the *Connext DDS* participant. * - :litrep:`-cfgFile ` - Semicolon-separated list of configuration file paths. |br| **Default:** unspecified * - :litrep:`-cfgName` - Configuration name used to find a ```` matching tag in the configuration file. * - :litrep:`-domainIdBase ` - This value is added to the domain IDs in the ```` 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). |br| **Default:** 0 * - :litrep:`-D=` - Defines a variable that can be used as an alternate replacement for XML environment variables, specified in the form $(VAR_NAME). |br| Note that definitions in the environment take precedence over these definitions. * - :litrep:`-help` - Shows this help. * - :litrep:`-heapSnapshotDir` - Output directory where the heap monitoring snapshots are dumped. The filename format is: |br| RTI_heap___.log * - :litrep:`-heapSnapshotPeriod ` - Period at which heap monitoring snapshots are dumped. Enables heap monitoring if > 0. |br| **Default:** 0 (disabled) * - :litrep:`-logFormat ` - 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 * - :litrep:`-maxObjectsPerThread ` - Maximum number of thread-specific objects that can be created. |br| **Default**: 1024. * - :litrep:`-remoteAdministrationDomainId ` - Enables remote administration and sets the domain ID for communication. |br| **Default**: Remote administration is not enabled. * - :litrep:`-remoteMonitoringDomainId ` - Enables remote monitoring and sets the domain ID for status publication. |br| **Default**: Remote monitoring is not enabled. * - :litrep:`-verbosity [0-6]` - RTI Service verbosity - 0 - silent - 1 - exceptions (*Connext DDS* and *Recording Service*) - 2 - warnings (*Recording Service*) - 3 - information (*Recording Service*) - 4 - warnings (*Connext DDS* and *Recording Service*) - 5 - tracing (*Recording Service*) - 6 - tracing (*Connext DDS* and *Recording Service*) **Default**: 1 (exceptions) * - :litrep:`-version` - Prints the program version and exits. .. _section-recording-service-operation-mode: 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 :litrep:`` settings for Sessions (see section :numref:`section-config-session-tag` 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. You can also define a flush period (see section :numref:`section-record-config-sqlite-tag` 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 :litrep:`` in the storage configuration of the service (see section :numref:`section-record-config-sqlite-tag`). 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. 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 :litrep:`` 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. 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): .. list-table:: *Recording Service* Buffer Size Control :name: RecordingServiceBufferSize :widths: 38 38 :header-rows: 1 :class: longtable * - 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: - :link_userman_history_qos:`History QoS Policy <>` - :link_userman_resource_limits_qos:`Resource Limits QoS Policy <>` - :link_userman_reader_resource_limits_qos:`Reader Resource Limits QoS Policy <>`