4.4. Remote Administration¶

This section provides documentation on Replay Service remote administration. A control client (such as RTI Admin Console) can use this interface to remotely control a Replay Service.

Note

Replay Service remote administration is based on the RTI Remote Administration Platform described in Section 10.3. Please refer to that manual for a detailed discussion on the workings of remote administration in Replay Service.

Below you will find an API reference for all the supported operations.

4.4.1. Enabling Remote Administration¶

By default, remote administration is disabled in Replay Service.

To enable remote administration you can use the <administration> XML tag (see Section 4.3) or the -remoteAdministrationDomainId command-line parameter (see Section 4.1). Both of these methods enable remote administration and set the domain ID for remote communication.

4.4.2. Available Service Resources¶

Table 4.20 lists the public resources specific to Replay Service. Each resource identifier is expressed as a hierarchical sequence of identifiers, including parent and target resources. (See Section 10.2.2 for details.)

In the table below, the elements (rs), and (st) refer to the name of an entity of the corresponding class as specified in the configuration in the name attribute. For example, in the following configuration:

<replay_service name="MyReplay">...</replay_service>

The resource identifier is:

/replay_service/MyReplay

In the table, the resource identifier is written as /replay_service/(rs), where (rs) is the service name. This nomenclature is used in the table to give you an idea of the structure of the resource identifiers. For actual (example) resource identifier names, see the example section that follows.

Table 4.20 Resources and Their Identifiers in *Replay Service*¶
Resource	Resource Identifier
Replay Service	/replay_service/(rs)

4.4.2.1. Example¶

This example shows you how to address a resource of each possible resource class in Replay Service.

Replay Service

Entity with name “MyReplay”:

<replay_service name="MyReplay">...</replay_service>

Resource identifier:

/replay_services/MyReplay

4.4.3. Remote API Overview¶

Table 4.21 Remote Interface Overview¶
Resource	Operation	Description
ReplayService	DELETE /replay_services/(rs)	Shuts down a running Replay Service
	UPDATE /replay_services/(rs)/state	Sets a Replay Service state
	UPDATE /replay_services/(rs)/playback/rate	Change the rate of the replay
	UPDATE /replay_services/(rs)/playback/current_timestamp	Jump to a specific timestamp and continue the replay
	UPDATE /replay_services/(rs)/playback/current_tag	Jump to a specific timestamp tag and continue the replay
	GET /replay_services/(rs)/playback:state	Provide the current Replay Service state. It will allow us to detect when Replay Service hit a breakpoint.
	UPDATE /replay_services/(rs)/playback:add_breakpoint	Add a new breakpoint
	UPDATE /replay_services/(rs)/playback:remove_breakpoint	Remove an existing breakpoint
	UPDATE /replay_services/(rs)/playback:goto_breakpoint	Jump to a specific breakpoint and stop the replay
	UPDATE /replay_services/(rs)/playback:next_breakpoint	Jump to the next breakpoint and stop the replay
	UPDATE /replay_services/(rs)/playback:continue	Continue the replay leaving the current breakpoint
	UPDATE /replay_services/(rs)/playback:next_slice	Continue the replay for a slice of period

4.4.4. Replay Service¶

DELETE /replay_services/(rs)

Operation shutdown

Causes Replay Service to shutdown.

UPDATE /replay_services/(rs)/state

Operation set_state

See Set Resource State (Section 10.3.3.4).

Valid requested states:

STARTED

STOPPED

PAUSED

RUNNING

Example
To pause a replay service with the name “MyReplay”:
Request Field

Value
command_action

UPDATE

resource_identifier

/replay_services/MyReplay/state

octet_body

to_cdr_buffer(RTI::Service::EntityStateKind::PAUSED)

UPDATE /replay_services/(rs)/playback/rate

Operation set_rate

This operation will cause Replay Service to change its rate.

Request body

The new rate of the replay.

UPDATE /replay_services/(rs)/playback/current_timestamp

Operation current_timestamp

This operation will cause Replay Service to change its current timestamp, modifying the replay location backward or forward in time.

It will affect the whole service, meaning that all StreamReaders will be affected by it.

Example

To change the current timestamp in a replay service named “MyReplay”:
Request Field

Value
command_action

UPDATE

resource_identifier

/replay_services/MyReplay/playback/current_timestamp
octet_body
RTI::RecordingService::TimestampHolder timestamp_holder;
timestamp_holder.timestamp_nanos(1600635588280996383);
std::vector<char> timestamp_holder_buffer;

dds::topic::topic_type_support<RTI::RecordingService::TimestampHolder>
    ::to_cdr_buffer(
        timestamp_holder_buffer,
        timestamp_holder);

UPDATE /replay_services/(rs)/playback/current_tag

Operation current_tag

This operation will cause Replay Service to change its current timestamp, modifying the replay location backward or forward in time. The replay will jump to the timestamp of the selected timestamp tag.

It will affect the whole service, meaning that all StreamReaders will be affected by it.

Request body

Tag name of a specific recorded timestamp tag.

GET /replay_services/(rs)/playback:state

Operation get_state

This operation will provide the current debug state of the Replay Service related to the debug mode. It will allow you to detect when Replay Service stop in a breakpoint

Valid provided states:

BREAKPOINT

WORKING

Request body

Empty.

Reply body

octet_body: CDR representation of the DebugStatus.

UPDATE /replay_services/(rs)/playback:add_breakpoint

Operation add_breakpoint

This operation will create a new breakpoint. Replay Service will only accept as proper breakpoint those which timestamp is not out of the recorded timestamp period.

