5.3. StatisticsBackend¶

class StatisticsBackend¶

Public Functions

StatisticsBackend() = delete¶: Deleted constructor, since the whole interface is static.

Public Static Functions

static void set_physical_listener(PhysicalListener *listener, CallbackMask callback_mask = CallbackMask::all(), DataKindMask data_mask = DataKindMask::none())¶

Set the listener for the physical domain events.

Any physical listener already configured will be replaced by the new one. The provided pointer to the listener can be null, in which case, any physical listener already configured will be removed.

Parameters

listener – The listener with the callback implementations.
callback_mask – Mask of the callbacks. Only the events that have the mask bit set will be informed.
data_mask – Mask of the data types that will be monitored.

static EntityId init_monitor(DomainId domain, DomainListener *domain_listener = nullptr, CallbackMask callback_mask = CallbackMask::all(), DataKindMask data_mask = DataKindMask::none(), std::string app_id = app_id_str[(int)AppId::UNKNOWN], std::string app_metadata = "")¶

Starts monitoring on a given domain.

This function creates a new statistics DomainParticipant that starts monitoring the requested domain ID.

Parameters

domain – The domain ID of the DDS domain to monitor.
domain_listener – Listener with the callback to use to inform of events.
callback_mask – Mask of the callbacks. Only the events that have the mask bit set will be informed.
data_mask – Mask of the data types that will be monitored.
app_id – App id of the monitor participant.
app_metadata – Metadata of the monitor participant.

Throws

eprosima::statistics_backend::BadParameter – if a monitor is already created for the given domain.
eprosima::statistics_backend::Error – if the creation of the monitor fails.

Returns

The ID of the created statistics Domain.

static EntityId init_monitor(std::string discovery_server_locators, DomainListener *domain_listener = nullptr, CallbackMask callback_mask = CallbackMask::all(), DataKindMask data_mask = DataKindMask::none(), std::string app_id = app_id_str[(int)AppId::UNKNOWN], std::string app_metadata = "")¶

Starts monitoring the network corresponding to a server.

This function creates a new statistics DomainParticipant that starts monitoring the network of the server with the given locators. The server GuidPrefix_t is set to the default one: eprosima::fastdds::rtps::DEFAULT_ROS2_SERVER_GUIDPREFIX. If any other server is to be used, call the overload method that receives the GuidPrefix_t as parameter.

The format to specify a locator is: kind:[IP]:port, where:

kind is one of { UDPv4, TCPv4, UDPv6, TCPv4 }
IP is the IP address
port is the IP port Note that SHM locators are not supported. For any server configured with shared memory locators, initialize the monitor using only the non shared memory locators.

Parameters

discovery_server_locators – The locator list of the server whose network is to be monitored, formatted as a semicolon separated list of locators.
domain_listener – Listener with the callback to use to inform of events.
callback_mask – Mask of the callbacks. Only the events that have the mask bit set will be informed.
data_mask – Mask of the data types that will be monitored.
app_id – App id of the monitor participant.
app_metadata – Metadata of the monitor participant.

Returns

The ID of the created statistics Domain.

static EntityId init_monitor(std::string discovery_server_guid_prefix, std::string discovery_server_locators, DomainListener *domain_listener = nullptr, CallbackMask callback_mask = CallbackMask::all(), DataKindMask data_mask = DataKindMask::none(), std::string app_id = app_id_str[(int)AppId::UNKNOWN], std::string app_metadata = "")¶

Starts monitoring the network corresponding to a server.

This function creates a new statistics DomainParticipant that starts monitoring the network of the server with the given GuidPrefix_t and with the given locators.

The format to specify a locator is: kind:[IP]:port, where:

kind is one of { UDPv4, TCPv4, UDPv6, TCPv4 }
IP is the IP address
port is the IP port Note that SHM locators are not supported. For any server configured with shared memory locators, initialize the monitor using only the non shared memory locators.

Parameters

discovery_server_guid_prefix – Server GuidPrefix_t to be monitored.
discovery_server_locators – The locator list of the server whose network is to be monitored, formatted as a semicolon separated list of locators.
domain_listener – Listener with the callback to use to inform of events.
callback_mask – Mask of the callbacks. Only the events that have the mask bit set will be informed.
data_mask – Mask of the data types that will be monitored.
app_id – App id of the monitor participant.
app_metadata – Metadata of the monitor participant.

Returns

The ID of the created statistics Domain.

static void restart_monitor(EntityId monitor_id)¶

Restarts a given monitor.

This function restarts a domain monitor. If the monitor is still active (meaning it has not being stopped), this function takes no effect.

Parameters: monitor_id – The entity ID of the monitor to restart.

