balm_publisher.h

Go to the documentation of this file.

/// @file balm_publisher.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// balm_publisher.h                                                   -*-C++-*-
#ifndef INCLUDED_BALM_PUBLISHER
#define INCLUDED_BALM_PUBLISHER
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: balm_publisher.h,v 1.6 2008/04/09 19:42:15 hversche Exp $")
 
/// @defgroup balm_publisher balm_publisher
/// @brief  Provide a protocol to publish recorded metric values.
/// @addtogroup bal
/// @{
/// @addtogroup balm
/// @{
/// @addtogroup balm_publisher
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#balm_publisher-purpose"> Purpose</a>
/// * <a href="#balm_publisher-classes"> Classes </a>
/// * <a href="#balm_publisher-description"> Description </a>
///   * <a href="#balm_publisher-alternative-systems-for-telemetry"> Alternative Systems for Telemetry </a>
///   * <a href="#balm_publisher-usage"> Usage </a>
///     * <a href="#balm_publisher-example-1-implementing-the-balm-publisher-protocol"> Example 1: Implementing the balm::Publisher Protocol </a>
///     * <a href="#balm_publisher-example-2-using-the-balm-publisher-protocol"> Example 2: Using the balm::Publisher Protocol </a>
///     * <a href="#balm_publisher-example-3-publishing-collected-metrics-using-eventmanager"> Example 3: Publishing Collected Metrics Using EventManager </a>
///
/// # Purpose {#balm_publisher-purpose}
/// Provide a protocol to publish recorded metric values.
///
/// # Classes {#balm_publisher-classes}
///
/// -   balm::Publisher: a protocol providing a method to publish metric values
///
/// @see 
///
/// # Description {#balm_publisher-description}
/// This component defines a protocol class `balm::Publisher` used
/// for publishing metric values.  The protocol's primary method is `publish`,
/// which takes a `balm::MetricSample`.  The precise meaning of `publish` is
/// left to derived classes to specify.
///
/// ## Alternative Systems for Telemetry {#balm_publisher-alternative-systems-for-telemetry}
///
///
/// Bloomberg software may alternatively use the GUTS telemetry API, which is
/// integrated into Bloomberg infrastructure.
///
/// ## Usage {#balm_publisher-usage}
///
///
/// This section illustrates intended use of this component.
///
/// ### Example 1: Implementing the balm::Publisher Protocol {#balm_publisher-example-1-implementing-the-balm-publisher-protocol}
///
///
/// The following example demonstrates a simple implementation of the
/// `balm::Publisher` protocol.  This implementation publishes the metric
/// records to an output stream provided on construction.
/// @code
/// // simplestreampublisher.h
/// class SimpleStreamPublisher : public balm::Publisher {
///     // A simple implementation of the 'balm::Publisher' protocol that
///     // writes metric records to a stream.
///
///     // DATA
///     bsl::ostream& d_stream; // output stream (held, not owned)
///
/// private:
///     // NOT IMPLEMENTED
///     SimpleStreamPublisher(const SimpleStreamPublisher& );
///     SimpleStreamPublisher& operator=(const SimpleStreamPublisher& );
///
/// public:
///     // CREATORS
///     SimpleStreamPublisher(bsl::ostream& stream);
///         // Create this publisher that will publish metrics to the specified
///         // 'stream'.
///
///     virtual ~SimpleStreamPublisher();
///          // Destroy this publisher.
///
///     // MANIPULATORS
///     virtual void publish(const balm::MetricSample& metricValues);
///         // Publish the specified 'metricValues'.  This implementation will
///         // write the 'metricValues' to the output stream specified on
///         // construction.
/// };
///
/// // simplestreampublisher.cpp
///
/// // CREATORS
/// SimpleStreamPublisher::SimpleStreamPublisher(bsl::ostream& stream)
/// : d_stream(stream)
/// {
/// }
///
/// SimpleStreamPublisher::~SimpleStreamPublisher()
/// {
/// }
///
/// // MANIPULATORS
/// void SimpleStreamPublisher::publish(const balm::MetricSample& metricValues)
/// {
///     if (0 >= metricValues.numRecords()) {
///         return;                                                   // RETURN
///     }
///     d_stream << metricValues.timeStamp() << " "
///              << metricValues.numRecords() << " Records" << bsl::endl;
///
///     balm::MetricSample::const_iterator sIt = metricValues.begin();
///     for (; sIt != metricValues.end(); ++sIt) {
///         d_stream << "\tElapsed Time: "
///                  << sIt->elapsedTime().totalSecondsAsDouble()
///                  << "s" << bsl::endl;
///         balm::MetricSampleGroup::const_iterator gIt = sIt->begin();
///         for (; gIt != sIt->end(); ++gIt) {
///             d_stream << "\t" << gIt->metricId()
///                      << " [count = " << gIt->count()
///                      << ", total = " << gIt->total()
///                      << ", min = "   << gIt->min()
///                      << ", max = "   << gIt->max() << "]" << bsl::endl;
///         }
///     }
/// }
/// @endcode
///
/// ### Example 2: Using the balm::Publisher Protocol {#balm_publisher-example-2-using-the-balm-publisher-protocol}
///
///
/// The following example defines a trivial `EventManager` class that uses the
/// `balm::Publisher` protocol to publish metrics related to the incoming
/// event.  Note that this event manager does no actual processing and is
/// intended only to illustrate how the publisher protocol might be used.
/// @code
/// class EventManager {
///     // This class provides a dummy event handling mechanism that publishes
///     // a metric for the size of the processed event messages.
///
///     // DATA
///     balm::Collector  d_eventMessageSize;  // metric for the message size
///     bdlt::DatetimeTz d_lastPublish;       // time of the last publication
///
/// private:
///     // NOT IMPLEMENTED
///     EventManager(const EventManager& );
///     EventManager& operator=(const EventManager& );
///
///   public:
///     // CREATORS
///     EventManager(const balm::MetricId& messageSizeId)
///         // Create this event manager using the specified 'messageSizeId'
///         // to identify the event message size metric.
///     : d_eventMessageSize(messageSizeId)
///     , d_lastPublish(bdlt::CurrentTime::nowAsDatetimeUTC(), 0)
///     {}
///
///     // 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 processing the event.
///     {
///         // Update the metrics with the size of the 'eventMessage'.
///         d_eventMessageSize.update(
///                                  static_cast<double>(eventMessage.size()));
///
///         // ...   process the event
///         (void)eventId;
///
///         return 0;
///     }
/// @endcode
/// We use a `balm::Publisher` to publish the metrics recorded by this event
/// manager.  Note that most of the functionality illustrated here is normally
/// provided by the `balm::MetricsManager`.
/// @code
///     void publishMetrics(balm::Publisher *publisher)
///     {
///         bdlt::DatetimeTz now(bdlt::CurrentTime::nowAsDatetimeUTC(), 0);
///         bdlt::DatetimeInterval dateInterval = now.utcDatetime() -
///                                              d_lastPublish.utcDatetime();
///         bsls::TimeInterval interval(dateInterval.totalSeconds(),
///                                    dateInterval.milliseconds());
///
///         balm::MetricRecord record;
///         d_eventMessageSize.loadAndReset(&record);
///
///         balm::MetricSample sample;
///         sample.setTimeStamp(now);
///         sample.appendGroup(&record, 1, interval);
///
///         // This is where we make use of the publisher argument to this
///         // function.
///         publisher->publish(sample);
///
///         d_lastPublish = now;
///     }
/// };
/// @endcode
///
/// ### Example 3: Publishing Collected Metrics Using EventManager {#balm_publisher-example-3-publishing-collected-metrics-using-eventmanager}
///
///
/// In this final example, we publish metrics collected for the `EventManager`
/// object (defined above).
///
/// We start by creating a `balm::MetricId` object by hand, but in practice, an
/// id should be obtained from a `balm::MetricRegistry` object (such as the one
/// owned by a `balm::MetricsManager`).
/// @code
/// balm::Category           myCategory("MyCategory");
/// balm::MetricDescription  description(&myCategory, "EventMessageSize");
/// balm::MetricId           eventMessageSizeId(&description);
/// @endcode
/// Now we create a `EventManager` object and supply it the metric id we have
/// created.
/// @code
/// EventManager eventManager(eventMessageSizeId);
/// @endcode
/// We use the `EventManager` object to process two events and then publish the
/// metrics for those events with a `SimpleStreamPublisher` object (also defined
/// above).
/// @code
/// eventManager.handleEvent(0, "123");
/// eventManager.handleEvent(0, "456789");
///
/// SimpleStreamPublisher myPublisher(bsl::cout);
/// balm::Publisher *publisher = &myPublisher;
/// eventManager.publishMetrics(publisher);
/// @endcode
/// Note that we have delivered two events, with the messages "123" and
/// "456789", so the count should be 2, the total message size should be 9, the
/// minimum should be 3, and the maximum should be 6.  The output to the
/// console should be:
/// @code
/// 05FEB2009_19:49:30.173+0000 1 Records
///         Elapsed Time: 1e-09s
///         MyCategory.EventMessageSize [count = 2, total = 9, min = 3, max = 6]
/// @endcode
/// @}
/** @} */
/** @} */
 
/** @addtogroup bal
 * @{
 */
/** @addtogroup balm
 * @{
 */
/** @addtogroup balm_publisher
 * @{
 */
 
#include <balscm_version.h>
 
 
 
 
namespace balm {
 
class MetricSample;
 
                              // ===============
                              // class Publisher
                              // ===============
 
/// This protocol class provides a `publish` method to publish collected
/// sample of recorded metric values.  The precise meaning of publish is
/// left to derived classes to specify.
///
/// See @ref balm_publisher 
class Publisher {
 
  public:
    // CREATORS
 
    /// Destroy this object.
    virtual ~Publisher();
 
    // MANIPULATORS
 
    /// Publish the specified `metricValue`.  The exact definition of
    /// publish depends on the implementing class, though the intention is
    /// that the recorded metric values will be distributed in a human or
    /// machine readable form.
    virtual void publish(const MetricSample& metricValue) = 0;
};
 
}  // close package namespace
 
 
#endif
 
// ----------------------------------------------------------------------------
// Copyright 2015 Bloomberg Finance L.P.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// ----------------------------- END-OF-FILE ----------------------------------
 
/** @} */
/** @} */
/** @} */