13.1.2. Statistics Domain Participant¶
In order to start collecting data in one of the statistics topics (Statistics Topic names), the corresponding
statistics DataWriter should be enabled.
In fact, Fast DDS Statistics module can be enabled and disabled at runtime.
For this purpose, Fast DDS Statistics module exposes an extended DDS DomainParticipant
API:
13.1.2.1. Enable statistics DataWriters¶
Statistics DataWriters can be enabled in different ways.
It can be done automatically (see Automatically enabling statistics DataWriters).
Alternatively, Statistics DataWriters can be enabled at run time using one of two methods:
enable_statistics_datawriter()
or enable_statistics_datawriter_with_profile()
.
enable_statistics_datawriter()
method requires as parameters:
Name of the statistics topic to be enabled (see Statistics Topic names for the statistics topic list).
DataWriter QoS profile (see Statistics DataWriter recommended QoS for the recommended profile).
It is possible to define specific desired QoS through DataWriter profile on the FASTRTPS_DEFAULT_PROFILES_FILE
(see XML profiles).
enable_statistics_datawriter_with_profile()
method enables a DataWriter by searching a specific DataWriter XML profile.
On those profiles, specific QoS can be set.
enable_statistics_datawriter_with_profile()
method requires as parameters:
Name of the XML profile to use to fill the QoS structure of the DataWriter.
Name of the statistics topic name to be enabled. (see Statistics Topic names for the statistics topic list).
13.1.2.2. Disable statistics DataWriters¶
Statistics DataWriters are disabled using the method disable_statistics_datawriter()
.
This method requires as parameter:
Name of the statistics topic to be disabled (see Statistics Topic names for the statistics topic list).
13.1.2.3. Obtain pointer to the extended DomainParticipant
class¶
The DomainParticipant
is created using the create_participant()
provided by the
DomainParticipantFactory
.
This method returns a pointer to the DDS standard DomainParticipant created.
In order to obtain the pointer to the child DomainParticipant
which extends the DDS API, the
static
method narrow()
is provided.
13.1.2.4. Example¶
The following example shows how to use the Statistics module extended DDS API:
// 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;
}
13.1.2.5. Automatically enabling statistics DataWriters¶
The statistics DataWriters can be directly enabled using the DomainParticipantQos
properties()
fastdds.statistics
.
The value of this property is a semicolon separated list containing the
statistics topic name aliases 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
create_participant_with_profile()
is called with a valid participant profile.XML settings also have priority if
create_participant()
is called usingPARTICIPANT_QOS_DEFAULT
and a participant profile exists in the XML file with theis_default_profile
option set totrue
(DomainParticipant XML attributes).The property set programmatically is used only when
create_participant()
is called with the specific QoS.
Another way of enabling statistics DataWriters, compatible with the previous one, is setting the
FASTDDS_STATISTICS environment variable.
The statistics DataWriters that will be enabled when the DomainParticipant
is enabled would be the union between
those specified in the properties()
fastdds.statistics
and those included with the
environment variable.
The following examples show how to use all the previous methods:
C++ |
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");
|
XML |
<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>
|
Environment Variable Linux |
export FASTDDS_STATISTICS="HISTORY_LATENCY_TOPIC;ACKNACK_COUNT_TOPIC;DISCOVERY_TOPIC;PHYSICAL_DATA_TOPIC"
|
Environment Variable Windows |
set FASTDDS_STATISTICS=HISTORY_LATENCY_TOPIC;ACKNACK_COUNT_TOPIC;DISCOVERY_TOPIC;PHYSICAL_DATA_TOPIC
|
Note
These are all the statistics topics:
HISTORY_LATENCY_TOPIC;NETWORK_LATENCY_TOPIC;PUBLICATION_THROUGHPUT_TOPIC;SUBSCRIPTION_THROUGHPUT_TOPIC;RTPS_SENT_TOPIC;RTPS_LOST_TOPIC;HEARTBEAT_COUNT_TOPIC;ACKNACK_COUNT_TOPIC;NACKFRAG_COUNT_TOPIC;GAP_COUNT_TOPIC;DATA_COUNT_TOPIC;RESENT_DATAS_TOPIC;SAMPLE_DATAS_TOPIC;PDP_PACKETS_TOPIC;EDP_PACKETS_TOPIC;DISCOVERY_TOPIC;PHYSICAL_DATA_TOPIC
Note
Be aware that automatically enabling the statistics DataWriters using all these methods implies using the recommended
QoS profile STATISTICS_DATAWRITER_QOS
. For more information, please refer to Statistics DataWriter recommended QoS.
However, if an XML profile is defined, the QoS applied are those defined in the profile,
and for those QoS that are not specified in that profile, the default library QoS are applied
(see DataWriterQos for the standard eProsima’s DataWriter QoS),
and not the recommended QoS for the Statistics DataWriters.
For the creation of an automatically enabled Datawriter, the priority for setting its QoS is the following:
First, if a specific profile exists for the statistics topic, that one is applied.
If that is not the case but a generic profile for statistics DataWriters exists, that one is applied.
If no profile is defined in XML file, the recommended statistics QoS are applied.
Note
The generic DataWriter profile defined in the FASTRTPS_DEFAULT_PROFILES_FILE XML needs to be named as GENERIC_STATISTICS_PROFILE.
The specific DataWriter profile defined in the FASTRTPS_DEFAULT_PROFILES_FILE XML needs to be named using the
same statistic topic alias or name (see Statistics Topic names for the alias corresponding to each statistic
topic) that has been used in the DomainParticipantQos properties()
fastdds.statistics
(see Statistics Module Settings) or the FASTDDS_STATISTICS environment variable,
where the enabling of the corresponding statistics
topic has been set.