balm_metricsample

Detailed Description

Outline

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

Purpose

Provide a container for a sample of collected metric records.

Classes

• balm::MetricSampleGroup: a group of records describing the same time period
• balm::MetricSample: a sample of collected metric records

See also

balm_publisher, balm_metricrecord

Description

This component provides a container used to store a sample of recorded metric information. A balm::MetricSample contains a collection of addresses to (external) balm::MetricRecord objects containing the aggregated record values for a series of metrics. The records in a sample are broken into a series of groups, each group is represented by a balm::MetricSampleGroup object. Each balm::MetricSampleGroup contains a sequence of records and an elapsed time value, indicating the time period over which those records were collected. Finally, a balm::MetricSample object contains a timestamp value used to indicate when the sample was taken.

Alternative Systems for Telemetry

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

Thread Safety

balm::MetricSample and balm::MetricSampleGroup are both const thread-safe, meaning that accessors may be invoked concurrently from different threads, but it is not safe to access or modify an object in one thread while another thread modifies the same object.

Usage

This section illustrates intended use of this component.

Example 1: Basic Usage

The following example demonstrates how to create and use a metric sample. We start by initializing several balm::MetricRecord values, which we will add to the sample. Note that in this example we create the balm::MetricId objects by hand; however, in practice ids should be obtained from a balm::MetricRegistry object (such as the one owned by a balm::MetricsManager).

bslma::Allocator *allocator = bslma::Default::allocator(0);
 
balm::Category myCategory("MyCategory");
balm::MetricDescription descA(&myCategory, "MetricA");
balm::MetricDescription descB(&myCategory, "MetricB");
balm::MetricDescription descC(&myCategory, "MetricC");
 
balm::MetricId metricA(&descA);
balm::MetricId metricB(&descB);
balm::MetricId metricC(&descC);
 
const int TZ = 0;  // UTC time zone offset
 
bdlt::DatetimeTz timeStamp(bdlt::Datetime(2008, 3, 26, 13, 30, 0, 0), TZ);
balm::MetricRecord recordA(metricA, 0, 0, 0, 0);
balm::MetricRecord recordB(metricB, 1, 2, 3, 4);
balm::MetricRecord recordC(metricC, 4, 3, 2, 1);

Now we create the two arrays of metric records whose addresses we will later add to the metric sample:

balm::MetricRecord              buffer1[] = { recordA, recordB };
bsl::vector<balm::MetricRecord> buffer2(allocator);
buffer2.push_back(recordC);

Next we create a balm::MetricSample object, sample, and set its timestamp property. Then we add two groups of records (containing the addresses of our two record arrays) to the sample we have created. Since the records were not actually collected over a period of time, we supply an arbitrary elapsed time value of 1 second and 2 seconds (respectively) for the two groups added to the sample. Note that these arrays must remain valid for the lifetime of sample.

balm::MetricSample sample(allocator);
sample.setTimeStamp(timeStamp);
sample.appendGroup(buffer1,
                   sizeof(buffer1) / sizeof(*buffer1),
                   bsls::TimeInterval(1.0));
sample.appendGroup(buffer2.data(),
                   static_cast<int>(buffer2.size()),
                   bsls::TimeInterval(2.0));

We can verify the basic properties of our sample:

     assert(timeStamp             == sample.timeStamp());
     assert(2                     == sample.numGroups());
     assert(3                     == sample.numRecords());
     assert(bsls::TimeInterval(1) == sample.sampleGroup(0).elapsedTime());
     assert(buffer1               == sample.sampleGroup(0).records());
     assert(2                     == sample.sampleGroup(0).numRecords());
     assert(bsls::TimeInterval(2) == sample.sampleGroup(1).elapsedTime());
     assert(buffer2.data()        == sample.sampleGroup(1).records());
     assert(1                     == sample.sampleGroup(1).numRecords());

Finally we can obtain an iterator over the sample's sequence of groups. In this simple example, we iterate over the groups of records in the sample and, for each group, iterate over the records in that group, writing those records to the console.

balm::MetricSample::const_iterator sampleIt = sample.begin();
for ( ; sampleIt != sample.end(); ++sampleIt) {
    balm::MetricSampleGroup::const_iterator groupIt = sampleIt->begin();
    for ( ; groupIt != sampleIt->end(); ++groupIt) {
        bsl::cout << *groupIt << bsl::endl;
    }
}

The output will look like:

[ MyCategory.MetricA: 0 0 0 0 ]
[ MyCategory.MetricB: 1 2 3 4 ]
[ MyCategory.MetricC: 4 3 2 1 ]