5. Monitoring

This section provides documentation on Routing Service remote monitoring.

Note

Routing Service monitoring is based on the Monitoring Distribution Platform described in Section 11.3. We recommend that you read Section 11.3 before using Routing Service monitoring.

5.1. Overview

5.1.1. Enabling Service Monitoring

By default, monitoring is disabled in Routing Service. To enable monitoring you can use the <monitoring> tag (see Section 3.5.1) or the -remoteMonitoringDomainId command-line parameter, which enables remote monitoring and sets the domain ID for data publication (see Section 2.1).

5.1.2. Monitoring Types

The available Keyed Resource classes and their types that can be present in the distribution monitoring topics are listed in Table 5.1. The complete type relationship is shown in Figure 5.1.

Table 5.1 Routing Service Keyed Resources

Keyed Resource Class	Config	Event	Periodic
Service	ServiceConfig	ServiceEvent	ServicePeriodic
DomainRoute	DomainRouteConfig	DomainRouteEvent	DomainRoutePeriodic
Session	SessionConfig	SessionEvent	SessionPeriodic
AutoRoute/AutoTopicRoute	AutoRouteConfig	AutoRouteEvent	AutoRoutePeriodic
Route/TopicRoute	RouteConfig	RouteEvent	RoutePeriodic
Input	InputConfig	InputEvent	InputPeriodic
Output	OutputConfig	OutputEvent	OutputPeriodic

Figure 5.1 Keyed Resource Types for Routing Service monitoring

All the type definitions for Routing Service monitoring information are in [NDDSHOME]/resource/idl/ServiceCommon.idl and [NDDSHOME]/resource/idl/RoutingServiceMonitoring.idl.

Routing Service creates a DataWriter for each distribution Topic. All DataWriters are created from a single Publisher, which is created from a dedicated DomainParticipant. See Section 3.5.1 for details on configuring the QoS for these entities.

5.2. Monitoring Metrics Reference

This section provides a reference to all the monitoring metrics Routing Service distributes, organized by service resource class.

5.2.1. Service

Listing 5.1 Routing Service Types

            @mutable @nested
            struct ServiceConfig : Service::Monitoring::EntityConfig {
                BoundedString application_name;
                Service::Monitoring::ResourceGuid application_guid;
                @optional Service::Monitoring::HostConfig host;
                @optional Service::Monitoring::ProcessConfig process;
            };

            @mutable @nested
            struct ServiceEvent : Service::Monitoring::EntityEvent {
            };
            
            @mutable @nested
            struct ServicePeriodic {
                @optional Service::Monitoring::HostPeriodic host;
                @optional Service::Monitoring::ProcessPeriodic process;
            };

Table 5.2 ServiceConfig

Field Name	Description
Inherited fields from EntityConfig	See Table 11.13.
application_name	Name of the Routing Service instance. The application name is provided through: appName command-line option when run as executable. ServiceProperty::application_name field when run as a library.
application_guid	GUID of the Routing Service instance. Unique across all service instances.
host	See Table 11.9.
process	See Table 11.11.

---

Table 5.3 ServiceEvent

Field Name	Description
Inherited fields from EntityEvent	See Table 11.14.

---

Table 5.4 ServicePeriodic

Field Name	Description
host	See Table 11.10.
process	See Table 11.12.

5.2.2. DomainRoute

Listing 5.2 DataReader Types

            @mutable @nested
            struct ConnectionConfigInfo {
                BoundedString name;                
                AdapterClassKind class;
                BoundedString plugin_name;
                XmlString configuration;
            };
            @mutable @nested
            struct ConnectionEventInfo {
                BoundedString name;
                @optional Service::BuiltinTopicKey participant_key;
            };

            @mutable @nested
            struct DomainRouteConfig : Service::Monitoring::EntityConfig {
                @optional sequence<ConnectionConfigInfo> connections;
            };

            @mutable @nested
            struct DomainRouteEvent : Service::Monitoring::EntityEvent {
                @optional sequence<ConnectionEventInfo> connections;
            };

            @mutable @nested
            struct DomainRoutePeriodic {
                @optional Service::Monitoring::StatisticVariable in_samples_per_sec;
                @optional Service::Monitoring::StatisticVariable in_bytes_per_sec;
                @optional Service::Monitoring::StatisticVariable out_samples_per_sec;
                @optional Service::Monitoring::StatisticVariable out_bytes_per_sec;
                @optional Service::Monitoring::StatisticVariable latency_millisec;
            };

Table 5.5 DomainRouteConfig

Field Name	Description
Inherited fields from EntityConfig	See Table 11.13.
connections	Sequence of ConnectionInfo objects, one for each Connection inside the DataReader. See Table 5.6.

Table 5.6 ConnectionInfo

Field Name	Description
name	Name of the Connection instance, as specified in the name attribute of the corresponding configuration tag.
class	Indicates the adapter class as AdapterClassKind: DDS_ADAPTER_CLASS: The Connection object is a DDS adapter connection, hence it corresponds to a <participant> element. GENERIC_ADAPTER_CLASS: The Connection object is a custom, generic adapter connection, hence it corresponds to a <connection> element.
plugin_name	Name of the adapter plugin as specified in the plugin_name attribute of the corresponding configuraiton tag. For the DDS adapter, this field has the constant value of rti.routingservice.adapters.dds.
configuration	String representation of the XML configuration of the object.

---

Table 5.7 DomainRouteEvent

Field Name	Description
Inherited fields from EntityEvent	See Table 11.14.

---

Table 5.8 DomainRoutePeriodic

Field Name	Description
in_samples_per_sec	Statistic variable that provides information about the input samples per second as an aggregation of the same metric across the contained Sessions.
in_bytes_per_sec	Statistic variable that provides information about the input bytes per second as an aggregation of the same metric across the contained Sessions.
output_samples_per_sec	Statistic variable that provides information about the output samples per second as an aggregation of the same metric across the contained Sessions.
output_bytes_per_sec	Statistic variable that provides information about the output bytes per second as an aggregation of the same metric across the contained Sessions.
latency_millisec	Statistic variable that provides information about the latency in milliseconds as an aggregation of the same metric across the contained Sessions.

5.2.3. Session

Listing 5.3 Session Types

            @mutable @nested
            struct SessionConfig : Service::Monitoring::EntityConfig {
            };

            @mutable @nested
            struct SessionEvent : Service::Monitoring::EntityEvent {
            };

            @mutable @nested
            struct SessionPeriodic {
                @optional Service::Monitoring::StatisticVariable in_samples_per_sec;
                @optional Service::Monitoring::StatisticVariable in_bytes_per_sec;
                @optional Service::Monitoring::StatisticVariable out_samples_per_sec;
                @optional Service::Monitoring::StatisticVariable out_bytes_per_sec;
                @optional Service::Monitoring::StatisticVariable latency_millisec;
            };

Table 5.9 SessionConfig

Field Name	Description
Inherited fields from EntityConfig	See Table 11.13.

---

Table 5.10 SessionEvent

Field Name	Description
Inherited fields from EntityEvent	See Table 11.14.

---

Table 5.11 SessionPeriodic

Field Name	Description
in_samples_per_sec	Statistic variable that provides information about the input samples per second as an aggregation of the same metric across the contained Routes/TopicRoutes.
in_bytes_per_sec	Statistic variable that provides information about the input bytes per second as an aggregation of the same metric across the contained Routes/TopicRoutes.
output_samples_per_sec	Statistic variable that provides information about the output samples per second as an aggregation of the same metric across the contained Routes/TopicRoutes.
output_bytes_per_sec	Statistic variable that provides information about the output bytes per second as an aggregation of the same metric across the contained Routes/TopicRoutes.
latency_millisec	Statistic variable that provides information about the latency in milliseconds as an aggregation of the same metric across the contained Routes/TopicRoutes.

