Component balm_stopwatchscopedguard [Package balm]

Provide a scoped guard for recording elapsed time. More...

Namespaces
namespace	balm

---

Detailed Description

Outline

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

Purpose:

Provide a scoped guard for recording elapsed time.

Classes:

balm::StopwatchScopedGuard

guard for recording a metric for elapsed time

See also:

Component balm_metricsmanager, Component balm_defaultmetricsmanager, Component balm_metric

Description:

This component provides a scoped guard class intended to simplify the task of recording (to a metric) the elapsed time of a block of code. The balm::StopwatchScopedGuard is supplied the identity of a metric on construction, and an optional enumerated constant indicating the time units to report values in (by default, values are reported in seconds). The guard measures the elapsed time between its construction and destruction, and on destruction records that elapsed time, in the indicated time units, to the supplied metric.

Alternative Systems for Telemetry:

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

Choosing Between balm::StopwatchScopedGuard and Macros:

The balm::StopwatchScopedGuard class and the macros defined in the balm_metrics component provide the same basic functionality. Clients may find that using a balm::StopwatchScopedGuard object (in coordination with a balm::Metric object) is 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 a matter of taste.

Thread Safety:

balm::StopwatchScopedGuard 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::StopwatchScopedGuard in one thread while thread modifies the same object. Note however, that at this another time balm::StopwatchScopedGuard provides no manipulator methods.

Usage:

The following examples demonstrate how to record the elapsed time of a block of code using a balm::StopwatchScopedGuard.

Example 1: Create and Configure 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 the balm::DefaultMetricsManager::create method must also explicitly call the balm::DefaultMetricsManager::release method.

Example 2: Metric Collection with balm::StopwatchScopedGuard:

Alternatively, we can use the balm::StopwatchScopedGuard to record metric values. In the following example we implement a hypothetical request processor similar to the one in example 3. We use a balm::Metric (d_elapsedTime) and a balm::StopwatchScopedGuard (guard) to record the elapsed time of the request-processing function.

  class RequestProcessor {

      // DATA
      balm::Metric d_elapsedTime;

    public:

      // CREATORS
      RequestProcessor()
      : d_elapsedTime("MyCategory", "RequestProcessor/elapsedTime")
      {}

      // MANIPULATORS
      int processRequest(const bsl::string& request)
          // Process the specified 'request'.  Return 0 on success, and a
          // non-zero value otherwise.
      {
          (void)request;

          int returnCode = 0;

          balm::StopwatchScopedGuard guard(&d_elapsedTime);

  // ...

          return returnCode;
      }

  // ...
  };

  // ...

      RequestProcessor processor;

      processor.processRequest("ab");
      processor.processRequest("abc");
      processor.processRequest("abc");
      processor.processRequest("abdef");

      manager->publishAll();

      processor.processRequest("ab");
      processor.processRequest("abc");
      processor.processRequest("abc");
      processor.processRequest("abdef");

      processor.processRequest("a");
      processor.processRequest("abc");
      processor.processRequest("abc");
      processor.processRequest("abdefg");

      manager->publishAll();