balm::MetricsManager Class Reference

#include <balm_metricsmanager.h>

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
	Identifies a registered RecordsCollectionCallback.

Public Member Functions
	BSLMF_NESTED_TRAIT_DECLARATION (MetricsManager, bslma::UsesBslmaAllocator)
	MetricsManager (bslma::Allocator *basicAllocator=0)
	~MetricsManager ()
	Destroy this 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 balm_metricsmanager

Member Typedef Documentation

CallbackHandle

typedef int balm::MetricsManager::CallbackHandle

RecordsCollectionCallback

typedef bsl::function<void(bsl::vector<MetricRecord> *, bool)> balm::MetricsManager::RecordsCollectionCallback

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:

void collectionCb(bsl::vector<MetricRecord> *records,
                  bool                       resetFlag);

Member Enumeration Documentation

anonymous enum

anonymous enum

Enumerator
e_INVALID_HANDLE
BAEM_INVALID_HANDLE

Constructor & Destructor Documentation

MetricsManager()

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.

~MetricsManager()

balm::MetricsManager::~MetricsManager

(

)

Member Function Documentation

addGeneralPublisher()

int balm::MetricsManager::addGeneralPublisher

(

const bsl::shared_ptr< Publisher > &

publisher

)

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).

addSpecificPublisher() [1/2]

int balm::MetricsManager::addSpecificPublisher	(	const Category *	category,
		const bsl::shared_ptr< Publisher > &	publisher
	)

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).

addSpecificPublisher() [2/2]

int balm::MetricsManager::addSpecificPublisher ( const char *  categoryName, const bsl::shared_ptr< Publisher > &  publisher  )

inline

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).

BSLMF_NESTED_TRAIT_DECLARATION()

balm::MetricsManager::BSLMF_NESTED_TRAIT_DECLARATION	(	MetricsManager	,
		bslma::UsesBslmaAllocator
	)

collectorRepository() [1/2]

CollectorRepository & balm::MetricsManager::collectorRepository ( )

inline

Return a reference to the modifiable repository of collectors managed by this object.

collectorRepository() [2/2]

const CollectorRepository & balm::MetricsManager::collectorRepository ( ) const

inline

Return a reference to the non-modifiable repository of collectors managed by this object.

collectSample() [1/2]

void balm::MetricsManager::collectSample	(	MetricSample *	sample,
		bsl::vector< MetricRecord > *	records,
		bool	resetFlag = false
	)

collectSample() [2/2]

void balm::MetricsManager::collectSample	(	MetricSample *	sample,
		bsl::vector< MetricRecord > *	records,
		const Category *const	categories[],
		int	numCategories,
		bool	resetFlag = false
	)

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.

findGeneralPublishers() [1/2]

int balm::MetricsManager::findGeneralPublishers

(

bsl::vector< Publisher * > *

publishers

)

const

findGeneralPublishers() [2/2]

int balm::MetricsManager::findGeneralPublishers

(

std::vector< Publisher * > *

publishers

)

const

findSpecificPublishers() [1/4]

int balm::MetricsManager::findSpecificPublishers	(	bsl::vector< Publisher * > *	publishers,
		const Category *	category
	)		const

findSpecificPublishers() [2/4]

int balm::MetricsManager::findSpecificPublishers ( bsl::vector< Publisher * > *  publishers, const char *  categoryName  ) const

inline

findSpecificPublishers() [3/4]

int balm::MetricsManager::findSpecificPublishers	(	std::vector< Publisher * > *	publishers,
		const Category *	category
	)		const

findSpecificPublishers() [4/4]

int balm::MetricsManager::findSpecificPublishers ( std::vector< Publisher * > *  publishers, const char *  categoryName  ) const

inline

metricRegistry() [1/2]

MetricRegistry & balm::MetricsManager::metricRegistry ( )

inline

Return a reference to the modifiable registry of metrics managed by this object.

metricRegistry() [2/2]

const MetricRegistry & balm::MetricsManager::metricRegistry ( ) const

inline

Return a reference to the non-modifiable registry of metrics managed by this object.

publish() [1/4]

void balm::MetricsManager::publish	(	const bsl::set< const Category * > &	categories,
		bool	resetFlag = true
	)

publish() [2/4]

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.

publish() [3/4]

void balm::MetricsManager::publish	(	const Category *const	categories[],
		int	numCategories,
		bool	resetFlag = true
	)

publish() [4/4]

void balm::MetricsManager::publish	(	const std::set< const Category * > &	categories,
		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.

publishAll() [1/3]

void balm::MetricsManager::publishAll

(

bool

resetFlag = true

)

publishAll() [2/3]

void balm::MetricsManager::publishAll	(	const bsl::set< const Category * > &	excludedCategories,
		bool	resetFlag = true
	)

publishAll() [3/3]

void balm::MetricsManager::publishAll	(	const std::set< const Category * > &	excludedCategories,
		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.

registerCollectionCallback() [1/2]

CallbackHandle balm::MetricsManager::registerCollectionCallback	(	const Category *	category,
		const RecordsCollectionCallback &	callback
	)

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.

registerCollectionCallback() [2/2]

MetricsManager::CallbackHandle balm::MetricsManager::registerCollectionCallback ( const char *  categoryName, const RecordsCollectionCallback &  callback  )

inline

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.

removeCollectionCallback()

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.

removePublisher() [1/2]

int balm::MetricsManager::removePublisher

(

const bsl::shared_ptr< 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.

removePublisher() [2/2]

int balm::MetricsManager::removePublisher

(

const Publisher *

publisher

)

setAllCategoriesEnabled()

void balm::MetricsManager::setAllCategoriesEnabled ( bool  value )

inline

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).

setCategoryEnabled() [1/2]

void balm::MetricsManager::setCategoryEnabled ( const Category *  category, bool  value = true  )

inline

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).

setCategoryEnabled() [2/2]

void balm::MetricsManager::setCategoryEnabled ( const char *  category, bool  isEnabled = true  )

inline

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).

Friends And Related Symbol Documentation

MetricsManager_PublicationHelper

friend struct MetricsManager_PublicationHelper

friend

---

The documentation for this class was generated from the following file:

• balm_metricsmanager.h