5.2.4. AutoRoute

Listing 5.4 AutoRoute/AutoTopicRoute Types

            @mutable @nested
            struct AutoRouteStreamPortInfo {
                XmlString configuration;
            };

            @mutable @nested
            struct AutoRouteConfig : Service::Monitoring::EntityConfig {
                @optional AutoRouteStreamPortInfo input;
                @optional AutoRouteStreamPortInfo output;
            };

            @mutable @nested
            struct AutoRouteEvent : Service::Monitoring::EntityEvent {
            };

            @mutable @nested
            struct AutoRoutePeriodic  {
                @optional Service::Monitoring::StatisticVariable in_samples_per_sec;
                @optional Service::Monitoring::StatisticVariable in_bytes_per_sec;
                @optional Service::Monitoring::StatisticVariable out_samples_per_sec;
                @optional Service::Monitoring::StatisticVariable out_bytes_per_sec;
                @optional Service::Monitoring::StatisticVariable latency_millisec;
                int64 route_count;
            };

Table 5.12 AutoRouteConfig

Field Name	Description
Inherited fields from EntityConfig	See Table 11.13.
input	See Table 5.13.
output	See Table 5.13.

Table 5.13 AutoRouteStreamPortInfo

Field Name	Description
configuration	String representation of the XML configuration of the object.

---

Table 5.14 AutoRouteEvent

Field Name	Description
Inherited fields from EntityEvent	See Table 11.14.

---

Table 5.15 AutoRoutePeriodic

Field Name	Description
in_samples_per_sec	Statistic variable that provides information about the input samples per second as an aggregation of the same metric across all current Routes/TopicRoutes created from this AutoRoute/AutoTopicRoute.
in_bytes_per_sec	Statistic variable that provides information about the input bytes per second as an aggregation of the same metric across all current Routes/TopicRoutes created from this AutoRoute/AutoTopicRoute.
output_samples_per_sec	Statistic variable that provides information about the output samples per second as an aggregation of the same metric across all current Routes/TopicRoutes created from this AutoRoute/AutoTopicRoute.
output_bytes_per_sec	Statistic variable that provides information about the output bytes per second as an aggregation of the same metric across all current Routes/TopicRoutes created from this AutoRoute/AutoTopicRoute.
latency_millisec	Statistic variable that provides information about the latency in milliseconds as an aggregation of the same metric across all current Routes/TopicRoutes created from this AutoRoute/AutoTopicRoute.
route_count	Current number of Routes/TopicRoutes created from this AutoRoute/AutoTopicRoute.

5.2.5. Route

Listing 5.5 Route/TopicRoute Types

            @mutable @nested
            struct RouteConfig : Service::Monitoring::EntityConfig {
                @optional Service::Monitoring::ResourceGuid auto_route_guid;
            };

            @mutable @nested
            struct RouteEvent : Service::Monitoring::EntityEvent {
            };

            @mutable @nested
            struct RoutePeriodic {
                @optional Service::Monitoring::StatisticVariable in_samples_per_sec;
                @optional Service::Monitoring::StatisticVariable in_bytes_per_sec;
                @optional Service::Monitoring::StatisticVariable out_samples_per_sec;
                @optional Service::Monitoring::StatisticVariable out_bytes_per_sec;
                @optional Service::Monitoring::StatisticVariable latency_millisec;
            };

Table 5.16 RouteConfig

Field Name	Description
Inherited fields from EntityConfig	See Table 11.13.
auto_route_guid	GUID of the AutoRoute/AutoTopicRoute from which this Route/TopicRoute was created. This field is set to zero for standalone routes.

---

Table 5.17 RouteEvent

Field Name	Description
Inherited fields from EntityEvent	See Table 11.14.

---

Table 5.18 RoutePeriodic