static void stop_monitor(EntityId monitor_id)¶

Stops a given monitor.

This function stops a domain monitor. After stopping, the statistical data related to the domain is still accessible.

Parameters: monitor_id – The entity ID of the monitor to stop.
Throws: eprosima::statistics_backend::BadParameter – if the given monitor ID is not yet registered.

static void clear_monitor(EntityId monitor_id)¶

Clear the data of a domain given its monitor.

This function clears all the data related to a domain given its monitor ID. If the monitor is still active (meaning it has not being stopped), this functions takes no effect. After clearing, the statistical data related to the domain is deleted and therefore no longer accessible.

Parameters: monitor_id – The entity ID of the monitor to stop.

static void set_domain_listener(EntityId monitor_id, DomainListener *listener = nullptr, CallbackMask callback_mask = CallbackMask::all(), DataKindMask data_mask = DataKindMask::none())¶

Set the listener of a monitor for the domain events.

Any domain listener already configured will be replaced by the new one. The provided pointer to the listener can be null, in which case, any domain listener already configured will be removed.

Parameters

monitor_id – The entity ID of the monitor.
listener – The listener with the callback implementations.
callback_mask – Mask of the callbacks. Only the events that have the mask bit set will be informed.
data_mask – Mask of the data types that will be monitored.

Throws

eprosima::statistics_backend::BadParameter – if the given monitor ID is not yet registered.

static std::vector<EntityId> get_entities(EntityKind entity_type, EntityId entity_id = EntityId::all())¶

Get all the entities of a given type related to another entity.

Get all the entity ids for every entity of kind entity_type that is connected with entity entity_id. Connection between entities means they are directly connected by a contained/connect relation (i.e. Host - User | Domain - Topic) or that connected entities are connected to it.

Use case: To get all host in the system, use arguments HOST and EntityId::all().

Use case: To get all locators from a participant with id X, use arguments LOCATOR and X, this will get all the locators that are connected with the endpoints this participant has.

In case the entity_id is not specified, all entities of type entity_type are returned.

Parameters

entity_type – The type of entities for which the search is performed.
entity_id – The ID of the entity to which the resulting entities are related.

Throws

eprosima::statistics_backend::BadParameter – in the following cases:

if the entity_kind is INVALID.
if the entity_id does not reference a entity contained in the database or is not EntityId::all().
if the EntityKind of the Entity with entity_id is INVALID.

Returns

All entities of type entity_type that are related to entity_id.

static bool is_active(EntityId entity_id)¶

Returns whether the entity is active.

For monitors, active means that no call to stop_monitor() has been performed since the last time the monitor was activated. For the rest of entities, active means that there is statistical data being reported within the entity.

Parameters: entity_id – The ID of the entity whose activeness is requested.
Returns: true if active, false otherwise.

static bool is_metatraffic(EntityId entity_id)¶

Returns whether the entity is related to a metatraffic topic.

For Topics, it is true when they are used for sharing metatraffic data. For DDSEndpoints, it is true when their associated to a metatraffic Topic. For the rest of entities, metatraffic is always false.

Parameters: entity_id – The ID of the entity whose metatraffic attribute is requested.
Returns: true if metatraffic, false otherwise.

static EntityKind get_type(EntityId entity_id)¶

Returns the entity kind of a given id.

Parameters: entity_id – The ID of the entity whose type is requested.
Throws: eprosima::statistics_backend::BadParameter – if there is no entity with the given ID.
Returns: EntityKind of entity_id.

static StatusLevel get_status(EntityId entity_id)¶

Returns the entity status of a given id.

Parameters: entity_id – The ID of the entity whose status is requested.
Throws: eprosima::statistics_backend::BadParameter – if there is no entity with the given ID.
Returns: StatusLevel of entity_id.

static Info get_info(EntityId entity_id)¶

Get the meta information of a given entity.

Parameters: entity_id – The entity for which the meta information is retrieved.
Returns: Info object describing the entity’s meta information.

static std::vector<StatisticsData> get_data(DataKind data_type, const std::vector<EntityId> &entity_ids_source, const std::vector<EntityId> &entity_ids_target, uint16_t bins = 0, Timestamp t_from = the_initial_time(), Timestamp t_to = now(), StatisticKind statistic = StatisticKind::NONE)¶

Provides access to the data measured during the monitoring.

Use this function for data types that relate to two entities, as described in DataType.

For data types that relate to a single entity, use the overloaded function that takes a single entity as argument.

t_from and t_to define the time interval for which the measurements will be returned. This time interval is further divided into bin segments of equal length, and a measurement is returned for each segment. Consequently, t_to should be greater than t_from by at least bin nanoseconds.

