Provide a container for a sample of collected metric records.
More...
Namespaces |
namespace | balm |
Detailed Description
- Outline
-
-
- Purpose:
- Provide a container for a sample of collected metric records.
-
- Classes:
-
- See also:
- Component balm_publisher, Component 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:
- 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;
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: 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
. 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. The output will look like: [ MyCategory.MetricA: 0 0 0 0 ]
[ MyCategory.MetricB: 1 2 3 4 ]
[ MyCategory.MetricC: 4 3 2 1 ]