balm_metricdescription

Detailed Description

Outline

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

Purpose

Provide a description for a metric.

Classes

• balm::MetricDescription: describes a metric

See also

balm_metricregistry, balm_metricid, balm_category

Description

This component provides a class, balm::MetricDescription, used to describe a metric. A balm::MetricDescription object contains the address of the category to which the metric belongs and also the address of the null-terminated string holding the name of the metric. The balm::MetricDescription class suppresses copy construction and assignment, and does not provide equality operators: Applications should use a single balm::MetricDescription object per metric (such as one provided by the *balm::MetricRegistry* component).

IMPORTANT: The metric description's name, whose type is const char *, must remain constant and valid throughout the lifetime of the balm::MetricDescription object.

Alternative Systems for Telemetry

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

Thread Safety

balm::MetricDescription 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::MetricDescription in one thread while another thread modifies the same object. However, clients of the balm package accessing a non-modifiable balm::MetricDescription supplied by a balm::MetricRegistry (by way of a balm::MetricId) can safely access the properties of that metric description at any time.

Usage

This section illustrates intended use of this component.

Example 1: Basic Usage

The following example demonstrates how to create and access a balm::MetricDescription object. We start by creating a category:

balm::Category myCategory("MyCategory");

Then we use that category to create three metric description objects with different names:

balm::MetricDescription metricA(&myCategory, "A");
balm::MetricDescription metricB(&myCategory, "B");
balm::MetricDescription metricC(&myCategory, "C");

We can use the category and name methods to access their values:

assert(&myCategory == metricA.category());
assert(&myCategory == metricB.category());
assert(&myCategory == metricC.category());
 
assert(0 == bsl::strcmp("A", metricA.name()));
assert(0 == bsl::strcmp("B", metricB.name()));
assert(0 == bsl::strcmp("C", metricC.name()));

Finally, we write all three metric descriptions to the console:

bsl::cout << "metricA: " << metricA << bsl::endl
          << "metricB: " << metricB << bsl::endl
          << "metricC: " << metricC << bsl::endl;

With the following console output:

metricA: MyCategory.A
metricB: MyCategory.B
metricC: MyCategory.C