counters.hpp¶

See Public API for a list of names and headers that are part of the public HPX API.

namespace hpx

namespace performance_counters

Typedefs

typedef hpx::function<naming::gid_type(counter_info const&, error_code&)> create_counter_func¶: This declares the type of a function, which will be called by HPX whenever a new performance counter instance of a particular type needs to be created.

typedef hpx::function<bool(counter_info const&, error_code&)> discover_counter_func¶: This declares a type of a function, which will be passed to a discover_counters_func in order to be called for each discovered performance counter instance.

typedef hpx::function<bool(counter_info const&, discover_counter_func const&, discover_counters_mode, error_code&)> discover_counters_func¶: This declares the type of a function, which will be called by HPX whenever it needs to discover all performance counter instances of a particular type.

Enums

enum counter_type¶

Values:

text¶

text shows a variable-length text string. It does not deliver calculated values.

Formula: None Average: None Type: Text

raw¶

raw shows the last observed value only. It does not deliver an average.

Formula: None. Shows raw data as collected. Average: None Type: Instantaneous

monotonically_increasing¶

monotonically_increasing shows the cumulatively accumulated observed value. It does not deliver an average.

Formula: None. Shows cumulatively accumulated data as collected. Average: None Type: Instantaneous

average_base¶

average_base is used as the base data (denominator) in the computation of time or count averages for the counter_type::average_count and counter_type::average_timer counter types. This counter type collects the last observed value only.

Formula: None. This counter uses raw data in factional calculations without delivering an output. Average: SUM (N) / x Type: Instantaneous

average_count¶

average_count shows how many items are processed, on average, during an operation. Counters of this type display a ratio of the items processed (such as bytes sent) to the number of operations completed. The ratio is calculated by comparing the number of items processed during the last interval to the number of operations completed during the last interval.

Formula: (N1 - N0) / (D1 - D0), where the numerator (N) represents the number of items processed during the last sample interval, and the denominator (D) represents the number of operations completed during the last two sample intervals. Average: (Nx - N0) / (Dx - D0) Type: Average

aggregating¶

aggregating applies a function to an embedded counter instance. The embedded counter is usually evaluated repeatedly after a fixed (but configurable) time interval.

Formula: F(Nx)

average_timer¶

average_timer measures the average time it takes to complete a process or operation. Counters of this type display a ratio of the total elapsed time of the sample interval to the number of processes or operations completed during that time. This counter type measures time in ticks of the system clock. The variable F represents the number of ticks per second. The value of F is factored into the equation so that the result is displayed in seconds.

Formula: ((N1 - N0) / F) / (D1 - D0), where the numerator (N) represents the number of ticks counted during the last sample interval, the variable F represents the frequency of the ticks, and the denominator (D) represents the number of operations completed during the last sample interval. Average: ((Nx - N0) / F) / (Dx - D0) Type: Average

elapsed_time¶

elapsed_time shows the total time between when the component or process started and the time when this value is calculated. The variable F represents the number of time units that elapse in one second. The value of F is factored into the equation so that the result is displayed in seconds.

Formula: (D0 - N0) / F, where the nominator (D) represents the current time, the numerator (N) represents the time the object was started, and the variable F represents the number of time units that elapse in one second. Average: (Dx - N0) / F Type: Difference

histogram¶

histogram exposes a histogram of the measured values instead of a single value as many of the other counter types. Counters of this type expose a counter_value_array instead of a counter_value. Those will also not implement the get_counter_value() functionality. The results are exposed through a separate get_counter_values_array() function.

The first three values in the returned array represent the lower and upper boundaries, and the size of the histogram buckets. All remaining values in the returned array represent the number of measurements for each of the buckets in the histogram.

raw_values¶: raw_values exposes an array of measured values instead of a single value as many of the other counter types. Counters of this type expose a counter_value_array instead of a counter_value. Those will also not implement the get_counter_value() functionality. The results are exposed through a separate get_counter_values_array() function.

text

raw

monotonically_increasing

average_base

average_count

aggregating

average_timer

elapsed_time

histogram

raw_values: raw_values counter exposes an array of measured values instead of a single value as many of the other counter types. Counters of this type expose a counter_value_array instead of a counter_value. Those will also not implement the get_counter_value() functionality. The results are exposed through a separate get_counter_values_array() function.

enum counter_status¶

Status and error codes used by the functions related to performance counters.

Values:

status_valid_data¶: No error occurred, data is valid.

status_new_data¶: Data is valid and different from last call.

status_invalid_data¶: Some error occurred, data is not value.

status_already_defined¶: The type or instance already has been defined.

status_counter_unknown¶: The counter instance is unknown.

