senf/Utils/Statistics.hh

   1 // $Id$
   2 //
   3 // Copyright (C) 2008
   4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
   5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
   6 //     Stefan Bund <g0dil@berlios.de>
   7 //
   8 // This program is free software; you can redistribute it and/or modify
   9 // it under the terms of the GNU General Public License as published by
  10 // the Free Software Foundation; either version 2 of the License, or
  11 // (at your option) any later version.
  12 //
  13 // This program is distributed in the hope that it will be useful,
  14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 // GNU General Public License for more details.
  17 //
  18 // You should have received a copy of the GNU General Public License
  19 // along with this program; if not, write to the
  20 // Free Software Foundation, Inc.,
  21 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  22
  23 /** \file
  24     \brief Statistics public header */
  25
  26 #ifndef HH_SENF_Utils_Statistics_
  27 #define HH_SENF_Utils_Statistics_ 1
  28
  29 // Custom includes
  30 #include <map>
  31 #include <vector>
  32 #include <deque>
  33 #include <boost/iterator/transform_iterator.hpp>
  34 #include <boost/range/iterator_range.hpp>
  35 #include <boost/utility.hpp>
  36 #include <boost/ptr_container/ptr_vector.hpp>
  37 #include <boost/signals.hpp>
  38 #include "Exception.hh"
  39 #include <senf/Utils/Logger/Logger.hh>
  40 #include <senf/Utils/Console/Console.hh>
  41
  42 //#include "Statistics.mpp"
  43 ///////////////////////////////hh.p////////////////////////////////////////
  44
  45 namespace senf {
  46
  47     /** \defgroup senf_statistics Statistics
  48
  49         The statistics functionality has two parts:
  50
  51         \li the senf::Statistics class
  52         \li statistics sources
  53
  54         Each senf::Statistics instance collects information about a single parameter. Which
  55         parameter is set up by connecting the Statistics instance with an arbitrary statistics
  56         source.
  57
  58         %Statistics sources are <a href="http://www.boost.org/doc/libs/release/doc/html/signals.html">
  59         Boost Signals</a> which are emitted periodically to provide new data.
  60      */
  61
  62     class Collector;
  63     class Statistics;
  64
  65     /** \brief Internal: Generic Statistics collection */
  66     class StatisticsBase
  67     {
  68         typedef std::map<unsigned, Collector> Children;
  69
  70         struct Transform {
  71             typedef Children::value_type & first_argument_type;
  72             typedef Collector & result_type;
  73             result_type operator()(first_argument_type i) const;
  74         };
  75
  76         typedef boost::transform_iterator<Transform,Children::iterator> ValueIterator;
  77
  78         struct OutputEntry;
  79
  80     public:
  81         ///////////////////////////////////////////////////////////////////////////
  82         // Types
  83
  84         typedef boost::iterator_range<ValueIterator> CollectorRange;
  85
  86         /** \brief Output connection interface
  87
  88             This class is returned from senf::StatisticsBase::output() and the derived
  89             <tt>output()</tt> implementations to allow connecting an output with an arbitrary
  90             target.
  91
  92             There are two types of targets:
  93             \li <em>Externally managed targets</em>. These targets live outside of the statistics
  94                 module, just a reference to those targets is saved. The target should derive from
  95                 <tt>boost::signals::trackable</tt> to ensure they are automatically disconnected
  96                 when destroyed.
  97             \li <em>Internally managed targets</em>. Those targets are owned by the statistics
  98                 module and will be destroyed when the statistics class is destroyed.
  99
 100             Externally managed targets are passed by non-const reference to connect(), internally
 101             managed targets are passed using <tt>std::auto_ptr</tt>.
 102
 103             A target is any callable object which takes three float values as argument: The current
 104             minimum, average and maximum value.
 105
 106             \code
 107             // Simple function as statistics target
 108             void collect(float min, float avg, float max)
 109                 { ... }
 110
 111             // Function object
 112             struct Collector
 113             {
 114                 void operator()(float min, float avg, float max, float dev)
 115                     { ... }
 116             };
 117             \endcode
 118
 119            \ingroup senf_statistics
 120          */
 121         template <class Owner>
 122         class OutputProxy
 123         {
 124         public:
 125             template <class Target> Owner & connect(Target & target,
 126                                                     std::string label="") const;
 127                                         ///< Connect externally managed target
 128             template <class PTarget> Owner & connect(std::auto_ptr<PTarget> target,
 129                                                      std::string label="") const;
 130                                         ///< Connect internally managed target
 131             Owner & noconnect() const;  ///< Don't connect the output
 132             senf::console::ScopedDirectory<> & dir() const;
 133                                         ///< Get target's console directory
 134
 135 #ifdef DOXYGEN
 136         private:
 137 #endif
 138             OutputProxy(Owner * owner, OutputEntry * entry);
 139             template <class OtherOwner>
 140             OutputProxy(Owner * owner, OutputProxy<OtherOwner> const & other);
 141
 142         private:
 143             Owner * owner_;
 144             OutputEntry * entry_;
 145
 146             template <class OtherOwner> friend class OutputProxy;
 147         };
 148
 149         ///////////////////////////////////////////////////////////////////////////
 150         ///\name Accessing the current value
 151         ///\{
 152
 153         float min() const;              ///< Last min value entered
 154         float avg() const;              ///< Last avg value entered
 155         float max() const;              ///< Last max value entered
 156         float dev() const;              ///< Last dev value entered
 157
 158         virtual unsigned rank() const;  ///< Return collectors rank value
 159                                         /**< \returns number of basic values collected into each new
 160                                              value by this collector. */
 161
 162         ///\}
 163         ///////////////////////////////////////////////////////////////////////////
 164         ///\name Child collectors
 165         ///\{
 166
 167         Collector & operator[](unsigned rank);
 168                                         ///< Get child collector
 169                                         /**< This member will return a reference to the collector
 170                                              collecting \a rank values.
 171                                              \param[in] rank Number of values the requested
 172                                                  collector collects into each combined value.
 173                                              \throws InvalidRankException if \a rank is not a valid
 174                                                  registered rank value. */
 175         CollectorRange collectors();    ///< List all child collectors
 176                                         /**< \returns iterator range of child collector
 177                                              references */
 178
 179         Collector & collect(unsigned rank); ///< Register a new collector
 180                                         /**< Adds a collector collecting \a rank values into each
 181                                              combined value.
 182                                              \param[in] rank number of values to collect
 183                                              \returns Reference to new collector
 184                                              \throws DuplicateRankException if a collector
 185                                                  collecting \a rank values already exists. */
 186
 187         Statistics & base();            ///< Get base statistics object
 188                                         /**< Returns the base statistics object. If this is
 189                                              a child collector, this will return the outermost
 190                                              statistics object, otherwise it will return
 191                                              \c *this. */
 192
 193         std::string path() const;       ///< Get the path to this collector
 194                                         /**< Returns the '-'-separated list of collectors up to
 195                                              here. If this is the basic statistics object, the value
 196                                              is empty, otherwise it is built by joining the
 197                                              collector ranks. */
 198
 199         ///\}
 200         ///////////////////////////////////////////////////////////////////////////
 201         ///\name Result generation
 202
 203         OutputProxy<StatisticsBase> output(unsigned n = 1u);
 204                                         ///< Register output
 205                                         /**< This call will request the collector to output
 206                                              statistics build by averaging the last \a n
 207                                              values. This output is generated for every new value in
 208                                              the collector. The output signal can be connected to an
 209                                              arbitrary target using the returned proxy. Example:
 210                                              \code
 211                                              stats.output(4u).connect(
 212                                                  senf::StatisticsLogger());
 213                                              \endcode
 214                                              \param[in] n size of sliding average window */
 215
 216         ///\}
 217         ///////////////////////////////////////////////////////////////////////////
 218         // Exceptions
 219
 220         struct InvalidRankException : public senf::Exception
 221         { InvalidRankException() : senf::Exception("Invalid rank value") {} };
 222
 223         struct DuplicateRankException : public senf::Exception
 224         { DuplicateRankException() : senf::Exception("Duplicate rank value") {} };
 225
 226         void consoleList(unsigned level, std::ostream & os) const;
 227
 228     protected:
 229         StatisticsBase();
 230         virtual ~StatisticsBase();
 231         void enter(unsigned n, float min, float avg, float max, float dev);
 232
 233     private:
 234         virtual Statistics & v_base() = 0;
 235         virtual std::string v_path() const = 0;
 236
 237         void generateOutput();
 238
 239         float min_;
 240         float avg_;
 241         float max_;
 242         float dev_;
 243         Children children_;
 244
 245         struct QueueEntry {
 246             float min;
 247             float avg;
 248             float max;
 249             float dev;
 250             QueueEntry() : min(), avg(), max(), dev() {}
 251             QueueEntry(float min_, float avg_, float max_, float dev_)
 252                 : min(min_), avg(avg_), max(max_), dev(dev_) {}
 253         };
 254         typedef std::deque<QueueEntry> Queue;
 255         Queue queue_;
 256
 257         struct OutputEntry {
 258             struct TargetBase
 259             {
 260                 explicit TargetBase(std::string const & label_) : label (label_) {}
 261                 virtual ~TargetBase() {};
 262                 std::string label;
 263             };
 264
 265             template <class PTarget>
 266             struct Target : public TargetBase
 267             {
 268                 boost::scoped_ptr<PTarget> target_;
 269                 Target(std::auto_ptr<PTarget> target, std::string const & label)
 270                     : TargetBase (label), target_ (target.release()) {}
 271                 explicit Target(std::string const & label)
 272                     : TargetBase (label), target_ (0) {}
 273             };
 274
 275             OutputEntry();
 276             explicit OutputEntry(unsigned n_);
 277             OutputEntry(const OutputEntry& other);
 278             OutputEntry& operator=(const OutputEntry& other);
 279
 280             void initDir();
 281             void consoleList(std::ostream & os);
 282
 283             unsigned n;
 284             float min;
 285             float avg;
 286             float max;
 287             float dev;
 288
 289             boost::signal<void(float,float,float,float)> signal;
 290             boost::ptr_vector<TargetBase> targets_;
 291
 292             senf::console::ScopedDirectory<> dir;
 293         };
 294         typedef std::map<unsigned, OutputEntry> OutputMap;
 295         OutputMap outputs_;
 296         unsigned maxQueueLen_;
 297     };
 298
 299     /** \brief  Collect statistics and generate %log messages
 300
 301         The Statistics class collects information about a single value. The assumption is, that
 302         Statistics::operator() is called \e periodically to supply new data.
 303
 304         Each data entry is comprised of a minimum, average and maximum value. These values should
 305         describe the value of whatever parameter is analyzed by a Statistics instance over the last
 306         period. The length of the period is defined by the interval, at which data is entered.
 307
 308         The Statistics class combines successive data values into ever larger groups. These groups
 309         form a tree where each node combines a fixed number of data values of it's parent node. An
 310         example:
 311
 312         Let us assume, that Statistics::operator() is called every 100ms. We can than build a chain
 313         of collectors:
 314         \li The basic statistics module provides information with a resolution of 1/10th of a second
 315         \li A collector collecting 10 values provides information with 1 second resolution
 316         \li The next collector collects 60 values and provides a resolution of 1 minute
 317         \li Again the next collector collects 60 values and provides a resolution of 1 hour
 318         \li ... and so on
 319
 320         This way, we create a hierarchy of values. Each collector manages a minimum, average and
 321         maximum value always created over it's the last complete interval.
 322
 323         It is possible to have more than one collector based on the same basic interval. In above
 324         scenario, we might want to add another collector which for example collects information
 325         with a 100 second scale. This is possible and changes the list of collectors into a tree.
 326
 327         Now to turn all this into code:
 328
 329         \code
 330         senf::ppi::module::RateAnalyzer rateAnalyzer;
 331         senf::Statistics packetStats;
 332
 333         rateAnalyzer.signals.packetsPerSecond.connect(boost::ref(packetStats));
 334
 335         packetStats                      // called 10 times / second
 336             .collect(10u)                // seconds
 337             .collect(60u)                // minutes
 338             .collect(60u);               // hours
 339
 340         packetStats[10u].collect(100u);  // 100 seconds
 341
 342         rateAnalyzer.startStatistics(senf::ClockService::milliseconds(100u));
 343         \endcode
 344
 345         This code will collect the statistics as described in the Example above. However, no output
 346         will be generated.
 347
 348         For every collector, any number of outputs may be defined. Each output consists of the
 349         number of values to calculate a sliding average over and an identifying label.
 350
 351         Lets say, we want to produce the following outputs:
 352         \li A sliding average of 5 values based on the raw 1/10th second data.
 353         \li Three different outputs from the seconds staistics: current value without average,
 354             sliding average over 10 seconds and sliding average over 60 seconds.
 355         \li Output the minutes and hourly value without averaging.
 356
 357         To achieve this, we can augment above code in the following way:
 358
 359         \code
 360         packetStats
 361                 .output( 5u).connect(senf::StatisicsLogger("pps 100ms 5"))
 362             .collect(10u)
 363                 .output(   ).noconnect()
 364                 .output(10u).connect(senf::StatisicsLogger("pps 1s 10"))
 365                 .output(60u).connect(senf::StatisicsLogger("pps 1s 60"))
 366             .collect(60u)
 367                 .output(   ).connect(senf::StatisicsLogger("pps 1min 1"))
 368             .collect(60u)
 369                 .output(   ).connect(senf::StatisicsLogger("pps 1h 1"));
 370
 371         packetStats.output(5u).connect(
 372             senf::StatisticsLogger<senf::log::Debug, senf::log::VERBOSE>("pps"));
 373
 374         senf::log::FileTarget statslog ("stats.log");
 375
 376         statslog.showArea(false);
 377         statslog.showLevel(false);
 378         statslog.tag("");
 379         statslog.timeFormat("");
 380
 381         statslog.route<senf::StatisticsStream>();
 382         \endcode
 383
 384         We use a StatisticsLogger to send the %log messages to the senf::StatisticsStream %log
 385         stream. The stream, area an level to send the statistics %log messages to may be configured
 386         using template arguments to StatisticsLogger.
 387
 388         It is also possible to skip sending the output to any target or send one output to several
 389         targets.
 390
 391         Here we have opted to use a label which explicitly describes the name of the variable, the
 392         basic interval and the size of the sliding average window. However, the label is completely
 393         arbitrary.
 394
 395         All output is generated using the Senf Logger on the senf::StatisticsStream %log stream. In
 396         the example above, we have configured a special logfile \c stats.log which contains the
 397         statistics values each prefixed with a timestamp in nanoseconds (but no further information
 398         like %log level or tag):
 399         <pre>
 400         0000000000.000000000 pps 100ms 5 43.3 43.3 43.3
 401         0000000000.010311928 pps 100ms 5 42.5 42.5 42.5
 402         ...
 403         0000000001.002413391 pps 100ms 5 62.0 62.0 62.0
 404         0000000001.003920018 pps 1s 1 42.1 53.4 62.0
 405         ...
 406         </pre>
 407         (the nanosecond values will of course be somewhat different ...)
 408
 409         \see senf::StatisticsBase::OutputProxy for the output proxy (connect) interface
 410         \ingroup senf_statistics
 411      */
 412     class Statistics
 413         : public StatisticsBase, boost::noncopyable
 414     {
 415     public:
 416 #ifndef SENF_DISABLE_CONSOLE
 417         console::ScopedDirectory<Statistics> dir;
 418 #endif
 419
 420         Statistics();
 421
 422         void operator()(unsigned n, float min, float avg, float max, float dev);
 423                                         ///< Enter new data
 424                                         /**< This member must be called whenever new data is
 425                                              available.
 426
 427                                              If \a min and \a max values are not available, this
 428                                              member should be called with \a min, \a avg and \a max
 429                                              set to the same value. If no error estimate is
 430                                              available, call with \a dev = 0.
 431
 432                                              In the most common case, this member is to be called
 433                                              periodically and \a n will be 1 on all calls. The
 434                                              interval, at which this member is called then defines
 435                                              the statistics time scale.
 436
 437                                              Calling with \a n > 1 will submit the value \a n
 438                                              times. This makes it possible to aggregate multiple
 439                                              time slices into a single call. This does not change
 440                                              the basic time scale but can change the number of
 441                                              submits per unit time. If the basic time slice is
 442                                              small, this allows to submit values almost arbitrarily
 443                                              non-periodic.
 444
 445                                              \param[in] n number of time-slices
 446                                              \param[in] min minimal data value since last call
 447                                              \param[in] avg average data value since last call
 448                                              \param[in] max maximal data values since last call
 449                                              \param[in] dev standard deviation of avg value */
 450         void operator()(float min, float avg, float max, float dev=0.0f);
 451                                         ///< Same as operator() with \a n==1
 452                                         /**< Provided so a Statistics instance can be directly used
 453                                              as a signal target. */
 454         void operator()(float value, float dev=0.0f);
 455                                         ///< Same as operator() with \a min == \a avg == \a max
 456                                         /**< Provided so a Statistics instance can be directly used
 457                                              as a signal target. */
 458
 459         StatisticsBase::OutputProxy<Statistics> output(unsigned n = 1u);
 460
 461         void consoleList(std::ostream & os);
 462         void consoleCollect(std::vector<unsigned> & ranks);
 463         boost::shared_ptr<senf::console::DirectoryNode> consoleOutput(
 464             std::vector<unsigned> & ranks, unsigned window);
 465
 466     private:
 467         Statistics & v_base();
 468         std::string v_path() const;
 469     };
 470
 471     /** \brief Accumulated statistics collector
 472
 473         This class collects accumulated statistics. It is automatically created by
 474         senf::Statistics::collect()
 475
 476         \see senf::Statistics
 477      */
 478     class Collector : public StatisticsBase
 479     {
 480     public:
 481         virtual unsigned rank() const;
 482
 483         StatisticsBase::OutputProxy<Collector> output(unsigned n = 1u);
 484
 485     private:
 486         Collector(StatisticsBase * owner, unsigned rank);
 487         void enter(unsigned n, float min, float avg, float max, float dev);
 488         Statistics & v_base();
 489         std::string v_path() const;
 490
 491         unsigned rank_;
 492         unsigned i_;
 493         float accMin_;
 494         float accSum_;
 495         float accSumSq_;
 496         float accMax_;
 497         StatisticsBase * owner_;
 498
 499         friend class StatisticsBase;
 500     };
 501
 502 }
 503
 504 ///////////////////////////////hh.e////////////////////////////////////////
 505 #include "Statistics.cci"
 506 //#include "Statistics.ct"
 507 #include "Statistics.cti"
 508 #endif
 509
 510 \f
 511 // Local Variables:
 512 // mode: c++
 513 // fill-column: 100
 514 // comment-column: 40
 515 // c-file-style: "senf"
 516 // indent-tabs-mode: nil
 517 // ispell-local-dictionary: "american"
 518 // compile-command: "scons -u test"
 519 // End: