Component balm_collector [Package balm]

Provide a container for collecting and aggregating metric values. More...

Namespaces
namespace	balm

---

Detailed Description

Outline

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

Purpose:

Provide a container for collecting and aggregating metric values.

Classes:

balm::Collector

a container for collecting and aggregating metric values

See also:

Component balm_collectorrepository, Component balm_metric

Description:

This component provides a class for collecting and aggregating the values of a metric. The collector records the number of times an event occurs as well as an associated measurement value. This component does not define what constitutes an event or what the value measures. The collector manages, in a thread-safe manner, the count of event occurrences and the aggregated minimum, maximum, and total of the measured metric value. This collector class provides operations to update the aggregated value, a load operator to populate a balm::MetricRecord with the current state of the collector, a reset method to reset the current state of the collector, and finally a combined loadAndReset method that performs both a load and a reset as an atomic operation. Note that in practice, most clients should not need to access a balm::Collector directly, but instead use it through another type (see balm_metric).

Alternative Systems for Telemetry:

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

Thread Safety:

balm::Collector is fully thread-safe, meaning that all non-creator operations on a given instance can be safely invoked simultaneously from multiple threads.

Usage:

The following example creates a balm::Collector, modifies its values, then collects a balm::MetricRecord.

We start by creating a balm::MetricId object by hand, but in practice, an id should be obtained from a balm::MetricRegistry object (such as the one owned by a balm::MetricsManager):

  balm::Category           myCategory("MyCategory");
  balm::MetricDescription  description(&myCategory, "MyMetric");
  balm::MetricId           myMetric(&description);

Now we create a balm::Collector object for myMetric and use the update method to update its collected value:

  balm::Collector collector(myMetric);

  collector.update(1.0);
  collector.update(3.0);

The collector accumulated the values 1 and 3. The result should have a count of 2, a total of 4 (3 + 1), a max of 3 (max(3, 1)), and a min of 1 (min(3, 1)).

  balm::MetricRecord record;
  collector.loadAndReset(&record);

      assert(myMetric == record.metricId());
      assert(2        == record.count());
      assert(4        == record.total());
      assert(1.0      == record.min());
      assert(3.0      == record.max());