.. include:: vars.rst .. _section-Monitoring: ********** Monitoring ********** This section provides documentation on |RS| remote monitoring. .. Note:: |RS| monitoring is based on the *Monitoring Distribution Platform* described in :ref:`section-Common-Mon`. We recommend that you read :ref:`section-Common-Mon` before using |RS| monitoring. .. _section-Monitoring-Ow: Overview ======== .. _section-Monitoring-Ow-EnablingMon: Enabling Service Monitoring --------------------------- By default, monitoring is disabled in |RS|. To enable monitoring you can use the ```` tag (see :ref:`section-config-routing-service`) or the ``-remoteMonitoringDomainId`` command-line parameter, which enables remote monitoring and sets the domain ID for data publication (see :ref:`section-usage-executable`). .. _section-Monitoring-Ow-DistTopics: Monitoring Types ---------------- The available *Keyed Resource* classes and their types that can be present in the distribution monitoring topics are listed in :numref:`TableRouterKeyedResources`. The complete type relationship is shown in :numref:`FigureRouterMonitoringTypes`. .. list-table:: |RS| *Keyed Resources* :name: TableRouterKeyedResources :widths: 25 25 25 25 :header-rows: 1 :class: longtable * - Keyed Resource Class - Config - Event - Periodic * - :ref:`Service ` - ``ServiceConfig`` - ``ServiceEvent`` - ``ServicePeriodic`` * - :ref:`DomainRoute ` - ``DomainRouteConfig`` - ``DomainRouteEvent`` - ``DomainRoutePeriodic`` * - :ref:`Session ` - ``SessionConfig`` - ``SessionEvent`` - ``SessionPeriodic`` * - :ref:`AutoRoute/AutoTopicRoute ` - ``AutoRouteConfig`` - ``AutoRouteEvent`` - ``AutoRoutePeriodic`` * - :ref:`Route/TopicRoute ` - ``RouteConfig`` - ``RouteEvent`` - ``RoutePeriodic`` * - :ref:`Input ` - ``InputConfig`` - ``InputEvent`` - ``InputPeriodic`` * - :ref:`Output ` - ``OutputConfig`` - ``OutputEvent`` - ``OutputPeriodic`` .. figure:: static/RouterMonitoringTypes.svg :figwidth: 90 % :name: FigureRouterMonitoringTypes :align: center Keyed Resource Types for |RS| monitoring All the type definitions for |RS| monitoring information are in ``[NDDSHOME]/resource/idl/ServiceCommon.idl`` and ``[NDDSHOME]/resource/idl/RoutingServiceMonitoring.idl``. |RS| creates a |DW| for each distribution |TOPIC|. All |DWs| are created from a single |PUB|, which is created from a dedicated |DP|. See :ref:`section-config-routing-service` for details on configuring the QoS for these entities. .. _section-Monitoring-Metrics: Monitoring Metrics Reference ============================ This section provides a reference to all the monitoring metrics |RS| distributes, organized by service resource class. .. _section-Monitoring-Metrics-Service: Service ------- .. literalinclude:: ../resource/idl/RoutingServiceMonitoring.idl :caption: |RS| Types :start-after: /* Service :end-before: /* --- Top-level .. list-table:: ``ServiceConfig`` :name: TableRouterServiceConfig :widths: 25 75 :header-rows: 1 * - Field Name - Description * - Inherited fields from ``EntityConfig`` - See :numref:`TableCommonEntityConfig`. * - application_name - Name of the |RS| 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 |RS| instance. Unique across all service instances. * - host - See :numref:`TableCommonHostConfig`. * - process - See :numref:`TableCommonProcessConfig`. .... .. list-table:: ``ServiceEvent`` :name: TableRouterServiceEvent :widths: 25 75 :header-rows: 1 * - Field Name - Description * - Inherited fields from ``EntityEvent`` - See :numref:`TableCommonEntityEvent`. .... .. list-table:: ``ServicePeriodic`` :name: TableRouterServicePeriodic :widths: 25 75 :header-rows: 1 * - Field Name - Description * - host - See :numref:`TableCommonHostPeriodic`. * - process - See :numref:`TableCommonProcessPeriodic`. .. _section-Monitoring-Metrics-DomainRoute: DomainRoute ----------- .. literalinclude:: ../resource/idl/RoutingServiceMonitoring.idl :caption: |DOMAINROUTE| Types :start-after: /* DomainRoute :end-before: /* Service .. list-table:: ``DomainRouteConfig`` :name: TableRouterDomainRouteConfig :widths: 25 75 :header-rows: 1 * - Field Name - Description * - Inherited fields from ``EntityConfig`` - See :numref:`TableCommonEntityConfig`. * - connections - Sequence of ``ConnectionInfo`` objects, one for each |CONNECTION| inside the |DOMAINROUTE|. See :numref:`TableRouterConnectionInfo`. .. list-table:: ``ConnectionInfo`` :name: TableRouterConnectionInfo :widths: 25 75 :header-rows: 1 * - 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 ```` element. - GENERIC_ADAPTER_CLASS: The |CONNECTION| object is a custom, generic adapter connection, hence it corresponds to a ```` 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. .... .. list-table:: ``DomainRouteEvent`` :name: TableRouterDomainRouteEvent :widths: 25 75 :header-rows: 1 * - Field Name - Description * - Inherited fields from ``EntityEvent`` - See :numref:`TableCommonEntityEvent`. .... .. list-table:: ``DomainRoutePeriodic`` :name: TableRouterDomainRoutePeriodic :widths: 25 75 :header-rows: 1 * - 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|. .. _section-Monitoring-Metrics-Session: Session ------- .. literalinclude:: ../resource/idl/RoutingServiceMonitoring.idl :caption: |SESSION| Types :start-after: /* Session :end-before: /* DomainRoute .. list-table:: ``SessionConfig`` :name: TableRouterSessionConfig :widths: 25 75 :header-rows: 1 * - Field Name - Description * - Inherited fields from ``EntityConfig`` - See :numref:`TableCommonEntityConfig`. .... .. list-table:: ``SessionEvent`` :name: TableRouterSessionEvent :widths: 25 75 :header-rows: 1 * - Field Name - Description * - Inherited fields from ``EntityEvent`` - See :numref:`TableCommonEntityEvent`. .... .. list-table:: ``SessionPeriodic`` :name: TableRouterSessionPeriodic :widths: 25 75 :header-rows: 1 * - 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|\/|TRs|. * - 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|\/|TRs|. * - 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|\/|TRs|. * - 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|\/|TRs|. * - latency_millisec - Statistic variable that provides information about the latency in milliseconds as an aggregation of the same metric across the contained |ROUTEs|\/|TRs|. * - thread_pool - Sequence of ``ThreadPeriodic`` objects, one for each thread of the |SESSION|'s thread pool. See :numref:`TableThreadPeriodic`. .. _section-Monitoring-Metrics-AutoRoute: AutoRoute --------- .. literalinclude:: ../resource/idl/RoutingServiceMonitoring.idl :caption: |AR|\/|ATR| Types :start-after: /* AutoRoute :end-before: /* Session .. list-table:: ``AutoRouteConfig`` :name: TableRouterAutoRouteConfig :widths: 25 75 :header-rows: 1 * - Field Name - Description * - Inherited fields from ``EntityConfig`` - See :numref:`TableCommonEntityConfig`. * - input - See :numref:`TableRouterAutoRouteStreamPortInfo`. * - output - See :numref:`TableRouterAutoRouteStreamPortInfo`. .. list-table:: ``AutoRouteStreamPortInfo`` :name: TableRouterAutoRouteStreamPortInfo :widths: 25 75 :header-rows: 1 * - Field Name - Description * - configuration - String representation of the XML configuration of the object. .... .. list-table:: ``AutoRouteEvent`` :name: TableRouterAutoRouteEvent :widths: 25 75 :header-rows: 1 * - Field Name - Description * - Inherited fields from ``EntityEvent`` - See :numref:`TableCommonEntityEvent`. .... .. list-table:: ``AutoRoutePeriodic`` :name: TableRouterAutoRoutePeriodic :widths: 25 75 :header-rows: 1 * - 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|\/|TRs| created from this |AR|\/|ATR|. * - 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|\/|TRs| created from this |AR|\/|ATR|. * - 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|\/|TRs| created from this |AR|\/|ATR|. * - 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|\/|TRs| created from this |AR|\/|ATR|. * - latency_millisec - Statistic variable that provides information about the latency in milliseconds as an aggregation of the same metric across all current |ROUTEs|\/|TRs| created from this |AR|\/|ATR|. * - route_count - Current number of |ROUTEs|\/|TRs| created from this |AR|\/|ATR|. .. _section-Monitoring-Metrics-Route: Route ----- .. literalinclude:: ../resource/idl/RoutingServiceMonitoring.idl :caption: |ROUTE|\/|TR| Types :start-after: /* Route :end-before: /* AutoRoute .. list-table:: ``RouteConfig`` :name: TableRouterRouteConfig :widths: 25 75 :header-rows: 1 * - Field Name - Description * - Inherited fields from ``EntityConfig`` - See :numref:`TableCommonEntityConfig`. * - auto_route_guid - GUID of the |AR|\/|ATR| from which this |ROUTE|\/|TR| was created. This field is set to zero for standalone routes. .... .. list-table:: ``RouteEvent`` :name: TableRouterRouteEvent :widths: 25 75 :header-rows: 1 * - Field Name - Description * - Inherited fields from ``EntityEvent`` - See :numref:`TableCommonEntityEvent`. .... .. list-table:: ``RoutePeriodic`` :name: TableRouterRoutePeriodic :widths: 25 75 :header-rows: 1 * - 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. |br| 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|\/|TRs| created from this |AR|\/|ATR|. .. _section-Monitoring-Metrics-StreamPort: Input/Output ------------ .. literalinclude:: ../resource/idl/RoutingServiceMonitoring.idl :caption: |INPUT|\/|OUTPUT| Types :start-after: /* StreamPort :end-before: /* Route .. list-table:: ``InputConfig`` and ``OutputConfig`` :name: TableRouterStreamPortConfig :widths: 25 75 :header-rows: 1 * - Field Name - Description * - Inherited fields from ``EntityConfig`` - See :numref:`TableCommonEntityConfig`. * - stream_name - Input/output stream name as specified in the configuration. |br| 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 |SR|\/|SW| are created. * - transformation - Optional field. If present, it provides information about the installed *Transformation*. See :numref:`TableRouterTransformationInfo`. |br| For |INPUTs|, this field will never be present. .. list-table:: ``TransformationInfo`` :name: TableRouterTransformationInfo :widths: 25 75 :header-rows: 1 * - 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. .... .. list-table:: ``InputEvent`` and ``OutputEvent`` :name: TableRouterStreamPortEvent :widths: 25 75 :header-rows: 1 * - Field Name - Description * - Inherited fields from ``EntityEvent`` - See :numref:`TableCommonEntityEvent`. .... .. list-table:: ``InputPeriodic`` and ``OutputPeriodic`` :name: TableRouterStreamPortPeriodic :widths: 25 75 :header-rows: 1 * - 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 [#f1]_ - Statistic variable that provides information about the bytes per second provided by this input/output. |br| The bytes refer only to the serialized samples, excluding protocol headers (RTPS, UDP, etc). .. [#f1] 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.