balm.h

Go to the documentation of this file.

/// @file balm.h
///
///
/// @defgroup balm Package balm
/// @brief  Basic Application Library Metrics (balm)
/// @addtogroup bal
/// @{
/// @addtogroup balm
/// [balm]: group__balm.html
/// @{
///
/// # Purpose {#balm-purpose}
/// Provide thread-safe collection and publishing of metrics.
///
/// # Mnemonic {#balm-mnemonic}
/// Basic Application Library Metrics (balm)
///
/// # Description {#balm-description}
/// The 'balm' package provides facilities for recording and
/// publishing metric data.
///
/// Bloomberg internal software should also consider the GUTS telemetry API, which
/// is integrated into Bloomberg infrastructure.
///
/// A "metric", in the context of this package, is a measured event.  This package
/// does *not* define what constitutes an event or what the associated measurement
/// represents.  For example, a metric could record the elapsed time of a function
/// call (in which case the event is the function call, and the measured value is
/// the elapsed time), or a metric could record the number of requests received by
/// a service (in which case the event is the reception of a request, and the
/// measured value is 1).
///
/// This package provides components for collecting and aggregating measurement
/// values (see @ref balm_metric  and @ref balm_metrics ).  Those aggregated metric
/// measurements are described by a metric record (see @ref balm_metricrecord ), which
/// contains the identifier for the recorded metric, the number of times the event
/// occurred, as well as the minimum, maximum, and total of the measured values.
/// This package provides a protocol for publishing metric records (see
/// @ref balm_publisher ) and an implementation of that protocol for publishing
/// records to a stream (see 'balm_streampublisher).  Finally this package
/// provides a @ref balm_metricsmanager  component to coordinate the collection and
/// publication of metrics.
///
/// ## Hierarchical Synopsis
///
/// The 'balm' package currently has 22 components having 13 levels of physical
/// dependency.  The list below shows the hierarchical ordering of the components.
/// The order of components within each level is not architecturally significant,
/// just alphabetical.
/// @code
///  13. balm_configurationutil
///
///  12. balm_metrics
///
///  11. balm_stopwatchscopedguard
///
///  10. balm_bdlmmetricsadapter
///      balm_integermetric
///      balm_metric
///
///   9. balm_defaultmetricsmanager
///      balm_publicationscheduler
///
///   8. balm_metricsmanager
///      balm_streampublisher
///
///   7. balm_collectorrepository
///      balm_publisher
///
///   6. balm_collector
///      balm_integercollector
///      balm_metricsample
///
///   5. balm_metricrecord
///      balm_metricregistry
///
///   4. balm_metricid
///
///   3. balm_metricdescription
///
///   2. balm_metricformat
///
///   1. balm_category
///      balm_publicationtype
/// @endcode
///
/// ## Component Synopsis
///
///  @ref balm_bdlmmetricsadapter :
///       Provide a concrete instance of the `bdlm` metrics adapter.
/// 
///  @ref balm_category :
///       Provide a representation of a metric category.
/// 
///  @ref balm_collector :
///       Provide a container for collecting and aggregating metric values.
/// 
///  @ref balm_collectorrepository :
///       Provide a repository for collectors.
/// 
///  @ref balm_configurationutil :
///       Provide a namespace for metrics configuration utilities.
/// 
///  @ref balm_defaultmetricsmanager :
///       Provide for a default instance of the metrics manager.
/// 
///  @ref balm_integercollector :
///       Provide a container for collecting integral metric values.
/// 
///  @ref balm_integermetric :
///       Provide helper classes for recording int metric values.
/// 
///  @ref balm_metric :
///       Provide helper classes for recording metric values.
/// 
///  @ref balm_metricdescription :
///       Provide a description for a metric.
/// 
///  @ref balm_metricformat :
///       Provide a formatting specification for a metric.
/// 
///  @ref balm_metricid :
///       Provide an identifier for a metric.
/// 
///  @ref balm_metricrecord :
///       Provide an aggregated record of the value of a metric.
/// 
///  @ref balm_metricregistry :
///       Provide a registry for metrics.
/// 
///  @ref balm_metrics :
///       Provide a suite of operations for recording metric values.
/// 
///  @ref balm_metricsample :
///       Provide a container for a sample of collected metric records.
/// 
///  @ref balm_metricsmanager :
///       Provide a manager for recording and publishing metric data.
/// 
///  @ref balm_publicationscheduler :
///       Provide a scheduler for publishing metrics.
/// 
///  @ref balm_publicationtype :
///       Provide an enumeration of aggregate types used to publish metrics.
/// 
///  @ref balm_publisher :
///       Provide a protocol to publish recorded metric values.
/// 
///  @ref balm_stopwatchscopedguard :
///       Provide a scoped guard for recording elapsed time.
/// 
///  @ref balm_streampublisher :
///       Provide a `balm::Publisher` implementation that writes to a stream.
///
/// ## Getting Started
///
/// The following section presents a simple example of collecting metrics.  We
/// create a trivial application that reads lines of text from standard input and
/// counts the number of letters, words, and unique words in each line.  The
/// function 'processLine()' processes each line of text and records metrics for
/// the number of times 'processLine()' has been called, the elapsed time for the
/// calls to 'processLine()', the total character count, and the total word count.
///
/// Before we can collect metrics we must first create a 'balm_MetricsManager'
/// object to manage their collection (and publication).  We use the
/// 'balm_DefaultMetricsManager', which is a singleton instance of the
/// 'balm_MetricsManager' class.  The default metrics manager is used by the
/// collection macros that we will use to collect metrics (see @ref balm_metrics ).
/// Note that the default metrics manager is intended to be created and destroyed
/// by the *owner* of 'main'.  A default metrics manager 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).
/// @code
///  int main(int argc, const char *argv[])
///  {
/// @endcode
/// We create a 'balm_DefaultMetricsManagerScopedGuard', which manages the
/// lifetime of the default metrics manager (singleton) instance.  At
/// construction, we provide the scoped guard an output stream ('stdout') to which
/// the @ref balm_publisher  (created by the default metrics manager) will publish
/// metrics.
/// @code
///      balm_DefaultMetricsManagerScopedGuard managerGuard(bdl::cout);
/// @endcode
/// We create a 'balm_PublicationScheduler' to periodically publish the metrics we
/// have collected.  A 'balm_PublicationScheduler' invokes 'publish()' on the
/// supplied 'balm_MetricsManager' object according to the provided schedule.
/// @code
///      bcep_TimerEventScheduler eventScheduler;
///      balm_PublicationScheduler publicationScheduler(
///                                     balm_DefaultMetricsManager::instance(),
///                                     &eventScheduler);
/// @endcode
/// To begin periodically publishing metrics we 'start' the event scheduler
/// supplied to the 'balm_PublicationScheduler', and then set a simple schedule to
/// publish all collected metrics every 30 seconds.
/// @code
///      eventScheduler.start();
///      publicationScheduler.setDefaultSchedule(bsls::TimeInterval(30, 0));
/// @endcode
/// Finally we have our main "application" loop, which reads lines of text from
/// the standard input (until "exit" is provided as input) and calls
/// 'processLine()' for each line of input.
/// @code
///      while (true) {
///          enum { BUFFER_SIZE = 1024 };
///          char buffer[BUFFER_SIZE];
///          if (!bdl::cin.getline(buffer, BUFFER_SIZE)) {
///              break;
///          }
///          if (0 == bdl::strcmp(buffer, "exit")) {
///              break;
///          }
///          processLine(buffer);
///      }
/// @endcode
/// At the end of this lexical scope 'managerGuard' is destroyed, releasing the
/// default 'balm_MetricsManager' instance.
/// @code
///  }
/// @endcode
/// Next we define the 'processLine()' function.  The 'processLine()' function
/// "processes" a line of text, and collects several metrics related to the
/// function invocation.
/// @code
///  void processLine(const bdl::string& line)
///      // Process the specified 'line' of text and write to standard output the
///      // number of characters, words, and unique words in 'line'.
///  {
/// @endcode
/// Increment the count of the number of calls to 'processLine()' and use the
/// 'BALM_METRICS_TIME_BLOCK' macro (see @ref balm_metrics ) to collect the elapsed
/// time of this function call.  Note that all the metrics recorded by this
/// function belong to the (arbitrarily chosen) category "Example".
/// @code
///      BALM_METRICS_INCREMENT("Example", "processLineCount");
///      BALM_METRICS_TIME_BLOCK("Example",
///                              "processLineElapsedTime",
///                              balm_StopwatchScopedGuard::BALM_SECONDS);
///
///      int                   wordCount  = 0;
///      bdl::set<bdl::string> words;
///
///      bdl::string        word;
///      bdl::istringstream istream(line);
///      while (istream >> word) {
///          words.insert(word);
///          ++wordCount;
///      }
///
///      bdl::cout << "Characters: count: " << line.size()
///                << "\tWord count: " << wordCount
///                << "\tUnique word count: " << words.size() << bdl::endl;
///
/// @endcode
/// Once we've "processed" the 'line', update the character count and word count
/// metrics.
/// @code
///      BALM_METRICS_UPDATE("Example", "characterCount", line.size());
///      BALM_METRICS_UPDATE("Example", "wordCount", wordCount);
///  }
/// @endcode
/// We've now created our example application.  A typical session with this
/// application might look like (note that '>' indicates user input):
/// @code
/// >this contains 4 words
///   Characters: count: 21   Word count: 4   Unique word count: 4
/// >this sentence contains 5 words
///   Characters: count: 30   Word count: 5   Unique word count: 5
/// @endcode
/// Every 30 seconds metrics will be reported to standard output.  A typical
/// publication of metrics would look like:
/// @code
///  17FEB2009_15:29:20.792+0000 4 Records
///    Elapsed Time: 30.0092s
///       Example.processLineCount [ count = 2, total = 2, min = 1, max = 1 ]
///       Example.processLineElapsedTime [ count = 2, total = 0.0007656,
///                                        min = 0.00022736, max = 0.00053824 ]
///       Example.characterCount [ count = 2, total = 51, min = 21, max = 30 ]
///       Example.wordCount [ count = 2, total = 9, min = 4, max = 5 ]
/// @endcode
///
/// ## Features Overview
///
/// This section provides a brief summary of the features of the 'balm'
/// package - details can be found in the indicated components and later in this
/// document.
///
///  * A protocol to provide pluggable publishing behavior.  Users can define and
///    register publishers with the metrics manager, which in turn defines the
///    behavior of the "publish" operation (see {@ref balm_publisher })
/// 
///  * A default (singleton) metrics manager instance (see
///    {@ref balm_defaultmetricsmanager })
/// 
///  * Simple macros for recording metrics to the default (singleton) metrics
///    manager instance (see {@ref balm_metrics })
/// 
///  * Simple types for recording metrics (see {@ref balm_metric } and
///    {@ref balm_integermetric })
/// 
///  * A guard helper class for recording the elapsed time of a block of code to a
///    metric (see {@ref balm_stopwatchscopedguard })
/// 
///  * The ability to enable and disable the collection and publication of
///    categories of metrics (see {@ref balm_metricsmanager } and {@ref balm_category })
/// 
///  * A scheduling mechanism for configuring the periodic publication of metrics
///    (see {@ref balm_publicationscheduler })
///
/// ## Multi-Threading
///
/// The components provided by the 'balm' package were designed for use in
/// multi-threaded applications.  Metrics can be safely collected and published
/// simultaneously from multiple threads.  Nevertheless, not every individual
/// component in the 'balm' package is thread-safe.  See the individual component
/// documentation for more information.
///
/// ## Collecting Metrics
///
/// The 'balm' package defines several ways to collect metrics, as well as
/// allowing users to define their own collection mechanisms.
///
/// ### Choosing Between @ref balm_metric  and @ref balm_integermetric 
///
/// The @ref balm_metric  and @ref balm_integermetric  components both define macros and
/// helper classes for recording metrics.  The mechanisms in @ref balm_integermetric 
/// are slightly more efficient for collecting integral metric values, but are
/// otherwise identical.
///
/// ### Choosing Between Metric Collection Macros and Metric Collection Classes
///
/// The macros and classes defined by the @ref balm_metric , @ref balm_integermetric  and
/// @ref balm_metrics  components provide the same basic functionality.  Clients may
/// find the 'balm_Metric' or 'balm_IntegerMetric' classes better suited to
/// collecting metrics associated with a particular instance of a stateful object,
/// while the 'BALM_METRICS_*' 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.
///
/// ### Creating a User Defined Collection Mechanism
///
/// The 'balm' package allows users to define their own metric collection
/// mechanisms by registering a callback with a 'balm_MetricsManager' object.
/// User defined callbacks must match the
/// 'balm_MetricsManager::MetricsCollectionCallback' function signature and
/// collect metrics for a *single* category.  Every time 'publish' is invoked for
/// a category, the metrics manager will invoke the registered collection
/// callbacks for that category, and publish the collected metrics.  See
/// @ref balm_metricsmanager  for more information.
///
/// ## Publishing Metrics
///
/// The @ref balm_publisher  component defines a protocol for publishing metric
/// records.  Users can register publisher objects with a metrics manager.
/// Invoking 'publish()' on a metrics manager will collect metrics for the set of
/// categories supplied with the function call, and then publish the metrics for
/// each supplied category to publishers registered for that category.
///
/// The 'balm_StreamPublisher' class implements the 'balm_Publisher' protocol to
/// provide a default publisher for publishing metrics to a stream.
///
/// ## Periodically Publishing Metrics
///
/// Users can schedule the periodic publication of metrics using the
/// @ref balm_publicationscheduler  component.  In the example presented above, under
/// "Getting Started", a 'balm_PublicationScheduler' object was configured to
/// publish all categories of metrics metrics every 30 seconds.
///
/// At construction, a 'balm_PublicationScheduler' object is provided the
/// addresses of a 'balm_MetricsManager' and a 'bcep_TimerEventScheduler'.  Users
/// can call 'scheduleCategory()' to schedule an individual metric category to be
/// published repeatedly at a given interval, or call 'setDefaultSchedule()' to
/// schedule the publication of any category not given an individual schedule.  At
/// the end of a scheduled time interval, the publication scheduler invokes the
/// metrics manager's 'publish()' operation with the set of categories to publish.
/// Note that, the publication scheduler will combine categories that occur at the
/// same frequency into a single invocation of the metrics manager's 'publish'
/// operation.
///
/// ## Disabling Metric Categories
///
/// Users can disable (and re-enable) a category of metrics by calling
/// 'balm_MetricsManager::setCategoryEnabled' method.  A disabled category will
/// not be published by the metrics manager.  In addition, the @ref balm_metric ,
/// @ref balm_integermetric , @ref balm_metrics , and @ref balm_stopwatchscopedguard 
/// components will not collect metrics for disabled categories (minimizing the
/// performance cost of collecting metric for disabled categories).  Note that
/// when 'balm_MetricsManager::publish()' is called on a disabled category, the
/// metrics manager *will* invoke any user defined collection callbacks registered
/// for the disable category, but *will* *not* publish the collected metrics.
/// Users defining their own metrics collection mechanism (using a
/// 'balm_MetricsManager::MetricsCollectionCallback') must (manually) test whether
/// a category is disabled if they wish to avoid collecting metrics for a disabled
/// category.
///
/// @}
/** @} */