Measurement time and intervals

If bin is zero, no statistic is calculated and the raw data values in the requested time interval are returned.

The kind of statistic calculated for each bin segment is indicated by statistic. In this implementation, if statistic is NONE, the first raw data point in the segment is returned.

Statistics

See also

StatisticsBackend

Parameters

data_type – The type of the measurement being requested.
entity_ids_source – Ids of the source entities of the requested data. These IDs must correspond to entities of specific kinds depending on the data_type.
entity_ids_target – Ids of the target entities of the requested data. These IDs must correspond to entities of specific kinds depending on the data_type.
bins – Number of time intervals in which the measurement time is divided.
t_from – Starting time of the returned measures.
t_to – Ending time of the returned measures.
statistic – Statistic to calculate for each of the bins.

Throws

eprosima::statistics_backend::BadParameter – if the above preconditions are not met.

Returns

a vector of bin elements with the values of the requested statistic.

static std::vector<StatisticsData> get_data(DataKind data_type, const std::vector<EntityId> &entity_ids, uint16_t bins = 0, Timestamp t_from = the_initial_time(), Timestamp t_to = now(), StatisticKind statistic = StatisticKind::NONE)¶

Provides access to the data measured during the monitoring.

Use this function for data types that relate to a single entity, as described in DataType.

For data types that relate to two entities, use the overloaded function that takes a source and a target entity as arguments.

t_from and t_to define the time interval for which the measurements will be returned. This time interval is further divided into bin segments of equal length, and a measurement is returned for each segment. Consequently, t_to should be greater than t_from by at least bin nanoseconds.

Measurement time and intervals

If bin is zero, no statistic is calculated and the raw data values in the requested time interval are returned.

The kind of statistic calculated for each bin segment is indicated by statistic. In this implementation, if statistic is NONE, the first raw data point in the segment is returned.

Statistics

See also

StatisticsBackend

Parameters

data_type – The type of the measurement being requested.
entity_ids – Ids of the entities of the requested data. These IDs must correspond to entities of specific kinds depending on the data_type.
bins – Number of time intervals in which the measurement time is divided.
t_from – Starting time of the returned measures.
t_to – Ending time of the returned measures.
statistic – Statistic to calculate for each of the bins.

Throws

eprosima::statistics_backend::BadParameter – if the above preconditions are not met.

Returns

a vector of bin elements with the values of the requested statistic.

static std::vector<StatisticsData> get_data(DataKind data_type, const std::vector<EntityId> &entity_ids_source, const std::vector<EntityId> &entity_ids_target, uint16_t bins, StatisticKind statistic)¶

Overload of get_data method without time arguments.

It calls the get_data method with the default time arguments. It is used to set the statistic argument with default time values.

Parameters

data_type – The type of the measurement being requested.
entity_ids_source – Ids of the source entities of the requested data. These IDs must correspond to entities of specific kinds depending on the data_type.
entity_ids_target – Ids of the target entities of the requested data. These IDs must correspond to entities of specific kinds depending on the data_type.
bins – Number of time intervals in which the measurement time is divided.
statistic – Statistic to calculate for each of the bins.

Throws

eprosima::statistics_backend::BadParameter – if the above preconditions are not met.

Returns

a vector of bin elements with the values of the requested statistic.

static std::vector<StatisticsData> get_data(DataKind data_type, const std::vector<EntityId> &entity_ids, uint16_t bins, StatisticKind statistic)¶

Overload of get_data method without time arguments.

It calls the get_data method with the default time arguments. It is used to set the statistic argument with default time values.

Parameters

data_type – The type of the measurement being requested.
entity_ids – Ids of the entities of the requested data. These IDs must correspond to entities of specific kinds depending on the data_type.
bins – Number of time intervals in which the measurement time is divided.
statistic – Statistic to calculate for each of the bins.

Throws

eprosima::statistics_backend::BadParameter – if the above preconditions are not met.

Returns

a vector of bin elements with the values of the requested statistic.

template<typename T> static void get_status_data(const EntityId &entity_id, T &status_data)¶

Get monitor service status data.

Default method is called if StatusKind is invalid.

Parameters

entity_id – The id of the Entity whose status info is requested.
status_data – Status data to be filled.

Throws

eprosima::statistics_backend::BadParameter – in the following cases:

if the entity_id does not reference a entity contained in the database.
if there is no specialization template for the requested StatusKind.
if the EntityKind of the Entity with entity_id doesn’t have the associated status_data.

static Graph get_domain_view_graph(const EntityId &domain_id)¶

Get the domain view graph.

