10.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:

Enable statistics DataWriters
Disable statistics DataWriters
Obtain pointer to the extended DomainParticipant class
Example
Automatically enabling statistics DataWriters

10.1.2.1. Enable statistics DataWriters¶

Statistics DataWriters are enabled using the method enable_statistics_datawriter(). This 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).

10.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).

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

10.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;
}

10.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 using PARTICIPANT_QOS_DEFAULT and a participant profile exists in the XML file with the is_default_profile option set to true (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

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.