balm_integercollector

Detailed Description

Outline

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

This section illustrates intended use of this component.

Example 1: Basic 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());