Also, we can use a recorded timestamp tag to create a breakpoint with it.

Examples

To create a new breakpoint in a replay service named “MyReplay”:

Request Field

Value

command_action

UPDATE

resource_identifier

/replay_services/MyReplay/playback:add_breakpoint

octet_body

RTI::RecordingService::BreakpointParams breakpoint_arguments;
::dds::core::optional<std::string> optional_label_value("breakpoint_1");
breakpoint_arguments.label(optional_label_value);
breakpoint_arguments.value().timestamp_nanos(1600635588280996383);
dds::topic::topic_type_support<RTI::RecordingService::BreakpointParams>
        ::to_cdr_buffer(
                reinterpret_cast<std::vector<char> &> (request.octet_body()),
                breakpoint_arguments);

To create a new breakpoint using a timestamp tag:

Request Field

Value

command_action

UPDATE

resource_identifier

/replay_services/MyReplay/playback:add_breakpoint

octet_body

RTI::RecordingService::BreakpointParams breakpoint_arguments;
::dds::core::optional<std::string> optional_label_value("breakpoint_tag");
breakpoint_arguments.label(optional_label_value);
breakpoint_arguments.value().tag_name("example/tag1");
dds::topic::topic_type_support<RTI::RecordingService::BreakpointParams>
        ::to_cdr_buffer(
                reinterpret_cast<std::vector<char> &> (request.octet_body()),
                breakpoint_arguments);

UPDATE /replay_services/(rs)/playback:remove_breakpoint

Operation remove_breakpoint

This operation will remove an existing breakpoint for the replay. A breakpoint can be removed by label or by timestamp.

In order to clean the complete list of breakpoints (except the default one) you can use the special character “*” as label value.

If Replay Service is hitting the breakpoint to be removed, It won’t resume the replay.

Examples

To remove the breakpoint with label “MyBreakpoint” in a replay service named “MyReplay”:

Request Field

Value

command_action

UPDATE

resource_identifier

/replay_services/MyReplay/playback:remove_breakpoint

octet_body

RTI::RecordingService::BreakpointParams breakpoint_arguments;
::dds::core::optional<std::string> optional_label_value("MyBreakpoint");
breakpoint_arguments.label(optional_label_value);
breakpoint_arguments.value().timestamp_nanos(0);
dds::topic::topic_type_support<RTI::RecordingService::BreakpointParams>
        ::to_cdr_buffer(
                reinterpret_cast<std::vector<char> &> (request.octet_body()),
                breakpoint_arguments);

UPDATE /replay_services/(rs)/playback:goto_breakpoint

Operation goto_breakpoint

This operation will cause Replay Service to jump to a specific breakpoint. You can specifie the jumping breakpoint by label or by timestamp.

It will affect the whole service, meaning that all StreamReaders will be affected by it.

-Example:

To jump to breakpoint with timestamp “1600635588280996383” in a replay service named “MyReplay”:
Request Field

Value
command_action

UPDATE

resource_identifier

/replay_services/MyReplay/playback:goto_breakpoint
octet_body
RTI::RecordingService::BreakpointParams breakpoint_arguments;
breakpoint_arguments.value().timestamp_nanos(1600635588280996383);
dds::topic::topic_type_support<RTI::RecordingService::BreakpointParams>
        ::to_cdr_buffer(
                reinterpret_cast<std::vector<char> &> (request.octet_body()),
                breakpoint_arguments);

UPDATE /replay_services/(rs)/playback:next_breakpoint

Operation next_breakpoint

This operation will cause Replay Service to jump to the next breakpoint on the list. if Replay Service was on the last breakpoint of the list It will throw an exception.

It will affect the whole service, meaning that all StreamReaders will be affected by it.

Request body

Empty.

UPDATE /replay_services/(rs)/playback:continue

Operation continue

This operation will cause Replay Service to continue the replay after it hit a breakpoint. If you do not add any CDR representation to the request, it will continue until it hits a new breakpoint or the replay end. Otherwise, this operation will continue the replay for the period of time specified by you. Replay Service has to be on BREAKPOINT state in order to make this action.

It will affect the whole service, meaning that all StreamReaders will be affected by it.

-Examples:

To continue the replay for 1 second in a replay service named “MyReplay”:
Request Field

Value
command_action

UPDATE

resource_identifier

/replay_services/MyReplay/playback:continue
octet_body
RTI::RecordingService::ContinueParams continue_arguments;
continue_arguments.value().offset(1000000000);
dds::topic::topic_type_support<RTI::RecordingService::ContinueParams>
::to_cdr_buffer(
        reinterpret_cast<std::vector<char> &> (request.octet_body()),
        continue_arguments);
To continue the replay for 2 slices periods in a replay service named “MyReplay”:
Request Field

Value
command_action

UPDATE

resource_identifier

/replay_services/MyReplay/playback:continue
octet_body
RTI::RecordingService::ContinueParams continue_arguments;
continue_arguments.value().slices(2);
dds::topic::topic_type_support<RTI::RecordingService::ContinueParams>
::to_cdr_buffer(
        reinterpret_cast<std::vector<char> &> (request.octet_body()),
        continue_arguments);

UPDATE /replay_services/(rs)/playback:next_slice

Operation next_slice

This operation will cause Replay Service to resume the replay for the duration of a slice period. Replay Service has to be on BREAKPOINT state in order to make this action.

It will affect the whole service, meaning that all StreamReaders will be affected by it.

Request body

Empty.