Component balm_metricformat [Package balm]

Provide a formatting specification for a metric. More...

Namespaces
namespace	balm

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Alternative Systems for Telemetry
  • Thread Safety
  • 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:

Component 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:

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%