balm_metricregistry

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Alternative Systems for Telemetry
  • Thread Safety
  • Usage
    • Example 1: Basic Usage

Purpose

Provide a registry for metrics.

Classes

• balm::MetricRegistry: a registry for metrics

See also

balm_metricsmanager, 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

This section illustrates intended use of this component.

Example 1: Basic 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());