balm_metricid

Detailed Description

Outline

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

Purpose

Provide an identifier for a metric.

Classes

• balm::MetricId: an identifier for a metric

See also

balm_metricregistry, balm_metricdescription, 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

This section illustrates intended use of this component.

Example 1: Basic 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!