Skip to content

Commit

Permalink
Statistics module documentation (#262)
Browse files Browse the repository at this point in the history 
* Update Statistics QoS documentation (#253)

* Refs #10991: update statistics QoS documentation.

Signed-off-by: JLBuenoLopez-eProsima <[email protected]>

* Refs #10991: add reference to the constants of the recommended QoS

Signed-off-by: JLBuenoLopez-eProsima <[email protected]>

* Refs #10991: update property name

Signed-off-by: JLBuenoLopez-eProsima <[email protected]>

* Refs #10991: apply review suggestions

Signed-off-by: JLBuenoLopez-eProsima <[email protected]>

* Fast DDS Statistics Module DataWriters auto enabling (#247)

* Refs #10714: environment variable and statistics datawriters auto enabling

Signed-off-by: JLBuenoLopez-eProsima <[email protected]>

* Refs #10714: document fastdds.statistics PropertyPolicyQos

Signed-off-by: JLBuenoLopez-eProsima <[email protected]>

* Refs #10714: automatically enabled statistics datawriters use recommended QoS

Signed-off-by: JLBuenoLopez-eProsima <[email protected]>

* Refs #10714: update with implemented statistics topics

Signed-off-by: JLBuenoLopez-eProsima <[email protected]>

* Refs #10714: apply review suggestions

Signed-off-by: JLBuenoLopez-eProsima <[email protected]>

* Refs #10714: include use case as per reviewer suggestion

Signed-off-by: JLBuenoLopez-eProsima <[email protected]>

* Refs #10714: apply review suggestions

Signed-off-by: JLBuenoLopez-eProsima <[email protected]>

* Refs #10714: apply review suggestions

Signed-off-by: JLBuenoLopez-eProsima <[email protected]>
  • Loading branch information
@JLBuenoLopez
JLBuenoLopez authored Apr 28, 2021
1 parent b0b4e6c commit 346fbdf
Show file tree
Hide file tree
Showing 11 changed files with 341 additions and 11 deletions.
56 changes: 56 additions & 0 deletions code/DDSCodeTester.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,11 @@
#include <fastdds/rtps/transport/TCPv4TransportDescriptor.h>
#include <fastdds/rtps/transport/TCPv6TransportDescriptor.h>
#include <fastdds/rtps/transport/shared_mem/SharedMemTransportDescriptor.h>

#include <fastdds/statistics/dds/domain/DomainParticipant.hpp>
#include <fastdds/statistics/dds/publisher/qos/DataWriterQos.hpp>
#include <fastdds/statistics/topic_names.hpp>

#include <fastrtps/utils/IPLocator.h>

#include <sstream>
Expand Down Expand Up @@ -525,6 +530,57 @@ void dds_domain_examples()
"myLogFile.log");
//!--
}
{
// FASTDDS_STATISTICS_MODULE
DomainParticipantQos pqos;

// Activate Fast DDS Statistics module
pqos.properties().properties().emplace_back("fastdds.statistics",
"HISTORY_LATENCY_TOPIC;ACKNACK_COUNT_TOPIC;DISCOVERY_TOPIC;PHYSICAL_DATA_TOPIC");
//!--
}
{
// ENABLE_DISABLE_STATISTICS_DATAWRITER
// Create a DomainParticipant
DomainParticipant* participant =
DomainParticipantFactory::get_instance()->create_participant(0, PARTICIPANT_QOS_DEFAULT);
if (nullptr == participant)
{
// Error
return;
}

// Obtain pointer to child class
eprosima::fastdds::statistics::dds::DomainParticipant* statistics_participant =
eprosima::fastdds::statistics::dds::DomainParticipant::narrow(participant);

// Enable statistics DataWriter
if (statistics_participant->enable_statistics_datawriter(eprosima::fastdds::statistics::GAP_COUNT_TOPIC,
eprosima::fastdds::statistics::dds::STATISTICS_DATAWRITER_QOS) != ReturnCode_t::RETCODE_OK);
{
// Error
return;
}

// Use the DomainParticipant to communicate
// (...)

// Disable statistics DataWriter
if (statistics_participant->disable_statistics_datawriter(eprosima::fastdds::statistics::GAP_COUNT_TOPIC) !=
ReturnCode_t::RETCODE_OK)
{
// Error
return;
}

// Delete DomainParticipant
if (DomainParticipantFactory::get_instance()->delete_participant(participant) != ReturnCode_t::RETCODE_OK)
{
// Error
return;
}
//!--
}

{
// PULL_MODE_DATAWRITER
Expand Down
16 changes: 16 additions & 0 deletions code/XMLTester.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2933,6 +2933,22 @@
</data_writer>
<!--><-->

<!-->FASTDDS_STATISTICS_MODULE<-->
<participant profile_name="statistics_domainparticipant_conf_xml_profile">
<rtps>
<propertiesPolicy>
<properties>
<!-- Activate Fast DDS Statistics Module -->
<property>
<name>fastdds.statistics</name>
<value>HISTORY_LATENCY_TOPIC;ACKNACK_COUNT_TOPIC;DISCOVERY_TOPIC;PHYSICAL_DATA_TOPIC</value>
</property>
</properties>
</propertiesPolicy>
</rtps>
</participant>
<!--><-->

<!-->
</profiles>
<-->
Expand Down
3 changes: 3 additions & 0 deletions docs/02-formalia/titlepage.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,9 @@ Main Features
pluggable security at three levels: authentication of remote participants, access control of entities and encryption
of data.

* :ref:`Statistics Module. <statistics>` *eProsima Fast DDS* can be configured to gather and provide information
about the data being exchanged by the user application.

* **Throughput controllers.** We support user-configurable throughput controllers, that can be used to limit the amount
of data to be sent under certain conditions.

Expand Down
5 changes: 5 additions & 0 deletions docs/03-exports/aliases-api.include
View file
Original file line number Diff line number Diff line change
Expand Up @@ -190,9 +190,11 @@
.. |SubscriberQos::SubscriberQos-api| replace:: :cpp:func:`SubscriberQos()<eprosima::fastdds::dds::SubscriberQos::SubscriberQos>`
.. |Subscribers-api| replace:: :cpp:class:`Subscribers <eprosima::fastdds::dds::Subscriber>`
.. |Topic-api| replace:: :cpp:class:`Topic <eprosima::fastdds::dds::Topic>`
.. |Topics-api| replace:: :cpp:class:`Topics <eprosima::fastdds::dds::Topic>`
.. |Topic::set_qos-api| replace:: :cpp:func:`Topic::set_qos()<eprosima::fastdds::dds::Topic::set_qos>`
.. |Topic::get_inconsistent_topic_status-api| replace:: :cpp:func:`get_inconsistent_topic_status()<eprosima::fastdds::dds::Topic::get_inconsistent_topic_status>`
.. |TopicDataType-api| replace:: :cpp:class:`TopicDataType<eprosima::fastdds::dds::TopicDataType>`
.. |TopicDataTypes-api| replace:: :cpp:class:`TopicDataTypes<eprosima::fastdds::dds::TopicDataType>`
.. |TopicDataType::getKey-api| replace:: :cpp:func:`getKey()<eprosima::fastdds::dds::TopicDataType::getKey>`
.. |TopicDataType::is_bounded-api| replace:: :cpp:func:`is_bounded()<eprosima::fastdds::dds::TopicDataType::is_bounded>`
.. |TopicDataType::m_isGetKeyDefined-api| replace:: :cpp:member:`m_isGetKeyDefined<eprosima::fastdds::dds::TopicDataType::m_isGetKeyDefined>`
Expand Down Expand Up @@ -778,5 +780,8 @@
.. |disable_statistics_datawriter| replace:: :cpp:func:`disable_statistics_datawriter() <eprosima::fastdds::statistics::dds::DomainParticipant::disable_statistics_datawriter>`
.. |statistics_narrow| replace:: :cpp:func:`narrow() <eprosima::fastdds::statistics::dds::DomainParticipant::narrow>`

.. |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>`

.. |RTPSMessageGroup| replace:: :cpp:class:`RTPSMessageGroup <eprosima::fastrtps::rtps::RTPSMessageGroup>`
.. |MessageReceiver| replace:: :cpp:class:`MessageReceiver <eprosima::fastrtps::rtps::MessageReceiver>`
38 changes: 38 additions & 0 deletions docs/fastdds/env_vars/env_vars.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -108,3 +108,41 @@ The following example shows how to set the address of two remote discovery serve
The *server*'s GUID prefixes generated by the CLI comply with the following schema:
``44.53.<server-id-in-hex>.5f.45.50.52.4f.53.49.4d.41``.
This prefix schema has been chosen for its ASCII translation: ``DS<id_in_hex>_EPROSIMA``.

.. _env_vars_fastdds_statistics:

``FASTDDS_STATISTICS``
----------------------

.. warning::
The environment variable is only used in the case where the CMake option `FASTDDS_STATISTICS` has been enabled.
In any other case, the environment variable has no effect.
Please, refer to :ref:`cmake_options` for more information.

Setting this variable configures the :ref:`DomainParticipant<dds_layer_domainParticipant>` to enable the statistics
DataWriters which topics are contained in the list set in this environment variable.
The elements of the list should be separated by semicolons and match the
:ref:`statistics topic name aliases<statistics_topic_names>`.

For example, to enable the statistics DataWriters that report the latency measurements, the environment variable should
be set as follows:

+----------------------------------------------------------------------------+
| **Linux** |
+----------------------------------------------------------------------------+
| .. code-block:: bash |
| |
| export FASTDDS_STATISTICS=HISTORY_LATENCY_TOPIC;NETWORK_LATENCY_TOPIC |
+----------------------------------------------------------------------------+
| **Windows** |
+----------------------------------------------------------------------------+
| .. code-block:: bash |
| |
| set FASTDDS_STATISTICS=HISTORY_LATENCY_TOPIC;NETWORK_LATENCY_TOPIC |
+----------------------------------------------------------------------------+

.. important::
This environment variable can be used together with the XML profiles
(for more information please refer to :ref:`auto_enabling_statistics_datawriters`).
The statistics DataWriters that will be enabled is the union between the ones specified in the XML file (if loaded)
and the ones stated in the environment variable (if set).
36 changes: 34 additions & 2 deletions docs/fastdds/property_policies/non_consolidated_qos.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -79,8 +79,40 @@ Unique network flows QoS Policy
.. warning::
This section is still under work.

.. _property_policies_statistics:

Statistics Module Settings
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. warning::
This section is still under work.
Fast DDS Statistics Module uses the :ref:`propertypolicyqos` to indicate the statistics DataWriters that are enabled
automatically (see :ref:`auto_enabling_statistics_datawriters`).
In this case, the property value is a semicolon separated list containing the
:ref:`statistics topic name aliases<statistics_topic_names>` of those DataWriters that the user wants to enable.

.. list-table::
:header-rows: 1
:align: left

* - PropertyPolicyQos name
- PropertyPolicyQos value
- Default value
* - ``"fastdds.statistics"``
- Semicolon separated list of :ref:`statistics topic name aliases<statistics_topic_names>`
- ``""``

+----------------------------------------------------------------------------------------------------------------------+
| **C++** |
+----------------------------------------------------------------------------------------------------------------------+
| .. literalinclude:: /../code/DDSCodeTester.cpp |
| :language: c++ |
| :start-after: // FASTDDS_STATISTICS_MODULE |
| :end-before: //!-- |
| :dedent: 8 |
+----------------------------------------------------------------------------------------------------------------------+
| **XML** |
+----------------------------------------------------------------------------------------------------------------------+
| .. literalinclude:: /../code/XMLTester.xml |
| :language: xml |
| :start-after: <!-->FASTDDS_STATISTICS_MODULE<--> |
| :end-before: <!--><--> |
+----------------------------------------------------------------------------------------------------------------------+
103 changes: 94 additions & 9 deletions docs/fastdds/statistics/dds_layer/domainParticipant.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,6 @@ For this purpose, *Fast DDS Statistics module* exposes an extended DDS |Statisti
Enable statistics DataWriters
-----------------------------

.. warning::
This method will be implemented in future releases. For the moment it always returns ``RETCODE_UNSUPPORTED``.

Statistics DataWriters are enabled using the method |enable_statistics_datawriter|.
This method requires as parameters:

Expand All @@ -27,9 +24,6 @@ This method requires as parameters:
Disable statistics DataWriters
------------------------------

.. warning::
This method will be implemented in future releases. For the moment it always returns ``RETCODE_UNSUPPORTED``.

Statistics DataWriters are disabled using the method |disable_statistics_datawriter|.
This method requires as parameter:

Expand All @@ -38,11 +32,102 @@ This method requires as parameter:
Obtain pointer to the extended |StatisticsDomainParticipant-api| class
----------------------------------------------------------------------

.. warning::
This method will be implemented in future releases. For the moment it always returns ``nullptr``.

The |DomainParticipant-api| is created using the |DomainParticipantFactory::create_participant-api| provided by the
|DomainParticipantFactory-api|.
This method returns a pointer to the DDS standard DomainParticipant created.
In order to obtain the pointer to the child |StatisticsDomainParticipant-api| which extends the DDS API, the
``static`` method |statistics_narrow| is provided.

The following example shows how to use the Statistics module extended DDS API:

.. literalinclude:: /../code/DDSCodeTester.cpp
:language: c++
:start-after: // ENABLE_DISABLE_STATISTICS_DATAWRITER
:end-before: //!--
:dedent: 8

.. _auto_enabling_statistics_datawriters:

Automatically enabling statistics DataWriters
---------------------------------------------

The statistics DataWriters can be directly enabled using the |DomainParticipantQos|
|DomainParticipantQos::properties-api| ``fastdds.statistics``.
The value of this property is a semicolon separated list containing the
:ref:`statistics topic name aliases<statistics_topic_names>` of those DataWriters that the user wants to enable.
The property can be set either programmatically or loading an XML file.
If the property is set in both ways, the priority would depend on the API and the QoS profile provided:

* XML settings have priority if |DomainParticipantFactory::create_participant_with_profile-api| is called with a valid
participant profile.

* XML settings also have priority if |DomainParticipantFactory::create_participant-api| is called using
|PARTICIPANT_QOS_DEFAULT-api| and a participant profile exists in the XML file with the ``is_default_profile`` option
set to ``true`` (:ref:`domainparticipantattributes`).

* The property set programmatically is used only when |DomainParticipantFactory::create_participant-api| is called with
the specific QoS.

Another way of enabling statistics DataWriters, compatible with the previous one, is setting the
:ref:`env_vars_fastdds_statistics` environment variable.
The statistics DataWriters that will be enabled when the |DomainParticipant-api| is enabled would be the union between
those specified in the |DomainParticipantQos::properties-api| ``fastdds.statistics`` and those included with the
environment variable.

The following examples show how to use all the previous methods:

+----------------------------------------------------------------------------------------------------------------------+
| **C++** |
+----------------------------------------------------------------------------------------------------------------------+
| .. literalinclude:: /../code/DDSCodeTester.cpp |
| :language: c++ |
| :start-after: // FASTDDS_STATISTICS_MODULE |
| :end-before: //!-- |
| :dedent: 8 |
+----------------------------------------------------------------------------------------------------------------------+
| **XML** |
+----------------------------------------------------------------------------------------------------------------------+
| .. literalinclude:: /../code/XMLTester.xml |
| :language: xml |
| :start-after: <!-->FASTDDS_STATISTICS_MODULE<--> |
| :end-before: <!--><--> |
+----------------------------------------------------------------------------------------------------------------------+
| **Environment Variable Linux** |
+----------------------------------------------------------------------------------------------------------------------+
| .. code-block:: bash |
| |
| export FASTDDS_STATISTICS=HISTORY_LATENCY_TOPIC;ACKNACK_COUNT_TOPIC;DISCOVERY_TOPIC;PHYSICAL_DATA_TOPIC |
+----------------------------------------------------------------------------------------------------------------------+
| **Environment Variable Windows** |
+----------------------------------------------------------------------------------------------------------------------+
| .. code-block:: bash |
| |
| set FASTDDS_STATISTICS=HISTORY_LATENCY_TOPIC;ACKNACK_COUNT_TOPIC;DISCOVERY_TOPIC;PHYSICAL_DATA_TOPIC |
+----------------------------------------------------------------------------------------------------------------------+

Be aware that automatically enabling the statistics DataWriters using all these methods implies using the recommended
QoS profile |STATISTICS_DATAWRITER_QOS-api|. For more information, please refer to :ref:`statistics_datawriter_qos`.

.. warning::
Currently, the following :ref:`statistics topics <statistics_topic_names>` have not been implemented yet. They will
be available in future releases:

* |HISTORY_LATENCY_TOPIC|

* |NETWORK_LATENCY_TOPIC|

* |PUBLICATION_THROUGHPUT_TOPIC|

* |SUBSCRIPTION_THROUGHPUT_TOPIC|

* |RTPS_LOST_TOPIC|

* |RESENT_DATAS_TOPIC|

* |SAMPLE_DATAS_TOPIC|

* |PDP_PACKETS_TOPIC|

* |EDP_PACKETS_TOPIC|

* |PHYSICAL_DATA_TOPIC|
9 changes: 9 additions & 0 deletions docs/fastdds/statistics/dds_layer/qos.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,12 @@ Statistics DataWriter recommended QoS
-------------------------------------

The following table shows the recommended |DataWriterQos-api| profile for enabling the statistics DataWriters.
This profile enables the ``pull mode`` :ref:`operating mode <push_mode_qos_policy>` on the statistics DataWriters.
This entails that the DataWriters will only send information upon the reception of acknack submessages sent by the
monitoring DataReader.
This QoS profile is always used when the statistics DataWriters are
:ref:`auto-enabled <auto_enabling_statistics_datawriters>`.
The recommended profile can be accessed through the constant |STATISTICS_DATAWRITER_QOS-api|.

.. list-table::
:header-rows: 1
Expand All @@ -36,11 +42,14 @@ The following table shows the recommended |DataWriterQos-api| profile for enabli
- |KEEP_LAST_HISTORY_QOS-api|
* - |history_depth-api|
- 100
* - |PropertyPolicyQos-api| name = value
- ``"fastdds.push_mode"`` = ``"false"``

Statistics DataReader recommended QoS
-------------------------------------

The following table shows the recommended |DataReaderQos-api| profile for creating the monitoring DataReaders.
The recommended profile can be accessed through constant |STATISTICS_DATAREADER_QOS-api|.

.. list-table::
:header-rows: 1
Expand Down
Loading

0 comments on commit 346fbdf

Please sign in to comment.