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 three overloads of init_monitor() that can be used to start a monitorization on a DDS domain or a Fast DDS Discovery Server network.

// 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, and that uses the default GUID prefix
// eprosima::fastdds::rtps::DEFAULT_ROS2_SERVER_GUIDPREFIX.
// The monitor has no listener associated.
EntityId disc_server_monitor_id =
        StatisticsBackend::init_monitor("UDPv4:[127.0.0.1]:11811");

// 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, and that uses the GUID prefix
// "44.53.01.5f.45.50.52.4f.53.49.4d.41".
// The monitor has no listener associated.
EntityId disc_server_prefix_monitor_id =
        StatisticsBackend::init_monitor("44.53.01.5f.45.50.52.4f.53.49.4d.41", "UDPv4:[localhost]:11811");

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, and that uses the default GUID prefix
// eprosima::fastdds::rtps::DEFAULT_ROS2_SERVER_GUIDPREFIX.
// The monitor uses a custom listener.
EntityId disc_server_monitor_id =
        StatisticsBackend::init_monitor("UDPv4:[127.0.0.1]:11811", &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 transport layer, and that uses the GUID prefix
// "44.53.01.5f.45.50.52.4f.53.49.4d.41".
// The monitor uses a custom listener.
EntityId disc_server_prefix_monitor_id =
        StatisticsBackend::init_monitor("44.53.01.5f.45.50.52.4f.53.49.4d.41", "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, and that uses the default GUID prefix
// eprosima::fastdds::rtps::DEFAULT_ROS2_SERVER_GUIDPREFIX.
// 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);

// 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, and that uses the GUID prefix
// "44.53.01.5f.45.50.52.4f.53.49.4d.41".
// The monitor uses a custom listener, a CallbackMask, and a DataKindMask.
EntityId disc_server_prefix_monitor_id =
        StatisticsBackend::init_monitor("44.53.01.5f.45.50.52.4f.53.49.4d.41", "UDPv4:[127.0.0.1]:11811",
                &domain_listener, callback_mask, datakind_mask);

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