balm_collector

Detailed Description

Outline

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

Purpose

Provide a container for collecting and aggregating metric values.

Classes

• balm::Collector: a container for collecting and aggregating metric values

See also

balm_collectorrepository, 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

This section illustrates intended use of this component.

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