#include <balm_metricsmanager.h>
List of all members.
Public Types |
| enum | { e_INVALID_HANDLE = -1,
BAEM_INVALID_HANDLE = e_INVALID_HANDLE
} |
typedef bsl::function< void(bsl::vector
< MetricRecord > *, bool) | RecordsCollectionCallback ) |
| typedef int | CallbackHandle |
Public Member Functions |
| | BSLMF_NESTED_TRAIT_DECLARATION (MetricsManager, bslma::UsesBslmaAllocator) |
| | MetricsManager (bslma::Allocator *basicAllocator=0) |
| | ~MetricsManager () |
| CallbackHandle | registerCollectionCallback (const char *categoryName, const RecordsCollectionCallback &callback) |
| CallbackHandle | registerCollectionCallback (const Category *category, const RecordsCollectionCallback &callback) |
| int | removeCollectionCallback (CallbackHandle handle) |
| int | addGeneralPublisher (const bsl::shared_ptr< Publisher > &publisher) |
| int | addSpecificPublisher (const char *categoryName, const bsl::shared_ptr< Publisher > &publisher) |
| int | addSpecificPublisher (const Category *category, const bsl::shared_ptr< Publisher > &publisher) |
| int | removePublisher (const Publisher *publisher) |
| int | removePublisher (const bsl::shared_ptr< Publisher > &publisher) |
| CollectorRepository & | collectorRepository () |
| MetricRegistry & | metricRegistry () |
| void | collectSample (MetricSample *sample, bsl::vector< MetricRecord > *records, bool resetFlag=false) |
| void | collectSample (MetricSample *sample, bsl::vector< MetricRecord > *records, const Category *const categories[], int numCategories, bool resetFlag=false) |
| void | publish (const Category *category, bool resetFlag=true) |
| void | publish (const Category *const categories[], int numCategories, bool resetFlag=true) |
| void | publish (const bsl::set< const Category * > &categories, bool resetFlag=true) |
| void | publish (const std::set< const Category * > &categories, bool resetFlag=true) |
| void | publishAll (bool resetFlag=true) |
| void | publishAll (const bsl::set< const Category * > &excludedCategories, bool resetFlag=true) |
| void | publishAll (const std::set< const Category * > &excludedCategories, bool resetFlag=true) |
| void | setCategoryEnabled (const char *category, bool isEnabled=true) |
| void | setCategoryEnabled (const Category *category, bool value=true) |
| void | setAllCategoriesEnabled (bool value) |
| int | findGeneralPublishers (bsl::vector< Publisher * > *publishers) const |
| int | findGeneralPublishers (std::vector< Publisher * > *publishers) const |
| int | findSpecificPublishers (bsl::vector< Publisher * > *publishers, const char *categoryName) const |
| int | findSpecificPublishers (std::vector< Publisher * > *publishers, const char *categoryName) const |
| int | findSpecificPublishers (bsl::vector< Publisher * > *publishers, const Category *category) const |
| int | findSpecificPublishers (std::vector< Publisher * > *publishers, const Category *category) const |
| const CollectorRepository & | collectorRepository () const |
| const MetricRegistry & | metricRegistry () const |
Friends |
| struct | MetricsManager_PublicationHelper |
Detailed Description
This class implements a manager for the recording and publishing of metrics. Metrics managed by a MetricsManager are grouped into categories identified by a string. The metrics manager allows clients to register a Publisher object using the addGeneralPublisher and addSpecificPublisher operations. Metrics can be recorded in one of two ways: Clients can (1) implement their own metric collection facilities and register a callback using this metric manager's registerMetricsCallback method; or (2) use the Collector objects available from the CollectorRepository owned by this metrics manager.
See Component balm_metricsmanager
Member Typedef Documentation
RecordsCollectionCallback is an alias for a callback function that appends to the supplied MetricRecord vector the values of the collected metrics, and, if the provided bool is true, resets those metrics to their default values. Clients can register callbacks matching this prototype with the metrics manager. Here is an example prototype matching this callback:
Member Enumeration Documentation
- Enumerator:
| e_INVALID_HANDLE |
an invalid callback handle
|
| BAEM_INVALID_HANDLE |
|
Constructor & Destructor Documentation
| balm::MetricsManager::MetricsManager |
( |
bslma::Allocator * |
basicAllocator = 0 |
) |
[explicit] |
Create a MetricsManager. Optionally specify a basicAllocator used to supply memory. If basicAllocator is 0, the currently installed default allocator is used.
| balm::MetricsManager::~MetricsManager |
( |
|
) |
|
Member Function Documentation
Register the specified callback to collect records for the category having the specified categoryName, and return an opaque integer handle that can be used later to remove the callback. The supplied callback will be called to collect metrics from the identified category each time the category is published or collected, even if the category is disabled. If the publish or collectSample method is called on the identified category, and the category is disabled, the callback will be invoked so clients may update any internal state, but the collected metrics will be ignored. Clients that wish to avoid overhead associated with collecting metrics for a disabled category must test (within their code) whether the category is disabled. The behavior is undefined if the callback returns metrics belonging to metric categories other than the one identified by categoryName, or if categoryName is not null-terminated. Note that the same callback can be registered for a category multiple times, and that registering the same callback multiple times will result in an equal number of invocations of the callback when publishing the category.
Register the specified callback to collect records for the specified category, and return an opaque integer handle that can be used later to remove the callback. The supplied callback will be called to collect metrics from category each time category is published, even if category is disabled (i.e., category->enabled() is false). If the publish method is called on category and category is disabled, the callback will be invoked so clients may update any internal state, but the collected metrics will be ignored. Clients that wish to avoid overhead associated with collecting metrics for a disabled category must test (within their code) whether the category is disabled. The behavior is undefined if the callback returns metrics belonging to metric categories other than category. Note that the same callback can be registered for a category multiple times, and that registering the same callback multiple times will result in an equal number of invocations of the callback when publishing the category.
| int balm::MetricsManager::removeCollectionCallback |
( |
CallbackHandle |
handle |
) |
|
Remove the callback associated with the specified handle. Return 0 on success, or a non-zero value if handle cannot be found.
Add the specified publisher to the set of publishers that will be used to propagate records for every category published by this metrics manager. Return 0 on success, and a non-zero value with no effect if publisher has already been registered. After this method returns, any category published by this metrics manager will be published to publisher. Note that this method will have no effect and return a non-zero value if publisher was previously registered for one or more specific categories (using the alternative addSpecificPublisher method).
| int balm::MetricsManager::addSpecificPublisher |
( |
const char * |
categoryName, |
|
|
const bsl::shared_ptr< Publisher > & |
publisher | |
|
) |
| | |
Add the specified publisher to the set of publishers that will be used to publish metrics for the category identified by the specified categoryName. Return 0 on success, and a non-zero value with no effect if publisher has already been registered to publish the identified category. The behavior is undefined unless categoryName is null-terminated. Note that this method will fail and return a non-zero value if publisher has previously been registered to publish every category (using the alternative addGeneralPublisher method).
Add the specified publisher to the set of publishers that will be used to publish metrics for the specified category. Return 0 on success, and a non-zero value with no effect if publisher has already been registered to publish category. The behavior is undefined unless category is a valid address returned by the metricRegistry method. Note that this method will fail and return a non-zero value if publisher has previously been registered to publish every category (using the alternative addGeneralPublisher method).
| int balm::MetricsManager::removePublisher |
( |
const Publisher * |
publisher |
) |
|
Stop publishing metrics to the specified publisher (for each category), and remove it from this metrics manager. Return 0 on success, and a non-zero value if publisher cannot be found.
Return a reference to the modifiable repository of collectors managed by this object.
Return a reference to the modifiable registry of metrics managed by this object.
Load into the specified sample a metric sample collected from the indicated categories, and append to records those collected records which are referred to by sample. Optionally specify a sequence of categories of length numCategories. If a sequence of categories is not supplied, a sample is collected from all registered categories. Optionally specify a resetFlag that determines if the collected metrics are reset as part of this operation. This operation will collect aggregated metric values for each enabled category in the indicated categories from registered callbacks as well as from its own CollectorRepository, and then append those values to records and update sample with the addresses of those collected records. If resetFlag is true, the metrics being collected are reset to their default state. This operation also populates the sample with the time interval is computed as the elapsed time since the interval over which the sampled metrics were collected. This last time the metrics were reset (either through a call to the publish or collectSample methods). If category has not previously been reset then this interval is taken to be the elapsed time since the creation of this metrics manager. The behavior is undefined unless 0 <= numCategories, categories refers to a contiguous sequence of (at least) numCategories, and each category in categories appears only once. Note that sample is loaded with the addresses of the metric records appended to records, and modifying records after this call returns may invalidate sample.
| void balm::MetricsManager::publish |
( |
const Category * |
category, |
|
|
bool |
resetFlag = true | |
|
) |
| | |
Publish metrics associated with the specified category if category is enabled; otherwise (if category is not enabled) this method has no effect. Optionally specify a resetFlag that determines if the collected metrics are reset as part of this operation. If category is enabled (i.e., category->isEnabled() is true), this operation will collect aggregated metric values for category from any registered callbacks as well as from its own CollectorRepository, and then publish those records using any publishers associated with category. If resetFlag is true, the metrics being collected are reset to their default state. The metrics manager provides publishers the time interval over which the published metrics were collected. This interval is computed as the elapsed time since the last time the category was reset (either through a call to the publish or collectSample methods). If category has not previously been reset then this interval is taken to be the elapsed time since the creation of this metrics manager. Note that the alternative publish methods that publish multiple categories in a single invocation are more efficient than publishing a sequence of categories individually.
| void balm::MetricsManager::publish |
( |
const Category *const |
categories[], |
|
|
int |
numCategories, |
|
|
bool |
resetFlag = true | |
|
) |
| | |
Publish metrics belonging to the specified sequence of (unique) categories, of specified length numCategories. Optionally specify a resetFlag that determines if the collected metrics are reset as part of this operation. This operation will collect aggregated metric values for each enabled category in categories from registered callbacks as well as from its own CollectorRepository, and then publish those records using any publishers associated with the category. Any individual category in categories that is not enabled is ignored. If resetFlag is true, the metrics being collected are reset to their default state. The metrics manager provides publishers the time interval over which the published metrics were collected. This interval is computed as the elapsed time since the last time the category was reset (either through a call to the publish or collectSample methods). If a category has not previously been reset then this interval is taken to be the elapsed time since the creation of this metrics manager. The behavior is undefined unless 0 <= numCategories, categories refers to a contiguous sequence of (at least) numCategories, and each category in categories appears only once.
| void balm::MetricsManager::publish |
( |
const bsl::set< const Category * > & |
categories, |
|
|
bool |
resetFlag = true | |
|
) |
| | |
| void balm::MetricsManager::publish |
( |
const std::set< const Category * > & |
categories, |
|
|
bool |
resetFlag = true | |
|
) |
| | |
Publish metrics belonging to the specified categories. Optionally specify a resetFlag that determines if the metrics are reset as part of this operation. This operation will collect aggregated metric values for each enabled category in categories from registered callbacks as well as from its own CollectorRepository, and then publish those records using any publishers associated with the category. Any category in categories that is not enabled is ignored. If resetFlag is true, the metrics being collected are reset to their default state. The metrics manager provides publishers the time interval over which the published metrics were collected. This interval is computed as the elapsed time since the last time the category was reset (either through a call to the publish or collectSample methods). If a category has not previously been reset then this interval is taken to be the elapsed time since the creation of this metrics manager.
| void balm::MetricsManager::publishAll |
( |
bool |
resetFlag = true |
) |
|
Publish metrics for every category registered with the contained MetricsRegistry object. Optionally specify a resetFlag that determines if the metrics are reset as part of this operation. This operation will collect aggregated metric values for each enabled category in its metricRegistry() from registered callbacks as well as from its own CollectorRepository, and then publish those records using any publishers associated with the category. Any category that is not enabled is ignored. If resetFlag is true, the metrics being collected are reset to their default state. The metrics manager provides publishers the time interval over which a published category of metrics were collected. This interval is computed as the elapsed time since the last time the category was reset (either through a call to the publish or collectSample methods). If a category has not previously been reset then this interval is taken to be the elapsed time since the creation of this metrics manager.
| void balm::MetricsManager::publishAll |
( |
const bsl::set< const Category * > & |
excludedCategories, |
|
|
bool |
resetFlag = true | |
|
) |
| | |
| void balm::MetricsManager::publishAll |
( |
const std::set< const Category * > & |
excludedCategories, |
|
|
bool |
resetFlag = true | |
|
) |
| | |
Publish metrics for every category registered with the contained MetricsRegistry object, except for the specified excludedCategories. Optionally specify a resetFlag that determines if the metrics are reset as part of this operation. This operation will collect aggregated metric values for each enabled category in its metricRegistry() (that is not in excludedCategories) from registered callbacks as well as from its own CollectorRepository, and then publish those records using any publishers associated with the category. Any category that is not enabled is ignored. If resetFlag is true, the metrics being collected are reset to their default state. The metrics manager provides publishers the time interval over which a published category of metrics were collected. This interval is computed as the elapsed time since the last time the category was reset (either through a call to the publish or collectSample methods). If a category has not previously been reset then this interval is taken to be the elapsed time since the creation of this metrics manager.
| void balm::MetricsManager::setCategoryEnabled |
( |
const char * |
category, |
|
|
bool |
isEnabled = true | |
|
) |
| | |
Set whether the specified category is enabled to the optionally specified isEnabled value. If category has not been registered, register it with the metricRegistry(). If a category is disabled it will not be published (see the publish methods), and higher level components may not record values for metrics belonging to the category (for an example, see the balm_metric documentation). Note that this operation is not atomic, and other threads may simultaneously access the current enabled value for category while this operation is performed. Also note that this operation has linear performance with respect to the number of registered category holders for category (see balm_metricregistry and balm_category for information on category holders).
| void balm::MetricsManager::setCategoryEnabled |
( |
const Category * |
category, |
|
|
bool |
value = true | |
|
) |
| | |
Set whether the specified category is enabled to the optionally specified value. If a category is disabled it will not be published (see the publish methods), and higher level components may not record values for metrics belonging to the category (for an example, see the balm_metric documentation). The behavior is undefined unless category is a valid address of a category previously returned by the metric registry owned by this MetricManager object (i.e., metricRegistry()). Note that this operation is thread-safe, but not atomic: Other threads may simultaneously access the current enabled value for category while this operation is performed. Also note that this operation has linear performance with respect to the number of registered category holders for category (see balm_metricregistry and balm_category for information on category holders).
| void balm::MetricsManager::setAllCategoriesEnabled |
( |
bool |
value |
) |
|
Set whether each category currently registered with metricRegistry() is enabled to the specified value, and ensure that categories registered after this call are initialized as either enabled or disabled, accordingly. If a category is disabled it will not be published (see the publish methods), and higher level components may not record values for metrics belonging to the category (for an example, see the balm_metric documentation). This operation is logically equivalent to iterating over the list of categories currently registered with metricRegistry() and calling setCategoryEnabled on each category individually, and also setting a default isEnabled() value (for newly-created categories). Hence, subsequent calls to setCategoryEnabled will override this value for a particular category. Note that this operation is thread-safe, but not atomic: Other threads may simultaneously access the current enabled status for a category while this operation completes. Also note that this operation has linear runtime performance with respect to the total number of category holders registered with metricRegistry() (see balm_metricregistry and balm_category for information on category holders).
| int balm::MetricsManager::findGeneralPublishers |
( |
std::vector< Publisher * > * |
publishers |
) |
const |
Append to the specified publishers the addresses of publishers registered to publish metrics for every category. Return the number of publishers found. Note that this method will not find publishers associated with individual categories (i.e., category specific publishers).
| int balm::MetricsManager::findSpecificPublishers |
( |
bsl::vector< Publisher * > * |
publishers, |
|
|
const char * |
categoryName | |
|
) |
| | const |
| int balm::MetricsManager::findSpecificPublishers |
( |
std::vector< Publisher * > * |
publishers, |
|
|
const char * |
categoryName | |
|
) |
| | const |
Append to the specified publishers the addresses of any publishers associated with the (particular) category identified by the specified categoryName. Return the number of publishers found for the category. The behavior is undefined unless category is null-terminated. Note that this method will not find publishers registered for every category (i.e., general publishers)
| int balm::MetricsManager::findSpecificPublishers |
( |
std::vector< Publisher * > * |
publishers, |
|
|
const Category * |
category | |
|
) |
| | const |
Append to the specified publishers the addresses of any publishers associated with the (particular) specified category. Return the number of publishers found for the category. The behavior is undefined unless category is a valid address supplied by metricRegistry(). Note that this method will not find publishers registered for every category (i.e., general publishers).
Return a reference to the non-modifiable repository of collectors managed by this object.
Return a reference to the non-modifiable registry of metrics managed by this object.
Friends And Related Function Documentation
friend struct MetricsManager_PublicationHelper [friend] |
The documentation for this class was generated from the following file:
