[#BloombergLP-balm]
= xref:BloombergLP.adoc[BloombergLP]::balm
:relfileprefix: ../
:mrdocs:

Package namespace for metrics components.

== Types

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/balm/BdlmMetricsAdapter.adoc[`BdlmMetricsAdapter`] 
| This class implements a pure abstract interface for clients and suppliers of metrics adapters. The implementation registers callbacks with a provided `balm::MetricsManager` to enable monitoring of statistics collection objects.
| xref:BloombergLP/balm/Category.adoc[`Category`] 
| This class provides a mechanism for representing a category. A category is an identifier used to group related metrics. A `Category` object contains the address of a null‐terminated string, `name`, holding the name of the category and a boolean value, `enabled`, indicating whether the category is currently enabled.
| xref:BloombergLP/balm/CategoryHolder.adoc[`CategoryHolder`] 
| This class, informally referred to as a "category holder" (or simply "holder"), holds a category, an enabled value, and a pointer to a "next" holder. Both the category and next pointer may be null. The intended use is as follows: (1) instances of this class are (only) declared in contexts where collecting a metric occurs; (2) if the enabled value is true, the category contains the address of a valid, enabled, category; (3) if the next pointer is non‐null, then the holder pointed to holds the same category and threshold. Instances of this class must be _statically_ initializable. Hence, the data members are `public`, and no constructors or destructor are defined.
| xref:BloombergLP/balm/Collector.adoc[`Collector`] 
| This class provides a mechanism for collecting and aggregating the value of a metric over a period of time. The collector contains a `MetricRecord` object that holds the identity of the metric being collected, the number of times an event occurred, and the total, minimum, and maximum aggregates of the associated measurement value. The default value for the count is 0, the default value for the total is 0.0, the default minimum value is `MetricRecord::k_DEFAULT_MIN`, and the default maximum value is `MetricRecord::k_DEFAULT_MAX`.
| xref:BloombergLP/balm/CollectorRepository.adoc[`CollectorRepository`] 
| This class defines a fully thread‐safe repository mechanism for `Collector` and `IntegerCollector` objects. Collectors are identified in the repository by a `MetricId` object and also grouped together according to the category of the metric. This repository supports operations to create, find, and collect metric records from the collectors in the repository.
| xref:BloombergLP/balm/CollectorRepository_MetricCollectors.adoc[`CollectorRepository_MetricCollectors`] 
| Private implementation type holding collectors for a single metric id.
| xref:BloombergLP/balm/ConfigurationUtil.adoc[`ConfigurationUtil`] 
| This `struct` provides utilities for configuring metrics.
| xref:BloombergLP/balm/DefaultMetricsManager.adoc[`DefaultMetricsManager`] 
| This struct provides a namespace for static functions that create, access, and destroy the default instance of the `MetricsManager`. The expected usage is that the default instance will be created during the initialization of an application (while the task has a single thread) and that it will be destroyed just prior to termination (when there is similarly a single thread).
| xref:BloombergLP/balm/DefaultMetricsManagerScopedGuard.adoc[`DefaultMetricsManagerScopedGuard`] 
| This class implements a scoped guard that, on construction, creates the default instance of the metrics manager, and, on destruction, destroys that instance. Note that the behavior is undefined if the default instance of the metrics manager is created before creating this guard, or if the default instance is externally destroyed before destroying this guard.
| xref:BloombergLP/balm/IntegerCollector.adoc[`IntegerCollector`] 
| This class provides a mechanism for collecting and aggregating the value of an integer metric over a period of time. The collector contains a `MetricId` object identifying the metric being collected, the number of times an event occurred, and the total, minimum, and maximum aggregates of the associated measurement value. The default value for the count is 0, the default value for the total is 0, the default value for the minimum is `k_DEFAULT_MIN`, and the default value for the maximum is `k_DEFAULT_MAX`.
| xref:BloombergLP/balm/IntegerMetric.adoc[`IntegerMetric`] 
| This class provides an in‐core value semantic type for recording and aggregating the values of an integer metric. The value of a `IntegerMetric` object is characterized by the `IntegerCollector` object it uses to collect metric‐event values. Each instance of this class establishes (at construction) an association to an `IntegerCollector` object to which the metric delegates. A `IntegerMetric` value is constant after construction (i.e., it does not support assignment or provide manipulators that modify its collector value), so that synchronization primitives are not required to protect its data members. Note that if a collector or metrics manager is not supplied at construction, and if the default metrics manager has not been instantiated, then the metric will be inactive (i.e., `isActive()` is `false`) and the manipulator methods of the integer metric object will have no effect.
| xref:BloombergLP/balm/IntegerMetric_MacroImp.adoc[`IntegerMetric_MacroImp`] 
| This structure provides a namespace for functions used to implement the macros defined by this component.
| xref:BloombergLP/balm/Metric.adoc[`Metric`] 
| This class provides an in‐core value semantic type for recording and aggregating the values of a metric. The value of a `Metric` object is characterized by the `Collector` object it uses to collect metric‐event values. Each instance of this class establishes (at construction) an association to a `Collector` object to which the metric delegates. A `Metric` value is constant after construction (i.e., it does not support assignment or provide manipulators that modify its collector value) so that synchronization primitives are not required to protect its data members. Note that if a collector or metrics manager is not supplied at construction, and if the default metrics manager has not been instantiated, then the metric will be inactive (i.e., `isActive() == false`) and the manipulator methods of the metric object will have no effect.
| xref:BloombergLP/balm/MetricDescription.adoc[`MetricDescription`] 
| This class provides a mechanism for describing a metric. A `MetricDescription` holds the category to which the metric belongs, and a null‐terminated string containing the name of the metric.
| xref:BloombergLP/balm/MetricFormat.adoc[`MetricFormat`] 
| This class provides a value‐semantic description for the formatting of a metric. For each published aggregate type of a metric (e.g., count, total, min, max, etc.), a `MetricFormat` contains a `MetricFormatSpec` object describing how to format values of that aggregate, or null if no formatting information is supplied. `Metricformat` provides the `setFormatSpec` method to set the format spec for a publication type, and the `formatSpec` method to retrieve the format spec for a publication type (or 0 if no format spec has been provided for the indicated publication type). Note that the types of published aggregates explicitly provided by the `balm` package are defined in the `PublicationType` enumeration.
| xref:BloombergLP/balm/MetricFormatSpec.adoc[`MetricFormatSpec`] 
| This class provides a value‐semantic representation of the formatting specification for a metric aggregate value. The `scale()` is a multiplier used to scale the numeric value. The `format()` is a `printf`‐style format string suitable for formatting a single floating‐point value.
| xref:BloombergLP/balm/MetricId.adoc[`MetricId`] 
| This class defines an in‐core value‐semantic type used to identify a metric. A `MetricId` object's value is the _address_ of a non‐modifiable `MetricDescription` object. In addition, a `MetricDescription` object provides auxiliary methods, `category`, `categoryName`, and `name`, that enable access to the properties of the held `MetricDescription`. Two `MetricId` objects have the same value if the values of their respective `MetricDescription` object _addresses_ are the same.
| xref:BloombergLP/balm/MetricRecord.adoc[`MetricRecord`] 
| Each instance of this class represents the aggregated value of a metric. A metric record contains a `MetricId` object (identifying the metric), the number of times the measured event has occurred as well as the minimum, maximum, and total of the measured value. The default `metricId` is the invalid id value, the default `count` is 0, the defined `k_DEFAULT_MIN` constant (the representation for positive default `total` is 0.0, the default `min` is the infinity), and the default `max` is the defined `k_DEFAULT_MAX` constant (the representation for negative infinity).
| xref:BloombergLP/balm/MetricRegistry.adoc[`MetricRegistry`] 
| The class defines a thread‐aware mechanism for registering metrics and metric categories. A metric is uniquely identified by its name and category, and the metric registry provides a mapping from those identifying properties to a `balm::MetricId`. A `balm::MetricRegistry` object also provides a mapping from a category name to the address of a non‐modifiable `balm::Category` object.
| xref:BloombergLP/balm/MetricSample.adoc[`MetricSample`] 
| This class provides an _in‐core_ value‐semantic representation of a sample of metric values. The class contains a collection of addresses to (external) `MetricRecord` objects holding the values for their respective metrics (aggregated over some period of time). The metric records contained by a sample are broken into a series of groups, which are represented by `MetricSampleGroup` objects. Each group contains a sequence of records and an elapsed time value, indicating the period of time over which those records were taken. This class also provides a timestamp value, used to indicate when the sample was collected. The class provides a method, `appendGroups`, that appends a group of metric records to the sample. Arrays supplied using `appendGroups` must be valid for the productive lifetime of the `MetricSample` object or until they are removed by calling `removeAllRecords`.
| xref:BloombergLP/balm/MetricSampleGroup.adoc[`MetricSampleGroup`] 
| This class provides an _in‐core_ value‐semantic representation of a group of metric record values. This class contains the address of an array of (externally managed) `MetricRecord` objects, the number of records in that array, and an elapsed time value (used to indicate the time span over which the metric values were aggregated).
| xref:BloombergLP/balm/Metric_MacroImp.adoc[`Metric_MacroImp`] 
| This structure provides a namespace for functions used to implement the macros defined by this component.
| xref:BloombergLP/balm/MetricsManager.adoc[`MetricsManager`] 
| 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.
| xref:BloombergLP/balm/MetricsManager_CallbackRegistry.adoc[`MetricsManager_CallbackRegistry`] 
| defined in implementation
| xref:BloombergLP/balm/MetricsManager_PublicationHelper.adoc[`MetricsManager_PublicationHelper`] 
| defined in implementation
| xref:BloombergLP/balm/MetricsManager_PublisherRegistry.adoc[`MetricsManager_PublisherRegistry`] 
| Private implementation type for the publisher registry.
| xref:BloombergLP/balm/Metrics_Helper.adoc[`Metrics_Helper`] 
| This `struct` provides a namespace for a suite of functions used in the implementation of the macros defined in this component.
| xref:BloombergLP/balm/PublicationScheduler.adoc[`PublicationScheduler`] 
| This class defines a mechanism for scheduling the periodic publication of metrics. Each publication scheduler object is supplied the address of a `MetricsManager` and a `bdlmt::TimerEventScheduler` at construction. The metrics manager is used to publish metrics, while the timer‐event scheduler provides the underlying scheduling mechanism. Metrics are scheduled for publication using the `scheduleCategory` and `setDefaultSchedule` methods. The `scheduleCategory` method schedules an individual category to be publisher periodically at the provided interval, whereas `setDefaultSchedule` schedules the periodic publication of any category not given an individual schedule. The publication scheduler will create a recurring timer for each unique time interval supplied, and will group together categories that share a common time interval into a single call to `MetricsManager::publish`. Note that it is left unspecified whether publication events that occur on a common multiple of _different_ intervals will be grouped into a single invocation of `MetricsManager::publish`.
| xref:BloombergLP/balm/PublicationScheduler_ClockData.adoc[`PublicationScheduler_ClockData`] 
| Private implementation type for clock data used by the scheduler.
| xref:BloombergLP/balm/PublicationScheduler_Proctor.adoc[`PublicationScheduler_Proctor`] 
| defined in implementation
| xref:BloombergLP/balm/PublicationType.adoc[`PublicationType`] 
| This class defines an enumeration of aggregation type that can be used to describe the published output of a metric. Concrete `Publisher` implementations may use this these types to configure their output.
| xref:BloombergLP/balm/Publisher.adoc[`Publisher`] 
| This protocol class provides a `publish` method to publish collected sample of recorded metric values. The precise meaning of publish is left to derived classes to specify.
| xref:BloombergLP/balm/StopwatchScopedGuard.adoc[`StopwatchScopedGuard`] 
| This class provides a mechanism for recording, to a metric, the elapsed time from the construction of an instance of the guard until that instance goes out of scope (and is destroyed). The constructor of this class takes an optional argument indicating the time units in which to report the elapsed time; by default a guard will report time in seconds. The supplied time units determine the scale of the double value reported by this guard, but does _not_ affect the precision of the elapsed time measurement. Each instance of this class delegates to a `Collector` for the metric. This `Collector` is initialized on construction based on the constructor arguments. If this scoped guard is not initialized with an active metric, or if the supplied metric becomes inactive before the scoped guard is destroyed, then `isActive()` will return `false` and no metric values will be recorded. Note that if the metric supplied at construction is not active when the scoped guard is constructed, the scoped guard will not become active or record metric values regardless of the future state of that supplied metric.
| xref:BloombergLP/balm/StreamPublisher.adoc[`StreamPublisher`] 
| This class provides an implementation of the `Publisher` protocol. This stream publisher publishes recorded metric values to an output stream specified at construction.
|===


== Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/balm/operator_lshift-09.adoc[`operator<<`] 
| Stream insertion operators
| xref:BloombergLP/balm/operator_eq-03.adoc[`operator==`] 
| Equality operators
| xref:BloombergLP/balm/operator_not_eq-00.adoc[`operator!=`] 
| Inequality operators
| xref:BloombergLP/balm/operator_lt.adoc[`operator<`] 
| Return `true` if the specified `lhs` metric id is less than (ordered before) the specified `rhs` metric id, and return `false` otherwise'. The `lhs` is considered less if the (unsigned) _address_ of the contained `MetricDescription` object is numerically less than the `rhs` description. Note that this function does _not_ provide any form of alphabetic ordering, and is logically equivalent to the expression `lhs.description() < rhs.description()`.
|===



[.small]#Created with https://www.mrdocs.com[MrDocs]#