Field Name	Description
in_samples_per_sec	Statistic variable that provides information about the input samples per second as an aggregation of the same metric across its contained Inputs.
in_bytes_per_sec	Statistic variable that provides information about the input bytes per second as an aggregation of the same metric across its contained Inputs.
output_samples_per_sec	Statistic variable that provides information about the output samples per second as an aggregation of the same metric across its contained Outputs.
output_bytes_per_sec	Statistic variable that provides information about the output bytes per second as an aggregation of the same metric across its contained Outputs.
latency_millisec	Statistic variable that provides information about the latency in milliseconds for the route. The latency in a route refers to the total time elapsed during the forwarding of a sample, which includes reading, processing, and writing.
route_count	Current number of Routes/TopicRoutes created from this AutoRoute/AutoTopicRoute.

5.2.6. Input/Output

Listing 5.6 Input/Output Types

            @mutable @nested
            struct TransformationInfo {
                BoundedString plugin_name;
                XmlString configuration;
            };

            @mutable @nested
            struct StreamPortConfig : Service::Monitoring::EntityConfig {
                BoundedString stream_name;
                BoundedString registered_type_name;
                BoundedString connection_name;
                @optional TransformationInfo transformation;
            };

            @mutable @nested
            struct StreamPortEvent : Service::Monitoring::EntityEvent{
                @optional Service::BuiltinTopicKey endpoint_key;
            };

            @mutable @nested
            struct StreamPortPeriodic {
                @optional Service::Monitoring::StatisticVariable samples_per_sec;
                @optional Service::Monitoring::StatisticVariable bytes_per_sec;
            };

            /* 
             * Input
             */
            @mutable @nested
            struct InputConfig : StreamPortConfig {
            };

            @mutable @nested
            struct InputEvent: StreamPortEvent {
            };

            @mutable @nested
            struct InputPeriodic : StreamPortPeriodic {
            };

            /*
             * Output
             */
            @mutable @nested
            struct OutputConfig : StreamPortConfig {
            };

            @mutable @nested
            struct OutputEvent: StreamPortEvent {
            };

            @mutable @nested
            struct OutputPeriodic : StreamPortPeriodic {
            };

Table 5.19 InputConfig and OutputConfig

Field Name	Description
Inherited fields from EntityConfig	See Table 11.13.
stream_name	Input/output stream name as specified in the configuration. For DDS Inputs/Outputs, this value matches the underlying Topic name.
registered_type_name	Input/Output registered type name. This is the name used to register the type of the input/output stream.
connection_name	Name of the Connection from which the Input/Output is created. The value of this field can be used to determine the adapter plugin (DDS or generic) from which the underlying StreamReader/StreamWriter are created.
transformation	Optional field. If present, it provides information about the installed Transformation. See Table 5.20. For Inputs, this field will never be present.

Table 5.20 TransformationInfo

Field Name	Description
plugin_name	Name of the adapter plugin as specified in the plugin_name attribute of the corresponding configuration tag.
configuration	String representation of the XML configuration of the object.

---

Table 5.21 InputEvent and OutputEvent

Field Name	Description
Inherited fields from EntityEvent	See Table 11.14.

---

Table 5.22 InputPeriodic and OutputPeriodic

Field Name	Description
samples_per_sec	Statistic variable that provides information about the samples per second provided by this input/output: If the resource is Input, this field provides the value of the samples returned by the underlying StreamReader::read() operation. If the resource is Output, this field provides the value of the samples provided to the underlying StreamWriter::write() operation.
bytes_per_sec [1]	Statistic variable that provides information about the bytes per second provided by this input/output. The bytes refer only to the serialized samples, excluding protocol headers (RTPS, UDP, etc).

[1]	The throughput measured in bytes can only be computed if the samples are DynamicData samples. If not, only the throughput, measured in samples per second, is available. This statement applies to all the statistic variables described in this chapter that measure throughput in bytes per second.