balm_metricrecord

Detailed Description

Outline

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

Purpose

Provide an aggregated record of the value of a metric.

Classes

• balm::MetricRecord: an aggregated record of the value of a metric

See also

balm_metricregistry, balm_metric, balm_metricsmanager

Description

This component implements an unconstrained pure-attribute class used to represent the aggregated value of a metric. A balm::MetricRecord contains a balm::MetricId object, and a set of aggregate values summarizing the recorded values for that metric. The attributes held by balm::MetricRecord are given in the following table:

Attribute      Type                    Description             Default
----------   ---------        ---------------------------      -------
 metricId     balm::MetricId   identifies the metric            invalid id
 count        int              count of metric values           0
 total        double           total of metric values           0.0
 min          double           minimum metric value             Infinity
 max          double           maximum metric value             -Infinity

Alternative Systems for Telemetry

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

Thread Safety

balm::MetricRecord is const thread-safe, meaning that accessors may be invoked concurrently from different threads, but it is not safe to access or modify a balm::MetricRecord 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 a balm::MetricRecord can be used to describe a set of metric values. In the example we create a RequestProcessor class that collects information about the sizes of the requests it has processed. The RequestProcessor also provides a loadRequestSizeInformation method that populates a balm::MetricRecord object describing the sizes of the requests it has processed.

class RequestProcessor {
    // This class defines a request processor that provides metric
    // information about the sizes of the requests it has processed.
 
    // DATA
    unsigned int d_numRequests;       // number of requests processed
    unsigned int d_totalRequestSize;  // total size of the requests
    unsigned int d_minRequestSize;    // minimum request size
    unsigned int d_maxRequestSize;    // maximum request size
 
  public:
    // CREATORS
    RequestProcessor()
        // Create this 'RequestProcessor'.
    : d_numRequests(0)
    , d_totalRequestSize(0)
    , d_minRequestSize(INT_MAX)
    , d_maxRequestSize(0)
    {
    }
 
    // ...
 
    // MANIPULATORS
    void processRequest(const bsl::string& request)
        // Process the specified 'request'.
    {
        ++d_numRequests;
        d_totalRequestSize += static_cast<unsigned int>(request.size());
        d_minRequestSize   =  bsl::min(d_minRequestSize,
                                       (unsigned int)request.size());
        d_maxRequestSize   =  bsl::max(d_maxRequestSize,
                                       (unsigned int)request.size());
 
        // Process the request.
    }

Now we declare a function that populates a balm::MetricRecord describing the sizes of the requests that the request processor has processed:

    // ACCESSORS
    void loadRequestSizeInformation(balm::MetricRecord *record) const
        // Populate the specified 'record' with information regarding
        // the sizes of the requests that have been processed by this
        // object.
    {
        if (0 < d_numRequests) {
            record->count()  = d_numRequests;
            record->total()  = d_totalRequestSize;
            record->min()    = d_minRequestSize;
            record->max()    = d_maxRequestSize;
        }
    }
 
    // ...
 
};

We can create an instance of this RequestProcessor class and use it to process a couple of requests:

RequestProcessor requestProcessor;
 
requestProcessor.processRequest("123");
requestProcessor.processRequest("12345");

Now we create a balm::MetricRecord to hold the aggregated metrics values. Note that we create 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, "RequestSize");
balm::MetricId           requestSizeId(&description);
 
// In practice, get 'requestSizeId' from a 'balm::MetricRegistry' object.
balm::MetricRecord requestSize(requestSizeId);

Finally we retrieve the information about the request sizes of the requests processed by requestProcessor. Note that the count of requests should be 2, the total size of the requests should be 8 (3 + 5), the minimum size should be 3, and the maximum size should be 5.

requestProcessor.loadRequestSizeInformation(&requestSize);
    assert(2 == requestSize.count());
    assert(8 == requestSize.total());
    assert(3 == requestSize.min());
    assert(5 == requestSize.max());