Component balm_integercollector [Package balm]

Provide a container for collecting integral 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 integral metric values.

Classes:

balm::IntegerCollector

a container for collecting integral values

See also:

Description:

This component provides a class for collecting and aggregating the values of an integral metric. The balm::IntegerCollector records the number of times an event occurs as well as an associated integral measurement value. This component does not define what constitutes an event or what the value measures. The collector manages, in a fully 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 method to populate a balm::MetricRecord with the current state of the collector, a reset operator to reset the current state of the integer collector, and finally a combined loadAndReset method that performs both a load and a reset in a single (atomic) operation.

Alternative Systems for Telemetry:

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

Thread Safety:

balm::IntegerCollector 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::IntegerCollector, 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::IntegerCollector object for myMetric and use the update method to update its collected value:

  balm::IntegerCollector collector(myMetric);

  collector.update(1);
  collector.update(3);

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        == record.min());
      assert(3        == record.max());