Component balm_metricid [Package balm]

Provide an identifier for a metric. More...

Namespaces
namespace	balm

---

Detailed Description

Outline

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

Purpose:

Provide an identifier for a metric.

Classes:

balm::MetricId

an identifier for a metric

See also:

Component balm_metricregistry, Component balm_metricdescription, Component balm_category

Description:

This component implements an in-core value-semantic type used to identify a metric. A balm::MetricId object's value is the address of a (non-modifiable) balm::MetricDescription object. A balm::MetricId object also provides auxiliary methods, category, categoryName, and metricName, that enables access to the properties of the held balm::MetricDescription. Two balm::MetricId objects have the same value if the values of their respective balm::MetricDescription object addresses are the same.

Alternative Systems for Telemetry:

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

Thread Safety:

balm::MetricId is const thread-safe, meaning that accessors may be invoked concurrently from different threads, but it is not safe to access or modify a balm::MetricId in one thread while another thread modifies the same object.

Usage:

The following example demonstrates how to create and use a balm::MetricId object. We start by creating a category and two metric description objects:

  balm::Category category("MyCategory");
  balm::MetricDescription descriptionA(&category, "MetricA");
  balm::MetricDescription descriptionB(&category, "MetricB");

Now we create three balm::MetricId objects:

  balm::MetricId invalidId;
  balm::MetricId metricIdA(&descriptionA);
  balm::MetricId metricIdB(&descriptionB);

We can access and verify the properties of the balm::MetricId objects we have created:

  assert(false == invalidId.isValid());
  assert(true  == metricIdA.isValid());
  assert(true  == metricIdB.isValid());

  assert(0             == invalidId.description());
  assert(&descriptionA == metricIdA.description());
  assert(&descriptionB == metricIdB.description());

  assert(invalidId != metricIdA);
  assert(invalidId != metricIdB);
  assert(metricIdA != metricIdB);

We now verify that copies of a metric id have the same value as the original:

  balm::MetricId copyMetricIdA(metricIdA);

  assert(metricIdA == copyMetricIdA);

Note that two balm::MetricId objects that have different balm::MetricDescription object addresses are not equal, even if the descriptions have the same name and category.

  balm::MetricDescription newDescriptionB(&category, "MetricB");
  balm::MetricId          differentIdB(&newDescriptionB);

  assert(0 == bsl::strcmp(differentIdB.metricName(),metricIdB.metricName()));
  assert(differentIdB.category() == metricIdB.category());

  assert(metricIdB != differentIdB);   // The 'balm::MetricDescription'
                                       // object addresses are not equal!