Monitor Service Documentation (#506)

* Refs #18066: Monitor Service Documentation Signed-off-by: Mario Dominguez <[email protected]> * Refs #18066: Spelling checks Signed-off-by: Mario Dominguez <[email protected]> * Refs #18066: Added use-case scenario Signed-off-by: Mario Dominguez <[email protected]> * Refs #18066: Spelling Signed-off-by: Mario Dominguez <[email protected]> * Refs #18066: Updated according to last Design Update Signed-off-by: Mario Dominguez <[email protected]> * Refs #18066: Updated Docs to fit the Monitor Service Status Topic Design Update Signed-off-by: Mario Dominguez <[email protected]> * Refs #18066: Spelling Signed-off-by: Mario Dominguez <[email protected]> * Refs #17294: Reviewer suggestions Signed-off-by: Mario Dominguez <[email protected]> * Refs #17294: Syntax Signed-off-by: Mario Dominguez <[email protected]> * Refs #17294: Reviewer Suggestion Signed-off-by: Mario Dominguez <[email protected]> * Refs #19071: Move the Monitor Service into the Statistics Module Signed-off-by: Mario Dominguez <[email protected]> * Refs #19071: Linter Signed-off-by: Mario Dominguez <[email protected]> * Refs #19071: Correct monitor service c++ api example snippet Signed-off-by: Mario Dominguez <[email protected]> * Refs #19071: Fixes for passing doc tests Signed-off-by: Mario Dominguez <[email protected]> * Refs #18066: Rev suggestions Signed-off-by: Mario Dominguez <[email protected]> * Refs #18066: Second rev suggestions Signed-off-by: Mario Dominguez <[email protected]> * Refs #18066: nit Signed-off-by: Mario Dominguez <[email protected]> --------- Signed-off-by: Mario Dominguez <[email protected]>
eProsima · Dec 12, 2023 · ee4c9b0 · ee4c9b0
1 parent 1b6016f
commit ee4c9b0
Show file tree

Hide file tree

Showing 14 changed files with 393 additions and 2 deletions.
diff --git a/code/DDSCodeTester.cpp b/code/DDSCodeTester.cpp
@@ -647,6 +647,43 @@ void dds_domain_examples()
                 "HISTORY_LATENCY_TOPIC;ACKNACK_COUNT_TOPIC;DISCOVERY_TOPIC;PHYSICAL_DATA_TOPIC");
         //!--
     }
+    {
+        // FASTDDS_MONITOR_SERVICE_PROPERTY
+        DomainParticipantQos pqos;
+
+        // Enable Fast DDS Monitor Service through properties
+        pqos.properties().properties().emplace_back("fastdds.enable_monitor_service",
+                "true");
+
+        // Enable Fast DDS Monitor Service through statistics properties (other way)
+        pqos.properties().properties().emplace_back("fastdds.statistics",
+                "MONITOR_SERVICE_TOPIC");
+
+        DomainParticipant* participant_with_mon_srv = DomainParticipantFactory::get_instance()->create_participant(0,
+                        pqos);
+
+        //!--
+    }
+    {
+        // FASTDDS_MONITOR_SERVICE_API
+
+        DomainParticipant* participant = DomainParticipantFactory::get_instance()->create_participant(0,
+                        PARTICIPANT_QOS_DEFAULT);
+
+        // Obtain pointer to child class
+        eprosima::fastdds::statistics::dds::DomainParticipant* statistics_participant =
+                eprosima::fastdds::statistics::dds::DomainParticipant::narrow(participant);
+
+
+        // Enable Fast DDS Monitor Service through API
+        statistics_participant->enable_monitor_service();
+
+        // Disable Fast DDS Monitor Service through API
+        statistics_participant->disable_monitor_service();
+
+
+        //!--
+    }
     {
         // FASTDDS_PHYSICAL_PROPERTIES
         /* Create participant which announces default physical properties */

diff --git a/code/XMLTester.xml b/code/XMLTester.xml
@@ -2858,6 +2858,31 @@
 </participant>
 <!--><-->
 
+<!-->DDS_MONITOR_SERVICE<-->
+<!--
+<?xml version="1.0" encoding="UTF-8" ?>
+<profiles xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles">
+-->
+<participant profile_name="monitor_service_participant_xml_profile">
+    <rtps>
+        <propertiesPolicy>
+            <properties>
+                <!-- Enable Monitor Service -->
+                <property>
+                    <name>fastdds.enable_monitor_service</name>
+                    <value>true</value>
+                </property>
+                <!-- Include Monitor Service in the Fast DDS Statistics (other way to enable it) -->
+                <property>
+                    <name>fastdds.statistics</name>
+                    <value>MONITOR_SERVICE_TOPIC</value>
+                </property>
+            </properties>
+        </propertiesPolicy>
+    </rtps>
+</participant>
+<!--><-->
+
 <!-->PULL_MODE_DATAWRITER<-->
 <!--
 <?xml version="1.0" encoding="UTF-8" ?>

diff --git a/docs/03-exports/aliases-api.include b/docs/03-exports/aliases-api.include
@@ -146,6 +146,8 @@
 .. |DomainParticipant::create_topic_with_profile-api| replace:: :cpp:func:`create_topic_with_profile()<eprosima::fastdds::dds::DomainParticipant::create_topic_with_profile>`
 .. |DomainParticipant::find_topic| replace:: :cpp:func:`find_topic()<eprosima::fastdds::dds::DomainParticipant::find_topic>`
 .. |DomainParticipant::ignore_participant-api| replace:: :cpp:func:`ignore_participant()<eprosima::fastdds::dds::DomainParticipant::ignore_participant>`
+.. |DomainParticipant::enable-monitor-service-api| replace:: :cpp:func:`enable_monitor_service()<eprosima::fastdds::dds::DomainParticipant::enable_monitor_service>`
+.. |DomainParticipant::disable-monitor-service-api| replace:: :cpp:func:`disable_monitor_service()<eprosima::fastdds::dds::DomainParticipant::disable_monitor_service>`
 
 .. |DomainParticipantFactory-api| replace:: :cpp:class:`DomainParticipantFactory<eprosima::fastdds::dds::DomainParticipantFactory>`
 .. |DomainParticipantFactory::create_participant_with_profile-api| replace:: :cpp:func:`create_participant_with_profile()<eprosima::fastdds::dds::DomainParticipantFactory::create_participant_with_profile>`
@@ -986,6 +988,9 @@
 .. |STATISTICS_DATAREADER_QOS-api| replace:: :cpp:member:`STATISTICS_DATAREADER_QOS <eprosima::fastdds::statistics::dds::STATISTICS_DATAREADER_QOS>`
 .. |STATISTICS_DATAWRITER_QOS-api| replace:: :cpp:member:`STATISTICS_DATAWRITER_QOS <eprosima::fastdds::statistics::dds::STATISTICS_DATAWRITER_QOS>`
 
+.. |DDSEntityStatus-api| replace:: :cpp:class:`DDSEntityStatus <eprosima::fastdds::statistics::rtps::DDSEntityStatus>`
+.. |MonitorServiceDataReaderQos-api| replace:: :cpp:class:`MonitorServiceDataReaderQos <eprosima::fastdds::statistics::dds::MonitorServiceDataReaderQos>`
+
 .. |RTPSMessageGroup| replace:: :cpp:class:`RTPSMessageGroup <eprosima::fastrtps::rtps::RTPSMessageGroup>`
 .. |MessageReceiver| replace:: :cpp:class:`MessageReceiver <eprosima::fastrtps::rtps::MessageReceiver>`
 

diff --git a/docs/fastdds/api_reference/dds_pim/core/status/ddsentitystatus.rst b/docs/fastdds/api_reference/dds_pim/core/status/ddsentitystatus.rst
@@ -0,0 +1,10 @@
+.. _api_pim_ddsentitystatus:
+
+.. rst-class:: api-ref
+
+DDSEntityStatus
+---------------
+
+.. doxygenstruct:: eprosima::fastdds::statistics::rtps::DDSEntityStatus
+    :project: FastDDS
+    :members:
diff --git a/docs/fastdds/api_reference/dds_pim/core/status/status.rst b/docs/fastdds/api_reference/dds_pim/core/status/status.rst
@@ -4,6 +4,7 @@ Status
 .. toctree::
 
    /fastdds/api_reference/dds_pim/core/status/basestatus.rst
+   /fastdds/api_reference/dds_pim/core/status/ddsentitystatus.rst
    /fastdds/api_reference/dds_pim/core/status/deadlinemissedstatus.rst
    /fastdds/api_reference/dds_pim/core/status/incompatibleqosstatus.rst
    /fastdds/api_reference/dds_pim/core/status/inconsistenttopicstatus.rst

diff --git a/docs/fastdds/api_reference/statistics/datareader_qos.rst b/docs/fastdds/api_reference/statistics/datareader_qos.rst
@@ -11,3 +11,10 @@ DataReaderQos
 
 .. doxygenvariable:: eprosima::fastdds::statistics::dds::STATISTICS_DATAREADER_QOS
     :project: FastDDS
+
+.. doxygenclass:: eprosima::fastdds::statistics::dds::MonitorServiceDataReaderQos
+    :project: FastDDS
+    :members:
+
+.. doxygenvariable:: eprosima::fastdds::statistics::dds::MONITOR_SERVICE_DATAREADER_QOS
+    :project: FastDDS
diff --git a/docs/fastdds/statistics/includes/intro.rst b/docs/fastdds/statistics/includes/intro.rst
@@ -4,7 +4,8 @@ The collected data is published using DDS over dedicated topics using builtin Da
 *Statistics module*.
 Consequently, by default, Fast DDS does not compile this module because it may entail affecting the application's
 performance.
-Nonetheless, the Statistics module can be activated using the ``-DFASTDDS_STATISTICS=ON`` at CMake configuration step.
+Nonetheless, the Statistics module and the Monitor Service can be activated using the ``-DFASTDDS_STATISTICS=ON``
+at CMake configuration step.
 For more information about *Fast DDS* compilation, see :ref:`linux_sources` and :ref:`windows_sources`.
 
 Besides enabling the *Statistics Module* compilation, the user must enable those DataWriters that are publishing data on

diff --git a/docs/fastdds/statistics/monitor_service/intro.rst b/docs/fastdds/statistics/monitor_service/intro.rst
@@ -0,0 +1,55 @@
+.. include:: ../../../03-exports/aliases.include
+.. include:: ../../../03-exports/aliases-api.include
+
+Introduction
+============
+
+The ``Monitor Service`` targets any application implementing the subscription side of
+the :ref:`Monitor Service Status Topic <monitor_service_topics>`,
+giving the possibility of retrieving the :ref:`Monitoring Information <monitor_service_keywords>`
+of the local entities (incompatible QoS, deadlines missed,
+active connections,...).
+
+.. _monitor_service_keywords:
+
+Keywords
+^^^^^^^^
+
+* **Proxy**: An entity that acts on behalf of another entity.
+
+* **Proxy Data**: The way in which a Proxy can be described.
+
+* **Monitoring Information**: The collection of different sources of information and statuses of an entity,
+  including: the Proxy Data, incompatible QoS, connections, liveliness, deadlines missed, inconsistent
+  topics and lost sample status.
+
+Description
+^^^^^^^^^^^
+
+Enabling the service makes each |DomainParticipant| publish its local entities, each one with its related
+``Monitoring Information``.
+
+The :ref:`monitor_service` is disabled by default, as it may entail a performance cost.
+Further information on the :ref:`monitor_service` topics and how to configure it is described
+in the following sections.
+
+The :ref:`monitor_service` is available in both the :ref:`DDS Layer <dds_layer>` and :ref:`RTPS Layer <rtps_layer>`.
+
+
+.. _monitor_service_in_rtps_note:
+
+.. note::
+
+   If the service is activated within a :ref:`RTPS <rtps_layer>` context, not all the ``Monitoring Information``
+   may be published by the service.
+
+Use Cases
+^^^^^^^^^
+
+The :ref:`monitor_service` can be particularly useful in the following scenarios:
+
+*  Collecting the ``Monitoring Information`` of any local entity of a remote |DomainParticipant|
+   in order to extend the default discovery information (see :ref:`discovery`) about it.
+*  Troubleshooting issues regarding discovery or entity-matching, leveraging the information
+   of the current locators in use, for example.
+*  Recreating an entity graph of a certain domain given that all participants are able to discover each other.
diff --git a/docs/fastdds/statistics/monitor_service/monitor_service.rst b/docs/fastdds/statistics/monitor_service/monitor_service.rst
@@ -0,0 +1,19 @@
+.. include:: ../../../03-exports/aliases.include
+.. include:: ../../../03-exports/aliases-api.include
+
+.. _monitor_service:
+
+Monitor Service
+===============
+
+The *Fast DDS* Monitor Service is a feature of Fast DDS that
+grants the user the ability to collect data about the entities existing within
+a particular |domain| (i.e |DomainParticipants|, |DataReaders|, |DataWriters|)
+as well as the capability of detecting possible misconfigurations among them.
+
+.. toctree::
+    :maxdepth: 2
+
+    intro
+    monitor_service_topics
+    monitor_service_configuration
diff --git a/docs/fastdds/statistics/monitor_service/monitor_service_configuration.rst b/docs/fastdds/statistics/monitor_service/monitor_service_configuration.rst
@@ -0,0 +1,72 @@
+.. include:: ../../../03-exports/aliases.include
+.. include:: ../../../03-exports/aliases-api.include
+
+.. _monitor_service_configuration:
+
+Monitor Service Configuration
+=============================
+
+The :ref:`monitor_service` can be activated using the ``-DFASTDDS_STATISTICS=ON`` at CMake configuration step
+(for further information regarding the *Fast DDS* compilation, see :ref:`linux_sources` and :ref:`windows_sources`).
+Once the :ref:`monitor_service` feature is activated, it can be programmatically enabled in both :ref:`dds_layer` and
+:ref:`rtps_layer` through the |DomainParticipant::enable-monitor-service-api| and
+|DomainParticipant::disable-monitor-service-api| calls.
+In addition, leveraging the |PropertyPolicyQos-api| there is new ``Property`` defined
+for the purpose: ``fastdds.enable_monitor_service``.
+
+The following table depicts the different ways in which the *Monitor Service* can be enabled or disabled:
+
+.. tabs::
+
+    .. tab:: C++ API
+
+      .. literalinclude:: /../code/DDSCodeTester.cpp
+        :language: c++
+        :dedent: 8
+        :start-after: // FASTDDS_MONITOR_SERVICE_API
+        :end-before: //!
+
+    .. tab:: C++ Property
+
+      .. literalinclude:: /../code/DDSCodeTester.cpp
+        :language: c++
+        :dedent: 8
+        :start-after: // FASTDDS_MONITOR_SERVICE_PROPERTY
+        :end-before: //!
+
+    .. tab:: XML
+
+      .. literalinclude:: /../code/XMLTester.xml
+        :language: xml
+        :start-after: <!-->DDS_MONITOR_SERVICE<-->
+        :end-before: <!--><-->
+        :lines: 2-3,5-22
+        :append: </profiles>
+
+    .. tab:: Env. Variable Linux
+
+      .. code-block:: bash
+
+        export FASTDDS_STATISTICS="MONITOR_SERVICE_TOPIC"
+
+    .. tab:: Env. Variable Windows
+
+      .. code-block:: bash
+
+        set FASTDDS_STATISTICS=MONITOR_SERVICE_TOPIC
+
+Endpoints QoS
+^^^^^^^^^^^^^
+
+For any consumer application of the :ref:`monitor_service`, the following endpoint QoS
+of the :ref:`monitor_service_status_topic` DataWriter should be taken into consideration:
+
++-------------------------+-------------------------------+------------------------------------+
+|       **Endpoint**      |          **QoS**              |  **Value**                         |
++-------------------------+-------------------------------+------------------------------------+
+|  MONITOR_STATUS_WRITER  | |ReliabilityQosPolicyKind-api|||RELIABLE_RELIABILITY_QOS-api|      |
+|                         +-------------------------------+------------------------------------+
+|                         | |HistoryQosPolicyKind-api|    ||KEEP_LAST_HISTORY_QOS-api| 1       |
+|                         +-------------------------------+------------------------------------+
+|                         | |DurabilityQosPolicyKind-api| ||TRANSIENT_LOCAL_DURABILITY_QOS-api||
++-------------------------+-------------------------------+------------------------------------+