status_counter_type_unknown¶: The counter type is unknown.

status_generic_error¶: A unknown error occurred.

status_valid_data: No error occurred, data is valid.

status_new_data: Data is valid and different from last call.

status_invalid_data: Some error occurred, data is not value.

status_already_defined: The type or instance already has been defined.

status_counter_unknown: The counter instance is unknown.

status_counter_type_unknown: The counter type is unknown.

status_generic_error: A unknown error occurred.

Functions

std::string &ensure_counter_prefix(std::string &name)¶

std::string ensure_counter_prefix(std::string const &counter)¶

std::string &remove_counter_prefix(std::string &name)¶

std::string remove_counter_prefix(std::string const &counter)¶

char const *get_counter_type_name(counter_type state)¶: Return the readable name of a given counter type.

bool status_is_valid(counter_status s)¶

counter_status add_counter_type(counter_info const &info, error_code &ec)¶

hpx::id_type get_counter(std::string const &name, error_code &ec)¶

hpx::id_type get_counter(counter_info const &info, error_code &ec)¶

Variables

constexpr const char counter_prefix[] = "/counters"¶

constexpr std::size_t counter_prefix_len = (sizeof(counter_prefix) / sizeof(counter_prefix[0])) - 1¶

struct counter_info¶

Public Functions

counter_info(counter_type type = counter_type::raw)¶

counter_info(std::string const &name)¶

counter_info(counter_type type, std::string const &name, std::string const &helptext = "", std::uint32_t version = HPX_PERFORMANCE_COUNTER_V1, std::string const &uom = "")¶

Public Members

counter_type type_¶: The type of the described counter.

std::uint32_t version_¶: The version of the described counter using the 0xMMmmSSSS scheme

counter_status status_¶: The status of the counter object.

std::string fullname_¶: The full name of this counter.

std::string helptext_¶: The full descriptive text for this counter.

std::string unit_of_measure_¶: The unit of measure for this counter.

Private Functions

void serialize(serialization::output_archive &ar, const unsigned int)¶

void serialize(serialization::input_archive &ar, const unsigned int)¶

Friends

friend hpx::performance_counters::hpx::serialization::access

struct counter_path_elements : public hpx::performance_counters::counter_type_path_elements ¶

#include <counters.hpp>

A counter_path_elements holds the elements of a full name for a counter instance. Generally, a full name of a counter instance has the structure:

/objectname{parentinstancename::parentindex/instancename#instanceindex} /countername#parameters

i.e. /queue{localityprefix/thread#2}/length

Public Types

typedef counter_type_path_elements base_type¶

Public Functions

counter_path_elements()¶

counter_path_elements(std::string const &objectname, std::string const &countername, std::string const &parameters, std::string const &parentname, std::string const &instancename, std::int64_t parentindex = -1, std::int64_t instanceindex = -1, bool parentinstance_is_basename = false)¶

counter_path_elements(std::string const &objectname, std::string const &countername, std::string const &parameters, std::string const &parentname, std::string const &instancename, std::string const &subinstancename, std::int64_t parentindex = -1, std::int64_t instanceindex = -1, std::int64_t subinstanceindex = -1, bool parentinstance_is_basename = false)¶

Public Members

std::string parentinstancename_¶: the name of the parent instance

std::string instancename_¶: the name of the object instance

std::string subinstancename_¶: the name of the object sub-instance

std::int64_t parentinstanceindex_¶: the parent instance index

std::int64_t instanceindex_¶: the instance index

std::int64_t subinstanceindex_¶: the sub-instance index

bool parentinstance_is_basename_¶: the parentinstancename_

Private Functions

void serialize(serialization::output_archive &ar, const unsigned int)¶

void serialize(serialization::input_archive &ar, const unsigned int)¶

Friends

friend hpx::performance_counters::hpx::serialization::access: member holds a base counter name

struct counter_type_path_elements¶

#include <counters.hpp>

A counter_type_path_elements holds the elements of a full name for a counter type. Generally, a full name of a counter type has the structure:

/objectname/countername

i.e. /queue/length

Subclassed by hpx::performance_counters::counter_path_elements

Public Functions

counter_type_path_elements()¶

counter_type_path_elements(std::string const &objectname, std::string const &countername, std::string const &parameters)¶

Public Members

std::string objectname_¶: the name of the performance object

std::string countername_¶: contains the counter name

std::string parameters_¶: optional parameters for the counter instance

Protected Functions

void serialize(serialization::output_archive &ar, const unsigned int)¶

void serialize(serialization::input_archive &ar, const unsigned int)¶

Friends

friend hpx::performance_counters::hpx::serialization::access