Component balm_defaultmetricsmanager [Package balm]

Provide for a default instance of the metrics manager. More...

Namespaces
namespace	balm

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Alternative Systems for Telemetry
  • Thread Safety
  • Usage
    • Example 1: Create and Access the Default balm::MetricsManager Instance

Purpose:

Provide for a default instance of the metrics manager.

Classes:

balm::DefaultMetricsManager	namespace for the default instance
balm::DefaultMetricsManagerScopedGuard	guard for the default instance

See also:

Component balm_metricsmanager, Component balm_metric

Description:

This component provides a namespace for a default instance of the balm::MetricsManager. This balm::DefaultMetricsManager provides static operations to create, access, and destroy the default instance of the balm::MetricsManager. The balm::DefaultMetricsManagedScopedGuard provides a proctor that creates a default metrics manager on construction and destroys it on destruction.

balm::DefaultMetricsManagerScopedGuard is also here.

Alternative Systems for Telemetry:

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

Thread Safety:

The default balm::MetricsManager instance, once initialized, can be safely accessed from multiple threads. However, the create and destroy operations supplied by the balm::DefaultMetricsManager are not thread-safe. Care must be taken, particularly when releasing the instance. The expected usage is that the instance will be created during the initialization of an application (while the task has a single thread) and that it will be destroyed just prior to termination (when there is similarly just a single thread).

Usage:

The following examples demonstrate how to create, configure, and destroy the default balm::MetricsManager instance.

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

This example demonstrates how to create the default balm::MetricManager instance and publish a single metric to the console. See the documentation of balm_metric and balm_metricsmanager for information on how to record metrics.

First we create a balm::DefaultMetricsManagerScopedGuard, which manages the lifetime of the default metrics manager instance. At construction, we provide the balm::DefaultMetricsManagerScopedGuard an output stream (stdout) to which it will publish metrics. Note that the default metrics manager is intended to be created and destroyed by the owner of main. The instance 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 static instance method.

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

The default metrics manager, by default, is configured with a balm::StreamPublisher object that will publish all recorded metrics to the consoled. We use the default manager instance to update the collector for a single metric, and then publish all metrics.

      balm::Collector *myMetric =
                      manager->collectorRepository().getDefaultCollector(
                                                   "MyCategory", "MyMetric");
      myMetric->update(10);
      manager->publishAll();

      // ... rest of program elided ...
  }

The output of this example would look similar to:

 05FEB2009_19:20:12.697+0000 1 Records
    Elapsed Time: 0.009311s
            MyCategory.MyMetric [ count = 1, total = 10, min = 10, max = 10 ]

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