bdlm.h

Go to the documentation of this file.

/// @file bdlm.h
///
///
/// @defgroup bdlm Package bdlm
/// @brief  Basic Development Library Metrics (bdlm)
/// @addtogroup bdl
/// @{
/// @addtogroup bdlm
/// @{
/// * <a href="#bdlm-purpose"> Purpose</a>
/// * <a href="#bdlm-mnemonic"> Mnemonic </a>
/// * <a href="#bdlm-description"> Description </a>
///   * <a href="#bdlm-hierarchical-synopsis"> Hierarchical Synopsis </a>
///   * <a href="#bdlm-component-synopsis"> Component Synopsis </a>
///   * <a href="#bdlm-instrumenting-a-class"> Instrumenting a Class </a>
///   * <a href="#bdlm-configuring-a-metricsadapter"> Configuring a MetricsAdapter </a>
///
/// # Purpose {#bdlm-purpose}
/// Provide metrics registrars.
///
/// # Mnemonic {#bdlm-mnemonic}
/// Basic Development Library Metrics (bdlm)
///
/// # Description {#bdlm-description}
/// The 'bdlm' package provides a means for low-level library
/// software to collect and publish metrics through a metric publishing framework,
/// without a library depending on the metrics publishing framework.  The 'bdlm'
/// package provides a protocol (i.e., a pure abstract interface),
/// 'bdlm::MetricsAdapter', that can be implemented for (higher level) metrics
/// facilities.  In addition, it also provides a registry of metrics,
/// 'bdlm::MetricRegistry', that allows low-level users of 'bdlm' to register
/// metrics at any time, serving as an intermediary with concrete
/// 'bdlm::MetricsAdapter' implementations (which may be configured before or
/// after the creation of any particular metric).
///
/// As a low-level metrics facility, this package does not directly manage
/// schedulers to collect metrics values or publishers to publish collected
/// values.  Instead it is designed to allow applications to plug in different
/// high-level feature-rich metrics collection and publication frameworks (without
/// requiring a library dependency on those frameworks).
///
/// ## Hierarchical Synopsis {#bdlm-hierarchical-synopsis}
///
/// The 'bdlm' package currently has 5 components having 4 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
///  4. bdlm_metricsregistry
///
///  3. bdlm_metricsadapter
///
///  2. bdlm_metricdescriptor
///
///  1. bdlm_instancecount
///     bdlm_metric
/// @endcode
///
/// ## Component Synopsis {#bdlm-component-synopsis}
///
///  @ref bdlm_instancecount :
///       Provide a type specific instance count.
/// 
///  @ref bdlm_metric :
///       Provide a class to store metric values of different types.
/// 
///  @ref bdlm_metricdescriptor :
///       Provide an attribute class to describe a metric.
/// 
///  @ref bdlm_metricsadapter :
///       Provide an abstract interface for metrics registration mechanisms.
/// 
///  @ref bdlm_metricsregistry :
///       Provide a transferable registry of metric registrations.
///
/// ## Instrumenting a Class {#bdlm-instrumenting-a-class}
///
/// Here, we describe how to instrument a low level class ('YourClass') to report
/// metrics through 'bdlm'.  Applications will configure 'bdlm' with a
/// 'bdlm::MetricAdapter' implementation for their preferred metrics framework, so
/// that metrics reported via 'bdlm' will be published through that framework
/// (without requiring a direct library dependency).
///
/// A software metric is a measurement (or collection of measurements) about a
/// running system.  The only metric classification 'bdlm' currently supports is a
/// 'Guage', which is a metric holding a single value for the most recent
/// measurement (other possible metric classifications include summaries,
/// counters, and distributions).  Information is provided to 'bdlm' about a
/// metric by registering a function having the 'bdlm::MetricsRegistry::Callback'
/// signature.  Typically, the function is declared in an unnamed namespace.
///
/// Here we define a metric reporting function 'youMetric' for reporting a metric
/// related to 'YourClass':
/// @code
///  void yourMetric(BloombergLP::bdlm::Metric             *value,
///                  const BloombergLP::package::YourClass *object)
///  {
///        *value = BloombergLP::bdlm::Metric::Gauge(object->interestingValue());
///  }
/// @endcode
/// A class exposes metrics by registering functors with a
/// 'bdlm::MetricsRegistry'.  Typically, this registry is provided in the
/// constructors of the class, or the default singleton registry,
/// 'bdlm::MetricsRegistry::defaultInstance()', is used:
/// @code
///  YourClass(bdlm::MetricsRegistry *metricsRegistry)
///  {
///      bdlm::MetricsRegistry *registry = metricsRegistry
///                                   ? metricsRegistry
///                                   : &bdlm::MetricsRegistry::defaultInstance();
/// @endcode
/// A metrics registration requires information to identify the metric and a
/// functor, with signature 'bdlm::MetricsRegistry::Callback', to produce the
/// metric when the publication system requests the value.  The identity
/// information is provided in a 'bdlm::MetricDescriptor', which is meant to
/// contain a superset of data needed by used publication systems (e.g., BALM and
/// GUTS).
///
/// The pieces of information used to identify a metric are (i.e., the arguments
/// to create a 'MetricDescriptor):
///  * Metric Namespace
///  * Metric Name
///  * A number uniquely identifying this object's instance of the class
///  * A name identifying the class
///  * An abbreviation for the class name
///  * A unique text identifying this object's instance of the class
///
/// See @ref bdlm_metricdescriptor  for more detail.
///
/// The instance number is generally best provided by the 'bdlm::InstanceCount'
/// class.  Here we use the constant
/// 'bdlm::MetricDescriptor::k_USE_METRICS_ADAPTER_NAMESPACE_SELECTION' for the
/// metric namespace, and
/// 'bdlm::MetricDescriptor::k_USE_METRICS_ADAPTER_OBJECT_ID_SELECTION' for the
/// unique text identifying the object instance, to allow the concrete
/// 'MetricAdapter' to select appropriate values for the particular metrics
/// framework.
/// @code
///      bdlm::InstanceCount::Value instanceNumber =
///                          bdlm::InstanceCount::nextInstanceNumber<YourClass>();
///
///      bdlm::MetricDescriptor mdInteresting(
///            bdlm::MetricDescriptor::k_USE_METRICS_ADAPTER_NAMESPACE_SELECTION,
///            "requestCount",       // the metric name
///            instanceNumber,
///            "package.yourclass",  // the class identifier
///            "yc",                 // the class abreviation
///            bdlm::MetricDescriptor::k_USE_METRICS_ADAPTER_OBJECT_ID_SELECTION);
/// @endcode
/// Assuming a class member 'd_interestingHandle' to hold the handle for the
/// registered metric, the metric is registered with the 'bdlm::MetricsRegistry':
/// @code
///      registry->registerCollectionCallback(
///                                &d_interestingHandle,
///                                mdInteresting,
///                                bdlf::BindUtil::bind(&yourMetric,
///                                                     bdlf::PlaceHolders::_1,
///                                                     this));
///  }
/// @endcode
/// Note that the destructor of the 'bdlm::MetricsRegistryRegistrationHandle'
/// unregisters the metric.
///
/// ## Configuring a MetricsAdapter {#bdlm-configuring-a-metricsadapter}
///
/// 'bdlm' is designed to allow application owners to plugin a higher level
/// metrics reporting framework by supplying a concrete 'bdlm::MetricsAdapter'
/// instance to the 'bdlm::MetricsRegistry'.  Imagine we have a hypothetical
/// metrics publication framework GUTS, and a concrete 'bdlm::MetricsAdapter' for
/// GUTS, 'guta::BdlmMetricsAdapter'.
/// @code
///  int main(int argc, const char *argv[]) {
///      // Initialize GUTS metrics publication
///
///      gtout::PublisherConfig config;
///      config.intervalSec() = 1.0;
///      gtout::PublisherGuard publisher(config);
///
///      // Create concrete 'bdlm::MetricAdapter' implementation of
///      // 'guta::BdlmMetricsAdapter'.
///
///      guta::BdlmMetricsAdapter adapter(
///                        gutz::DefaultMetricsManager::instance(),
///                        "myNamespace",     // a namespace for the metrics
///                        "myServiceName");  // an identifier for the application
///
///      // Assign the adapter to the registry singleton.
///
///      bdlm::MetricsRegistry::singleton().setMetricsAdapter(&adapter);
///
///      // ...
///
///      // Remove the adapter from the registry singleton.
///
///      bdlm::MetricRegistry::removeMetricsAdapter(&adapter);
///  }
/// @endcode
///
/// @}
/** @} */