balm_streampublisher.h

Go to the documentation of this file.

/// @file balm_streampublisher.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// balm_streampublisher.h                                             -*-C++-*-
#ifndef INCLUDED_BALM_STREAMPUBLISHER
#define INCLUDED_BALM_STREAMPUBLISHER
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
 
/// @defgroup balm_streampublisher balm_streampublisher
/// @brief  Provide a `balm::Publisher` implementation that writes to a stream.
/// @addtogroup bal
/// @{
/// @addtogroup balm
/// @{
/// @addtogroup balm_streampublisher
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#balm_streampublisher-purpose"> Purpose</a>
/// * <a href="#balm_streampublisher-classes"> Classes </a>
/// * <a href="#balm_streampublisher-description"> Description </a>
///   * <a href="#balm_streampublisher-alternative-systems-for-telemetry"> Alternative Systems for Telemetry </a>
///   * <a href="#balm_streampublisher-usage"> Usage </a>
///     * <a href="#balm_streampublisher-example-1-basic-usage"> Example 1: Basic Usage </a>
///
/// # Purpose {#balm_streampublisher-purpose}
/// Provide a `balm::Publisher` implementation that writes to a stream.
///
/// # Classes {#balm_streampublisher-classes}
///
/// -  balm::StreamPublisher: publishes collected metric samples to a stream
///
/// @see  balm_publisher, balm_metricrecord, balm_metricsmanager
///
/// # Description {#balm_streampublisher-description}
/// This component defines a concrete class
/// `balm::StreamPublisher` that implements the `balm::Publisher` protocol for
/// publishing metric records:
/// @code
///              ( balm::StreamPublisher )
///                          |              ctor
///                          |
///                          V
///                  ( balm::Publisher )
///                                         dtor
///                                         publish
/// @endcode
/// This implementation of the publisher protocol publishes records to an output
/// stream that is supplied at construction.
///
/// ## Alternative Systems for Telemetry {#balm_streampublisher-alternative-systems-for-telemetry}
///
///
/// Bloomberg software may alternatively use the GUTS telemetry API, which is
/// integrated into Bloomberg infrastructure.
///
/// ## Usage {#balm_streampublisher-usage}
///
///
/// This section illustrates intended use of this component.
///
/// ### Example 1: Basic Usage {#balm_streampublisher-example-1-basic-usage}
///
///
/// In the following example we illustrate how to create and publish records
/// with a `balm::StreamPublisher`.  First we define a couple of metric ids.
/// Note that we create the `balm::MetricId` objects 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 descA(&myCategory, "MetricA");
/// balm::MetricDescription descB(&myCategory, "MetricB");
///
/// balm::MetricId metricA(&descA);
/// balm::MetricId metricB(&descB);
/// @endcode
/// Now we create a `balm::StreamPublisher` object, supplying it the `stdout`
/// stream:
/// @code
/// balm::StreamPublisher myPublisher(bsl::cout);
/// @endcode
/// Next we create a metric sample containing some records and pass it to the
/// `balm::StreamPublisher` we created.  Note that because we are not actually
/// collecting the metrics we set the elapsed time of the sample to an
/// arbitrary 5s interval.
/// @code
/// bslma::Allocator *allocator = bslma::Default::allocator(0);
/// bsl::vector<balm::MetricRecord> records(allocator);
///
/// records.push_back(balm::MetricRecord(metricA, 5, 25.0, 6.0, 25.0));
/// records.push_back(balm::MetricRecord(metricB, 2,  7.0, 3.0, 11.0));
///
/// balm::MetricSample sample(allocator);
///
/// sample.setTimeStamp(bdlt::DatetimeTz(bdlt::CurrentTime::utc(), 0));
/// sample.appendGroup(records.data(),
///                    static_cast<int>(records.size()),
///                    bsls::TimeInterval(5, 0));
///
/// myPublisher.publish(sample);
/// @endcode
/// The output of this example would look similar to:
/// @code
/// 05FEB2009_19:52:11.723+0000 2 Records
///     Elapsed Time: 5s
///         MyCategory.MetricA [ count = 5, total = 25, min = 6, max = 25 ]
///         MyCategory.MetricB [ count = 2, total = 7, min = 3, max = 11 ]
/// @endcode
/// @}
/** @} */
/** @} */
 
/** @addtogroup bal
 * @{
 */
/** @addtogroup balm
 * @{
 */
/** @addtogroup balm_streampublisher
 * @{
 */
 
#include <balscm_version.h>
 
#include <balm_publisher.h>
 
#include <bsl_iosfwd.h>
 
 
 
 
namespace balm {
 
class MetricSample;
 
                           // =====================
                           // class StreamPublisher
                           // =====================
 
/// This class provides an implementation of the `Publisher` protocol.
/// This stream publisher publishes recorded metric values to an output
/// stream specified at construction.
///
/// See @ref balm_streampublisher 
class StreamPublisher : public Publisher {
 
    // DATA
    bsl::ostream& d_stream;   // stream to which to write data
 
  private:
    // NOT IMPLEMENTED
    StreamPublisher(const StreamPublisher& );
    StreamPublisher& operator=(const StreamPublisher& );
 
  public:
    // CREATORS
 
    /// Create a streampublisher and initialize it to publish metrics to
    /// the specified `stream`.
    StreamPublisher(bsl::ostream& stream);
 
    /// Destroy this stream publisher.
    virtual ~StreamPublisher();
 
    // MANIPULATORS
 
    /// Publish the specified `metricValues` to the output stream specified
    /// at construction.
    virtual void publish(const MetricSample& metricValues);
};
 
// ============================================================================
//                            INLINE DEFINITIONS
// ============================================================================
 
                           // ---------------------
                           // class StreamPublisher
                           // ---------------------
 
// CREATORS
inline
StreamPublisher::StreamPublisher(bsl::ostream& stream)
: d_stream(stream)
{
}
 
}  // 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 ----------------------------------
 
/** @} */
/** @} */
/** @} */