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

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.

== Synopsis

Declared in `<balm_metricregistry.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class MetricRegistry;
----

== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/balm/MetricRegistry/2constructor.adoc[`MetricRegistry`]         [.small]#[constructor]#
| Create an empty metric registry. Optionally specify a `basicAllocator` used to supply memory. If `basicAllocator` is 0, the currently installed default allocator is used.
| xref:BloombergLP/balm/MetricRegistry/2destructor.adoc[`~MetricRegistry`] [.small]#[destructor]#
| Destroy this metric registry.
| xref:BloombergLP/balm/MetricRegistry/addCategory.adoc[`addCategory`] 
| Add the specified `category` to this registry, unless it has already been registered. Return the address of the newly‐created non‐modifiable `balm::Category` object on success, and 0 otherwise. The behavior is undefined unless `category` is null‐terminated.
| xref:BloombergLP/balm/MetricRegistry/addId.adoc[`addId`] 
| Add the specified `category` and `name` to this registry, unless it has already been registered, and return a `balm::MetricId` object identifying the newly‐registered metric. If the indicated metric has already been registered, the returned `balm::MetricId` object will _not_ be valid (i.e., `isValid` will return `false`). The behavior is undefined unless `category` and `name` are null‐terminated.
| xref:BloombergLP/balm/MetricRegistry/createUserDataKey.adoc[`createUserDataKey`] 
| Return a new unique key that can be used to associate (via `setUserData`) and retrieve (via `userData`) a value with a metric (or group of metrics). Note that the returned key can be used by clients of `balm` to associate additional information with a metric.
| xref:BloombergLP/balm/MetricRegistry/findCategory.adoc[`findCategory`] 
| Find the specified `category`, a null‐terminated string, in this registry. Return the address of the non‐modifiable `balm::Category` object corresponding to the `category`, or 0 if no such category has been registered.
| xref:BloombergLP/balm/MetricRegistry/findId.adoc[`findId`] 
| Find the specified null‐terminated strings `category` and `name` in this registry. Return the `balm::MetricId` object corresponding to the metric having the `category` and `name`, if found, or an invalid metric id if no such metric has been registered (i.e., `isValid` will return `false`).
| xref:BloombergLP/balm/MetricRegistry/getAllCategories.adoc[`getAllCategories`] 
| Append to the specified `categories` the addresses of all the categories registered by this `balm::MetricRegistry` object.
| xref:BloombergLP/balm/MetricRegistry/getCategory.adoc[`getCategory`] 
| Return the address of the non‐modifiable `balm::Category` object for the specified `category`. If no corresponding category exists, register a new category and return the address of the newly‐created `balm::Category` object. The behavior is undefined unless `category` is null‐terminated. Note that this operation is guaranteed to return a valid address.
| xref:BloombergLP/balm/MetricRegistry/getId.adoc[`getId`] 
| Return a `balm::MetricId` object for the metric identified by the specified `category` and `name`. If no corresponding metric has already been registered, register a new metric and return a `balm::MetricId` object identifying that newly‐registered metric. The behavior is undefined unless `category` and `name` are null‐terminated. Note that this operation is guaranteed to return a valid `balm::MetricId` object.
| xref:BloombergLP/balm/MetricRegistry/numCategories.adoc[`numCategories`] 
| Return the number of categories in this registry.
| xref:BloombergLP/balm/MetricRegistry/numMetrics.adoc[`numMetrics`] 
| Return the number of metrics in this registry.
| xref:BloombergLP/balm/MetricRegistry/print.adoc[`print`] 
| Format this object to the specified output `stream` at the (absolute value of) the optionally specified indentation `level` and return a reference to `stream`. If `level` is specified, optionally specify `spacesPerLevel`, the number of spaces per indentation level for this and all of its nested objects. If `level` is negative, suppress indentation of the first line. If `spacesPerLevel` is negative, format the entire output on one line, suppressing all but the initial indentation (as governed by `level`). If `stream` is not valid on entry, this operation has no effect.
| xref:BloombergLP/balm/MetricRegistry/registerCategoryHolder.adoc[`registerCategoryHolder`] 
| Load into the specified `holder` the address of the specified `category`, its `enabled` status, and the address of the next holder in the linked list of category holders maintained by `category` (prepending `holder` to the linked list of category holders for `category`). The supplied `category` will update the value returned by `holder‐>enabled()` when its enabled state changes, and will reset `holder` (i.e., `holder‐>reset()`) when `category` is destroyed. The behavior is undefined unless `holder` remains valid and _unmodified_ (by the client) for the lifetime of this object.
| xref:BloombergLP/balm/MetricRegistry/setAllCategoriesEnabled.adoc[`setAllCategoriesEnabled`] 
| Set whether each currently registered category is enabled to the specified `value`, and ensure that categories registered after this call are initialized as either enabled or disabled, accordingly. This operation is logically equivalent to iterating over the list of currently registered categories and calling `setCategoryEnabled` on each category individually, and also setting a default `enabled` value (for newly‐created categories). Hence, subsequent calls `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 registered categories while this operation completes. Also note that this operation has _linear_ runtime performance with respect to the total number of category holders registered with this repository.
| xref:BloombergLP/balm/MetricRegistry/setCategoryEnabled.adoc[`setCategoryEnabled`] 
| Set whether the specified `category` is enabled to the specified `value`. The behavior is undefined unless `category` is a valid address of a category previously returned by this metric registry. Note that this operation is thread‐safe, but _not_ atomic: Other threads may simultaneously access the current enabled value for `category` while this operation completes. Also note that this operation has _linear_ runtime performance with respect to the number of registered category holders for `category`.
| xref:BloombergLP/balm/MetricRegistry/setFormat.adoc[`setFormat`] 
| Set the format for the specified `metricId` to the specified `format`. Note that there is no uniform specification for how publisher implementations will interpret the supplied `format`. Also note that the format for a metric is accessed through the `balm::MetricDescription`. For example: ` metric.description()‐>format(); `
| xref:BloombergLP/balm/MetricRegistry/setPreferredPublicationType.adoc[`setPreferredPublicationType`] 
| Set the preferred publication type of the specified `metric` to the specified `type`. The preferred publication type of a metric indicates the preferred aggregate to publish for that metric, or `balm::PublicationType::UNSPECIFIED` if there is no preference. The behavior is undefined unless `metric` was previously returned by this metric registry. Note that there is no uniform definition for how publishers will interpret this value; an `UNSPECIFIED` value generally indicates that the all the collected aggregates (total, count, minimum, and maximum value) should be published. Also note that the preferred publication type is accessed through the `balm::MetricDescription` (i.e., `metric.description()‐>preferredPublicationType()`).
| xref:BloombergLP/balm/MetricRegistry/setUserData-0b.adoc[`setUserData`] 
| `setUserData` overloads
| xref:BloombergLP/balm/MetricRegistry/2conversion.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<MetricRegistry, UsesBslmaAllocator>`] 
| Declare that this type uses a `bslma` allocator.
|===



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