Component balm_metricrecord [Package balm]

Provide an aggregated record of the value of a metric. More...

Namespaces
namespace	balm

---

Detailed Description

Outline

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

Component balm_metricregistry, Component balm_metric, Component 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:

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());