1.1. Initialize a monitor

Initializing a monitor on a certain Domain ID makes eProsima Fast DDS Statistics Backend start monitoring the statistics data and entity discoveries on that domain. No statistics data will be gathered unless there is a monitor initialized in the required domain.

StatisticsBackend provides several overloads of init_monitor() that can be used to start a monitorization on a DDS domain or a Fast DDS Discovery Server network.

Additionally, it is possible to initialize a monitor using an XML profile with the new init_monitor_with_profile() method. This allows the monitor to be configured according to the settings defined in the XML profile, providing greater flexibility and integration with existing Fast DDS XML configuration workflows.

// Init a monitor in DDS domain 0 with no listener associated.
EntityId domain_monitor_id =
        StatisticsBackend::init_monitor(0);

// Init a monitor for a Fast DDS Discovery Server network which server is located in IPv4
// address 127.0.0.1 and port 11811 using UDP as transport layer.
// The monitor has no listener associated.
EntityId disc_server_monitor_id =
        StatisticsBackend::init_monitor("UDPv4:[127.0.0.1]:11811");

The following example demonstrates how to initialize a monitor using an XML profile:

// Init a monitor in DDS domain 0 using an XML profile named "monitor_profile" from the file "my_profiles.xml".
StatisticsBackend::load_xml_profiles_file("my_profiles.xml");
StatisticsBackend::init_monitor_with_profile("monitor_profile");

Furthermore, it is possible to initialize a monitor with a custom DomainListener. Please refer to DomainListener for more information about the DomainListener and its functionality.

CustomDomainListener domain_listener;

// Init a monitor in DDS domain 0 with a custom listener.
EntityId domain_monitor_id =
        StatisticsBackend::init_monitor(0, &domain_listener);

// Init a monitor for a Fast DDS Discovery Server network which server is located in IPv4
// address 127.0.0.1 and port 11811 using UDP as transport layer.
// The monitor uses a custom listener.
EntityId disc_server_monitor_id =
        StatisticsBackend::init_monitor("UDPv4:[127.0.0.1]:11811", &domain_listener);

In addition, init_monitor() allows for specifying which monitorization events should be notified. This is done by setting a CallbackMask where the active callbacks from the listener are specified. Moreover, a mask on statistics data kind of interest can be set creating a DataKindMask

// Only get notifications when new data is available or when a new host is discovered
CallbackMask callback_mask = CallbackKind::ON_DATA_AVAILABLE | CallbackKind::ON_HOST_DISCOVERY;

// Only get notificiations about network latency or subscription throughput
DataKindMask datakind_mask = DataKind::NETWORK_LATENCY | DataKind::SUBSCRIPTION_THROUGHPUT;

CustomDomainListener domain_listener;

// Init a monitor in DDS domain 0 with a custom listener, a CallbackMask, and a DataKindMask
EntityId domain_monitor_id =
        StatisticsBackend::init_monitor(0, &domain_listener, callback_mask, datakind_mask);

// Init a monitor for a Fast DDS Discovery Server network which server is located in IPv4
// address 127.0.0.1 and port 11811 using UDP transport layer.
// The monitor uses a custom listener, a CallbackMask, and a DataKindMask.
EntityId disc_server_monitor_id =
        StatisticsBackend::init_monitor("UDPv4:[localhost]:11811", &domain_listener, callback_mask,
                datakind_mask);

Similarly, when initializing a monitor with an XML profile, you can also specify a custom DomainListener and callback masks as needed.

init_monitor() throws exceptions in the following cases:

BadParameter if a monitor is already created for the given DDS domain or Fast DDS Discovery Server network.
Error if the creation of the monitor fails