Component balm_metricregistry [Package balm]

Provide a registry for metrics. More...

Namespaces
namespace	balm

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Alternative Systems for Telemetry
  • Thread Safety
  • Usage

Purpose:

Provide a registry for metrics.

Classes:

balm::MetricRegistry

a registry for metrics

See also:

Component balm_metricsmanager, Component balm_metricrecord

Description:

This component defines a class, balm::MetricRegistry, that provides operations to register both metric categories and individual metrics. 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.

Alternative Systems for Telemetry:

Bloomberg software may alternatively use the GUTS telemetry API, which is integrated into Bloomberg infrastructure.

Thread Safety:

balm::MetricRegistry is fully thread-safe, meaning that all non-creator operations on a given object can be safely invoked simultaneously from multiple threads.

Usage:

The following example illustrates how to create and use a balm::MetricRegistry. We start by creating a balm::MetricRegistry object, registry, and then using this registry to create a balm::MetricId for a metric named "MetricA" belonging to the category "MyCategory" (i.e., "MyCategory.MetricA").

  bslma::Allocator    *allocator = bslma::Default::allocator(0);
  balm::MetricRegistry  registry(allocator);

  balm::MetricId idA = registry.addId("MyCategory", "MetricA");

Now that we have added a metric id, "MyCategory.MetricA", attempting to add the metric id again will return an invalid id. We retrieve the same identifier we have created using either getId or findId:

  balm::MetricId invalidId = registry.addId("MyCategory", "MetricA");
        assert(!invalidId.isValid());

  balm::MetricId idA_copy1 = registry.getId("MyCategory", "MetricA");
        assert(idA_copy1.isValid());
        assert(idA_copy1 == idA);

  balm::MetricId idA_copy2 = registry.findId("MyCategory", "MetricA");
        assert(idA_copy2.isValid());
        assert(idA_copy2 == idA);

We use the getId method to add a new metric to the registry, then verify we can lookup the metric:

  balm::MetricId idB = registry.getId("MyCategory", "MetricB");
        assert(idB.isValid());
        assert(idB == registry.getId("MyCategory", "MetricB"));
        assert(idB == registry.findId("MyCategory", "MetricB"));
        assert(!registry.addId("MyCategory", "MetricB").isValid());

Next we use getCategory to find the address of the balm::Category object corresponding to "MyCategory":

  const balm::Category *myCategory = registry.getCategory("MyCategory");
        assert(myCategory == idA.category());
        assert(myCategory == idB.category());
        assert(myCategory->isEnabled());

Finally we use the setCategoryEnabled method to disable the category "MyCategory":

  registry.setCategoryEnabled(myCategory, false);
        assert(!myCategory->isEnabled());