balm_metricformat

Detailed Description

Outline

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

Purpose

Provide a formatting specification for a metric.

Classes

• balm::MetricFormat: description for how to format a metric
• balm::MetricFormatSpec: specification for formatting an individual aggregate

See also

balm_metricdescription

Description

This component provides classes for describing the formatting for a metric. For each published aggregate type (e.g., count, total, min, max, etc.), a balm::MetricFormat object holds a balm::MetricFormatSpec object describing how values of that aggregate may be formatted. balm::MetricFormat provides the setFormatSpec method to set the format specification for a particular publication type, and the formatSpec method to retrieve the format specification for a publication type (or null if no format specification has been provided for the indicated publication type).

balm::MetricFormatSpec is an unconstrained pure-attribute class that represents the specification for formatting a particular publication type of a metric (e.g., total, count, min, max, etc.). The attributes held by balm::MetricFormatSpec are given in the following table:

Attribute       Type                  Description               Default
---------   ------------   ----------------------------------   -------
scale       float          multiplier for scaling value         1.0
format      const char *   'printf'-style format for 'double'   "%f"

The string provided must be a printf-style format valid for formatting a single double value.

Note that balm::Publisher implementations determine how to use the format information associated with a metric (i.e., there is no guarantee that every publisher will format a metric using its balm::MetricFormat).

Alternative Systems for Telemetry

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

Thread Safety

balm::MetricFormat 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::MetricFormat in one thread while another thread modifies the same object.

balm::MetricFormatSpec 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::MetricFormatSpec 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 configure a balm::MetricFormat. Note that clients of the balm package can set the format for a metric through balm_configurationutil or balm_metricregistry .

We start by creating a balm::MetricFormat object:

bslma::Allocator  *allocator = bslma::Default::allocator(0);
balm::MetricFormat  format(allocator);

Next we specify that average values should only be printed to two decimal places:

format.setFormatSpec(balm::PublicationType::e_AVG,
                     balm::MetricFormatSpec(1.0, "%.2f"));

Next we specify that rate values should be formatted as a percentage – i.e., multiplied by 100, and then displayed with a "%" character:

format.setFormatSpec(balm::PublicationType::e_RATE,
                     balm::MetricFormatSpec(100.0, "%.2f%%"));

We can verify that the correct format specifications have been set:

assert(balm::MetricFormatSpec(1.0, "%.2f") ==
       *format.formatSpec(balm::PublicationType::e_AVG));
assert(balm::MetricFormatSpec(100.0, "%.2f%%") ==
       *format.formatSpec(balm::PublicationType::e_RATE));
assert(0 == format.formatSpec(balm::PublicationType::e_TOTAL));

We can use the balm::MetricFormatSpec::formatValue utility function to format the value 0.055 to the console. Note however, that there is no guarantee that every implementation of balm::Publisher will format metrics in this way.

balm::MetricFormatSpec::formatValue(
   bsl::cout, .055, *format.formatSpec(balm::PublicationType::e_AVG));
bsl::cout << bsl::endl;
balm::MetricFormatSpec::formatValue(
  bsl::cout, .055, *format.formatSpec(balm::PublicationType::e_RATE));
bsl::cout << bsl::endl;

The resulting console output will be:

0.06
5.50%