The RnR Service can be controlled and monitored using a DDS topic API. All topics are in a separate DDS partition called RecordAndReplay.
Name | Type | Purpose |
---|---|---|
rr_scenario | RnR::Command | Controlling the Record and Replay service |
rr_scenario_v2 | RnR_V2::Command | Controlling the Record and Replay service (version 2) |
rr_scenarioStatus | RnR::ScenarioStatus | Monitoring status of scenarios |
rr_serviceStatus | RnR::ServiceStatus | Monitoring status of services |
rr_storageStatus | RnR::StorageStatus | Monitoring status of storages |
rr_storageStatistics | RnR::StorageStatistics | Monitoring data-characteristics of storages |
The following table shows the topic QoS parameters that deviate from the default DDS topic QoS, for the topics used by the Record and Replay Service.
Policy | Scenario Topic | Status + Statistics Topics |
---|---|---|
DurabilityQosPolicy | PERSISTENT | TRANSIENT |
DurabilityServiceQosPolicy => HistoryQosPolicy | KEEP_ALL | KEEP_LAST (with DEPTH=1) |
ReliabilityQosPolicy | RELIABLE | RELIABLE |
HistoryQosPolicy | KEEP_ALL | KEEP_LAST (with DEPTH=1) |
This enables readers and writers to use the copy_from_topic_qos() operations or the USE_TOPIC_QOS convenience macro to create a reader or writer that is compatible with the topics created by the service. Furthermore the status topic writers use a KEEP_ALL history QoS so readers can get a full overview of all status updates instead of only the last state. The scenario readers are created with a VOLATILE durability so they are also able to read samples produced by a VOLATILE writer in addition to TRANSIENT and PERSISTENT writers.
The corresponding IDL code can be found in the RnR Topic API specification.
Command Topic
The command type, used by the rr_scenario and rr_scenario_v2 topics, contains a union that allows the command kind to be set. Depending on the command kind, certain members are available that apply only to a specific type of command.
The following command kinds can be set when creating a command:
There are a number of common properties that are shared by all commands:
Optionally one or more conditions can be attached to a command. The command is only processed when all conditions are met.
Currently only one kind of condition is supported: the
time-stamp condition. Future extensions will add other kinds
of conditions which is the reason why the API supports attaching
multiple conditions to a command.
Some kinds of commands are used to control the running state of a scenario: the start, stop and suspend commands.
These all have a single member.
The name of the target scenario to control.
Do not confuse this with scenarioName, which is the name
of the scenario that will process the command.
Config commands are used to modify the runtime configuration of a RnR service.
A config command can be used to add a storage to the service or modify properties of an existing storage. Storages can also be configured in the OpenSplice configuration file, but config commands provide the opportunity to create and configure storages dynamically.
A single config command can apply to multiple storages, if the config sequence consists of multiple elements. The key of the KeyValue object should always be Storage.
The value for Storage configuration data is a string describing the storage in XML notation. The format of this XML string is identical to the XML used in the configuration file (created by the OpenSplice configuration tool).
An example:
command {
scenarioName = “MyScenario”,
rnrId = “MyService”,
conditions = NULL,
kind = CONFIG_COMMAND,
config[0].keyval = “Storage”,
config[0].sValue = “<Storage name='MyStorage'>
<rr_storageAttrXML>
<filename>my-storage.dat</filename>
</rr_storageAttrXML>
<Statistics enabled=”true” publish_interval=”30”/>
</Storage>”
};
When a config command is issued for an existing storage, the storage properties are modified accordingly.
This command is used to add interest to record certain DDS data.
Mandatory properties:
The name of the storage in which the data has to be stored. If the storage cannot be resolved the command is ignored.
Available storages can be determined by subscribing to the StorageStatus topic.
This command mirrors the add record command and is used to remove record interest from a storage.
Mandatory properties:
This command is similar to a record command but adds interest to replay data to the Record and Replay service.
Mandatory properties:
The name of the storage from which the data will be replayed. If the storage cannot be resolved the command is ignored.
Available storages can be determined by subscribing to the StorageStatus topic.
Optional properties:
A sequence of transformations, applied to each sample upon replay. By default, no transformations are applied. Note that samples first have to match interest-expression and time-range before any transformations are evaluated. The transformations sequence consists of KeyValue elements. A specific type of transformation is selected by choosing a specific key. Multiple transformations of the same kind can be used in the same sequence. The value is a string describing the new value. The transformation can be applied conditionally by using a ‘:’ (colon) character to separate original and replacement values in the value-string. Note that the original value needs to be an exact match, wildcards or expressions are not supported. The supported transformations types are listed in the table.
Key | Description |
---|---|
partition | Partition in which the sample is replayed |
deadline_period | Deadline QoS policy |
latency_period | Latency budget QoS policy |
ownership_strength | Ownership strength QoS policy (applies only to samples written with exclusive ownership-kind QoS policy) |
transport_priority | Transport priority QoS policy |
lifespan_period | Lifespan QoS policy |
Transformations that involve a period can be expressed in either DDS-compliant duration (sec.nanosec) or more human-friendly floating-point (sec.millis) formats. Floating-point values are interpreted locale-independent, using a period ‘.’ (decimal point) character. Partition transformations are supported for partition names consisting of alphanumeric and special characters ‘-’, ‘/’ and ‘_’.
This command mirrors the ADD_REPLAY_COMMAND, except for the properties useOriginalTimestamps and skipToFirstSample, which change the replay behaviour and are not applicable to the remove replay command.
The command is used to remove replay interest from a storage. Mandatory members of the add replay command are also mandatory in the remove replay command.
Mandatory properties:
The interest expressions describing the replay interest to remove.
Note that these interest expressions need to match those used
previously in an add replay command.
Optional properties:
This command can be used to clear a storage. When recording samples to an existing storage, by defauilt the data is appended. If instead the required behaviour is to overwrite the storage, the truncate command can be used to remove the data recorded to the storage during previous sessions.
Using this command the replay speed of a storage can be manipulated. The replay speed affects the delay between replayed samples. For example, a replay speed of 2 will cut the delay in half: samples will be replayed twice as fast as originally recorded.
Mandatory properties:
A floating-point value containing the new replay-speed. The following values have a special meaning:
-1: Maximum speed; delays between samples are skipped and the samples from the storage are inserted into DDS as fast as possible.
1 : Replay samples with the same timing characteristics as when originally recorded.
0 : Pause the storage; no samples are replayed until the speed is increased.
The default replay speed is 1 (samples are replayed with the same timing characteristics as when originally recorded).
To monitor the status of various components of the service, applications can take a subscription on the status topics published by the Record and Replay service.
Status Topics
Status topics are state-based, meaning that they are only published when a state changes. Readers normally only need to read the latest sample of an instance to get the latest (current) state. However, a reader can also be created with a KEEP_ALL history if it needs to be aware of all states even when state changes occur in quick succession.
Each Record and Replay service publishes its own state in the rr_serviceStatus topic. The topic uses the ServiceStatus type, which has the following members:
The current state of the service. The following states are possible:
INITIALISING: The service is started and initialising, but not yet able to process commands. During initialization the service processes configuration parameters and joins the DDS domain.
OPERATIONAL: The service is successfully initialized and ready to accept commands.
TERMINATING: The service is shutting down.
TERMINATED: The service is detached from the DDS domain and stopped.
The service status topic reflects the life-cycle of a Record and Replay service. It is published when the state field changes, which normally occurs only during service startup or shutdown (i.e. when OpenSplice is started or stopped).
The service publishes the state of each known scenario in the rr_scenarioStatus topic. This topic, using the ScenarioStatus type, contains the following members:
The scenarioName combined with the rnrId define an instance of the scenario status topic, so each update can be related to the service and scenario responsible for that status.
The current state of the scenario. The following states are possible:
RUNNING: The scenario is running and actively processing commands.
SUSPENDED: A scenario enters the suspended state after a suspend-scenario command is processed for the scenario. While suspended, the scenario doesn’t process any new commands.
STOPPED: The scenario was stopped and removed from the service.
The service publishes the state of each known storage in the rr_storageStatus topic. This topic, using the StorageStatus type, contains the following members:
The storageName combined with the rnrId define an instance of the storage status topic and can be used to relate an update of the topic to the service and storage responsible.
The current state of the storage. A storage may have the following states:
READY: This is the initial state after configuring a storage, when the configuration is deemed valid. It means the storage was defined and available when configured. In the case of a pre-existing storage, properties are available in the status update for this state.
OPEN: The storage is in use by one or more scenarios identified by the scenarioNames sequence in the status update for this state.
ERROR: The storage is invalid and cannot be used. This can either mean an error in the storage configuration or an issue related to resources claimed by the storage. Most notably in case of an XMLstorage, the service may not have permission to open a file that is part of the storage.
Note that it is not currently possible to determine the reason for
an ERROR state directly from the status update, but a descriptive
message is written to the OpenSplice log files. A future release will
make this message available in the status update.
OUTOFRESOURCES: When a storage is used for recording, it may run out of resources.
CLOSED: A storage may enter the closed state for two reasons. Usually it is closed when all record and/or replay interest has been detached from the storage. This occurs when all scenarios that were using the storage are stopped. If the storage is used for replay, it may also be closed when all data in the storage has been evaluated and the end of the storage was reached.
Properties of the data contained in a storage. The following properties are available per recorded topic:
Note that properties are not updated while a storage is open, they are
only updated when the state of a storage changes.
Unlike the other status topics, the storage status is determined by more than just the state field. The attributes and sequence of scenario names are also part of the state. Therefore storage status updates not only occur when the state field itself is changed but also when the attributes are changed or when a scenario starts (or stops) using the storage.
The Record and Replay service can optionally maintain runtime statistics regarding the data that is recorded to and/or replayed from a storage. These statistics can be published in the rr_storageStatistics topic.
Storage Statistics Topic
Statistics are enabled per storage. Publication in the rr_storageStatistics topic is optional and can be managed by the publish_interval attribute of the statistics configuration element.
The statistics values can be reset by setting the reset attribute in the XML configuration string of the storage statistics.
The API contains a number of utility types used as members in one or more topics. These helper types are described in this section.
Miscellaneous Types
The KeyValue type is a generic key:value container. It is used for the transformations sequence in add and remove replay commands and as the config sequence of a config command, to send configuration values to a Record and Replay service and/or scenario.
Depending on the KeyValue kind, a value can take on a number of representations: boolean, string, long or float.
The TimeRange type can be used to limit the selection of data in a replay command. Interest expressions select data based on partition and topic names, time-ranges filter this selection based on record timestamps.
The DDS::Time_t type is used to express a timestamp. A range is defined by a start and an end timestamp.