balm_category

Detailed Description

Outline

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

Purpose

Provide a representation of a metric category.

Classes

• balm::Category: a representation of a metric category

See also

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

This section illustrates intended use of this component.

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