.. include:: ../../../recorder.4.0/srcDoc/vars.rst .. _section-usage: .. _section-usage-executable: .. _section-record_usage: Usage ===== This section explains how to run |RECS| from a command line. In particular, it describes: - How to Start |RECS| (:numref:`section-starting-recording-service`) - How to Stop |RECS| (:numref:`section-stopping-recording-service`) - |RECS| command-line parameters (:numref:`section-recording-service-command-line-parameters`) |RECS| can also be deployed as a native library linked into your application on select architectures. For details on using |RECS| as a library, see :numref:`section-recording-service-library`. .. _section-starting-recording-service: Starting Recording Service -------------------------- |RECS| 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 |RECS| with a default configuration, enter: .. code-block:: bash rtirecordingservice This command will run |RECS| indefinitely until you stop it. You can run |RECS| using the command-line parameters defined below. *Recording Service* is pre-loaded with a builtin configuration that has default settings. See :numref:`section-builtin-config-recording-service`. .. 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. .. _section-stopping-recording-service: Stopping Recording Service -------------------------- To stop |RECS|, press Ctrl-c. |RECS| 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 |RECS|. 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:: |RECS| Command-Line Parameters :name: RecordingServiceHelp :widths: 38 62 :header-rows: 1 :class: longtable * - Parameter - Description * - -appName - Application name used to identify this execution for remote administration and to name the *Connext DDS* participant. * - -cfgFile - Semicolon-separated list of configuration file paths. |br| **Default:** unspecified * - -cfgName - Configuration name used to find a ```` matching tag in the configuration file. * - -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 |RECS| 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 * - -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. * - -help - Shows this help. * - -heapSnapshotDir - Output directory where the heap monitoring snapshots are dumped. The filename format is: |br| RTI_heap___.log * - -heapSnapshotPeriod - Period at which heap monitoring snapshots are dumped. Enables heap monitoring if > 0. |br| **Default:** 0 (disabled) * - -logFormat - A mask to configure the format of the log messages for both |RECS| 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 - Maximum number of thread-specific objects that can be created. |br| **Default**: 1024. * - -remoteAdministrationDomainId - Enables remote administration and sets the domain ID for communication. |br| **Default**: Remote administration is not enabled. * - -remoteMonitoringDomainId - Enables remote monitoring and sets the domain ID for status publication. |br| **Default**: Remote monitoring is not enabled. * - -verbosity [:] - Controls what type of messages are logged. |br| is the verbosity level for the service logs and 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. .. _section-recording-service-operation-mode: Controlling Recording Service's Operation Mode ---------------------------------------------- |RECS| can operate in different modes, regarding when data are written into disk. In standard operation mode, |RECS| 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 settings for Sessions (see :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. In flush mode, you can define a flush period (see :numref:`section-record-config-sqlite-tag` for more information on how to enable it). When a flush period is defined, |RECS| 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 in the storage configuration of the service (see :numref:`section-record-config-sqlite-tag`). Unlike the other modes above, when operating in buffering mode, |RECS| 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 |RECS| 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**: |RECS| will still write DDS discovery information automatically, even if buffering mode is enabled. This is done to ensure compatibility with |REPS| and *Converter*, by making sure no discovery samples are missing in the database files. |REPS| and *Converter* rely on this information to be able to function properly. In between reception of `flush` commands, |RECS| 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 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 |RECS| 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:: |RECS| 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 |RECS|'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 |RECS| 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_connext_users_man_up_5_s:`History QoS Policy ` - :link_connext_users_man_up_5_s:`Resource Limits QoS Policy ` - :link_connext_users_man_up_5_s:`Reader Resource Limits QoS Policy ` Operating System Daemon ======================= See generic instructions in :ref:`section-Common-Config-Deamon`.