Component balm_category [Package balm]

Provide a representation of a metric category. More...

Namespaces
namespace	balm

---

Detailed Description

Outline

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

Purpose:

Provide a representation of a metric category.

Classes:

balm::Category

a representation of a metric category

See also:

Component balm_metricregistry, Component balm_metricid, Component balm_metricdescription

Description:

This component provides a class, balm::Category, whose values are used to categorize collected metrics. A metric "category" is an identifier (chosen by the application) that groups together one or more metrics. A balm::Category object contains the address of a string holding the name of the category and a boolean value indicating whether the category is currently enabled. The balm::Category class suppresses copy construction and assignment, and does not provide equality operators; applications should use a single balm::Category object instance per category (such as one provided by the balm::MetricRegistry component).

IMPORTANT: The category name, whose type is const char *, must remain constant and valid throughout the lifetime of the 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::Category is generally const thread-safe, meaning that accessors may be invoked concurrently from different threads, but it is not safe to access or modify a balm::Category in one thread while another thread modifies the same object. However, it is safe to access the enabled property on one (or more) thread(s) while the object is being modified on another thread.

Usage:

The following example demonstrates how to create, access, and modify a balm::Category object. We start by creating three category objects with different names:

  balm::Category categoryA("A", true);
  balm::Category categoryB("B", false);
  balm::Category categoryC("C");

Once the category objects have been created, we can use the name and enabled methods to access their values:

  assert(0 == bsl::strcmp("A", categoryA.name()));
  assert(0 == bsl::strcmp("B", categoryB.name()));
  assert(0 == bsl::strcmp("C", categoryC.name()));

  assert( categoryA.enabled());
  assert(!categoryB.enabled());
  assert( categoryC.enabled());

Finally, we modify the enablement status of one of the categories, and then write all three categories to the console:

  categoryC.setEnabled(false);

  bsl::cout << "categoryA: " << categoryA << bsl::endl
            << "categoryB: " << categoryB << bsl::endl
            << "categoryC: " << categoryC << bsl::endl;

With the resulting console output:

  categoryA: [ A ENABLED ]
  categoryB: [ B DISABLED ]
  categoryC: [ C DISABLED ]