Component balm_metricdescription [Package balm]

Provide a description for a metric. More...

Namespaces
namespace	balm

---

Detailed Description

Outline

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

Purpose:

Provide a description for a metric.

Classes:

balm::MetricDescription

describes a metric

See also:

Component balm_metricregistry, Component balm_metricid, Component 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:

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