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
_images/RouterMonitoringTypes.png

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.