Parameters: domain_id – EntityId from domain whose graph is delivered.
Throws: eprosima::statistics_backend::BadParameter – if there is no graph for the specified domain id.
Returns: Graph object describing per domain topology of the entities.

static bool regenerate_domain_graph(const EntityId &domain_id)¶

Regenerate graph from data stored in database.

Parameters: domain_id – EntityId from domain whose graph is regenerated.
Returns: True if the graph has been regenerated

static DatabaseDump dump_database(bool clear)¶

Get a dump of the database.

Parameters: clear – If true, clear all the statistics data of all entities.
Returns: DatabaseDump object representing the backend database.

static void dump_database(const std::string &filename, bool clear)¶

Dump Fast DDS Statistics Backend’s database to a file.

Parameters

filename – The name of the file where the database is dumped.
clear – If true, clear all the statistics data of all entities.

static void load_database(const std::string &filename)¶

Load Fast DDS Statistics Backend’s database from a file.

Parameters: filename – The name of the file from which where the database is loaded.
Throws: eprosima::statistics_backend::BadParameter – if the file does not exist.
Pre: The Backend’s database has no data. This means that no monitors were initialized since the Backend started, or that the Backend has been reset().

static void clear_statistics_data(const Timestamp &t_to = the_end_of_time())¶

Clear statistics data of all entities received previous to the time given.

Parameters: t_to – Timestamp regarding the maximum time to stop removing data.

static void clear_inactive_entities()¶: Remove all inactive entities from database.

static void reset()¶

Resets the Fast DDS Statistics Backend.

After calling this method, the Fast DDS Statistics Backend reverts to its default state, as it was freshly started:

All the data in the database is erased.
All monitors are removed and cannot be restarted afterwards.
The physical listener is removed.
The physical listener callback mask is set to CallbackMask::none().
The physical listener data mask is set to DataMask::none().

Pre: There are no active monitors. There can be inactive monitors.

static std::vector<std::pair<EntityKind, EntityKind>> get_data_supported_entity_kinds(DataKind data_kind)¶

Return the EntityKind of the entities to which a DataKind refers.

Some DataKind relate to a single Entity of a given EntityKind. This is the case of SUBSCRIPTION_THROUGHPUT, that always relates to a DATAREADER. Other DataKind relate to two different Entity, each one of a given EntityKind. For example, FASTDDS_LATENCY relates to a DATAWRITER as source and a DATAREADER as target of the data flow. In the specific case of DISCOVERY_TIME, the DataKind relates to a PARTICIPANT as the discoverer, but can relate to a DATAWRITER, DATAREADER or another PARTICIPANT as the discovered entity.

Given a DataKind, this method provides a collection of all pairs of EntityKind to which this DataKind relates.

For a DataKind that only relates to one Entity, the first element of the pair is the EntityKind of such Entity, while the second element is EntityKind::INVALID.
For a DataKind that relates to two Entity, the first element of the pair is the EntityKind of the source Entity, while the second element is the EntityKind of the target Entity.

The source and target pairs returned by this method are exactly the accepted source and target EntityKind accepted by get_data for the given DataKind. This is convenient to prepare a call to get_data from an EntityKind. First, call get_data_supported_entity_kinds with the EntityKind to get the EntityKinds of the related entities. Then, call get_entities to get the available entities for that kind. Finally, call get_data with the pairs that get_entities returns.

i.e. Get the DISCOVERY_TIME of all entities on Host2 discovered by Host1:

// Get all the EntityKind pairs related to DISCOVERY_TIME.
std::vector<std::pair<EntityKind, EntityKind>> types_list =
        StatisticsBackend::get_data_supported_entity_kinds(DataKind::DISCOVERY_TIME);

// Iterate over all the valid pairs composing the final result
std::vector<StatisticsData> discovery_times;
for (std::pair<EntityKind, EntityKind> type_pair : types_list)
{
    // Take the data for this pair and append it to the existing data
    std::vector<StatisticsData> tmp = StatisticsBackend::get_data(
            DataKind::DISCOVERY_TIME,
            StatisticsBackend::get_entities(type_pair.first, host1_id),
            StatisticsBackend::get_entities(type_pair.second, host2_id));

    discovery_times.insert(discovery_times.end(), tmp.begin(), tmp.end());
}

See also

DataKind

See also

get_data

Parameters: data_kind – Data kind.
Returns: list of EntityKind pairs with the entity kinds to which a DataKind refers.

static void set_alias(EntityId entity_id, const std::string &alias)¶

Set a new alias for the entity.

Parameters

entity_id – The EntityId of the entity.
alias – New alias that will replace the old one.

Throws

eprosima::statistics_backend::BadParameter – if there is no entity with the given ID.