Component balm_metric [Package balm]

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

Namespaces
namespace	balm

---

Detailed Description

Outline

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

Purpose:

Provide helper classes for recording metric values.

Classes:

balm::Metric

container for recording metric values

See also:

Component balm_metricsmanager, Component balm_defaultmetricsmanager, Component balm_integermetric, Component balm_metrics

Description:

This component provides a class, balm::Metric, to simplify the process of collecting 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::Metric class, defined in this component, has in-core value semantics. Each balm::Metric object holds a pointer to a balm::Collector that collects values for a particular metric. The balm::Collector 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::Metric and Macros:

The balm::Metric class and the macros defined in balm_metrics provide the same basic functionality. Clients may find balm::Metric objects better suited to collecting 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, however, choosing between the two is simply a matter of taste.

Thread Safety:

balm::Metric is fully thread-safe, meaning that all non-creator operations on a given instance 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::Metric:

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

  class EventManager {

      // DATA
      balm::Metric d_messageSize;
      balm::Metric d_elapsedTime;
      balm::Metric 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<double>(eventMessage.size()));
          bsls::Stopwatch stopwatch;
          stopwatch.start();

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

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

          d_elapsedTime.update(stopwatch.elapsedTime());
          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();
  }