Component balm_integermetric [Package balm]

Provide helper classes for recording int metric values. More...

Namespaces
namespace	balm

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Alternative Systems for Telemetry
  • Choosing Between balm::IntegerMetric and Macros
  • Thread Safety
  • Usage
    • Example 1: Metric Collection With balm::IntegerMetric
    • Example 2: Create and Access the Default balm::MetricsManager Instance

Purpose:

Provide helper classes for recording int metric values.

Classes:

balm::IntegerMetric

container for recording integer metric values

See also:

Component balm_metric, Component balm_metrics, Component balm_metricsmanager, Component balm_defaultmetricsmanager

Description:

This component provides a class, balm::IntegerMetric, to simplify the process of collecting integer metrics. A metric 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 associated value represents. A metric maintains a count of event occurrences and the aggregated minimum, maximum, and total of the measured metric-event values.

The balm::IntegerMetric class, defined in this component, has in-core value semantics. Each balm::IntegerMetric object holds a pointer to a balm::IntegerCollector that collects values for a particular integer metric. The balm::IntegerCollector is either supplied at construction, or else obtained from a balm::MetricsManager object's balm::CollectorRepository. If the supplied balm::MetricsManager is 0, the metric will use the default metrics manager instance (balm::DefaultMetricsManager::instance()), if initialized; otherwise the metric is placed in the inactive state (i.e., isActive() is false) and operations that would otherwise update the metric will have no effect.

Alternative Systems for Telemetry:

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

Choosing Between balm::IntegerMetric and Macros:

The balm::IntegerMetric class and the macros defined in balm_metrics provide the same basic functionality. Clients may find balm::IntegerMetric objects better suited to collecting integer metrics associated with a particular instance of a stateful object, while macros are better suited to collecting metrics associated with a particular code path (rather than an object instance). In most instances choosing is a matter of taste.

Thread Safety:

balm::IntegerMetric is fully thread-safe, meaning that all non-creator operations on a given instance can be safely invoked simultaneously from multiple threads.

In addition all the macros defined in this component are fully thread-safe, meaning that they can be safely invoked simultaneously from multiple threads.

Usage:

The following examples demonstrate how to configure, collect, and publish metrics.

Example 1: Metric Collection With balm::IntegerMetric:

We can use balm::IntegerMetric objects to record metric values. In this example we implement a hypothetical event manager object. We use balm::IntegerMetric objects to record metrics for the size of the request, the elapsed processing time, and the number of failures.

  class EventManager {

      // DATA
      balm::IntegerMetric d_messageSize;
      balm::IntegerMetric d_elapsedTime;
      balm::IntegerMetric d_failedRequests;

    public:

      // CREATORS
      EventManager()
      : d_messageSize("MyCategory", "EventManager/size")
      , d_elapsedTime("MyCategory", "EventManager/elapsedTime")
      , d_failedRequests("MyCategory", "EventManager/failedRequests")
      {}

      // MANIPULATORS
      int handleEvent(int eventId, const bsl::string& eventMessage)
          // Process the event described by the specified 'eventId' and
          // 'eventMessage' .  Return 0 on success, and a non-zero value
          // if there was an error handling the event.
      {
          (void)eventId;

          int returnCode = 0;

          d_messageSize.update(static_cast<int>(eventMessage.size()));

          bsls::TimeInterval start = bdlt::CurrentTime::now();

          // Process 'data' ('returnCode' may change).

          if (0 != returnCode) {
              d_failedRequests.increment();
          }

          bsls::TimeInterval end = bdlt::CurrentTime::now();
          d_elapsedTime.update(static_cast<int>(
                                         (end - start).totalMicroseconds()));
          return returnCode;
      }

  // ...
  };

Example 2: Create and Access the Default balm::MetricsManager Instance:

This example demonstrates how to create the default balm::MetricManager instance and perform a trivial configuration.

First we create a balm::DefaultMetricsManagerScopedGuard, which manages the lifetime of the default metrics manager instance. At construction, we provide the scoped guard an output stream (stdout) that it will publish metrics to. Note that the default metrics manager is intended to be created and destroyed by the owner of main. An instance of the manager should be created during the initialization of an application (while the task has a single thread) and destroyed just prior to termination (when there is similarly a single thread).

  int main(int argc, char *argv[])
  {
      // ...

      balm::DefaultMetricsManagerScopedGuard managerGuard(bsl::cout);

Once the default instance has been created, it can be accessed using the instance operation.

      balm::MetricsManager *manager =
                                     balm::DefaultMetricsManager::instance();
      assert(0 != manager);

Note that the default metrics manager will be released when managerGuard exits this scoped and is destroyed. Clients that choose to explicitly call balm::DefaultMetricsManager::create must also explicitly call balm::DefaultMetricsManager::release().

Now that we have created a balm::MetricsManager instance, we can use the instance to publish metrics collected using the event manager described in Example 1:

      EventManager eventManager;

      eventManager.handleEvent(0, "ab");
      eventManager.handleEvent(0, "abc");
      eventManager.handleEvent(0, "abc");
      eventManager.handleEvent(0, "abdef");

      manager->publishAll();

      eventManager.handleEvent(0, "ab");
      eventManager.handleEvent(0, "abc");
      eventManager.handleEvent(0, "abc");
      eventManager.handleEvent(0, "abdef");

      eventManager.handleEvent(0, "a");
      eventManager.handleEvent(0, "abc");
      eventManager.handleEvent(0, "abc");
      eventManager.handleEvent(0, "abdefg");

      manager->publishAll();
  }