Merge pull request #1 from basho/docs

Bugfixes and docs.

README.org

@@ -0,0 +1,35 @@
+* basho_metrics
+** Overview
+basho_metrics is an open source Erlang library for efficient calculation of service performance metrics.
+
+basho_metrics is inspired by and provides a subset of the functionality of Coda Hale's 
+[[https://github.com/codahale/metrics/][Metrics]] package.
+
+** Quick Start
+   You must have [[http://erlang.org/download.html][Erlang/OTP R13B04]] or later and a GNU-style build
+   system to compile and run =basho_metrics=. 
+** Contributing
+   We encourage contributions to =basho_metrics= from the community.
+
+   1) Fork the =basho_metrics= repository on [[https://github.com/basho/basho_metrics][Github]].
+   2) Clone your fork or add the remote if you already have a clone of
+      the repository.
+#+BEGIN_SRC shell
+git clone git@github.com:yourusername/basho_metrics.git
+# or
+git remote add mine git@github.com:yourusername/basho_metrics.git
+#+END_SRC
+   3) Create a topic branch for your change.
+#+BEGIN_SRC shell
+git checkout -b some-topic-branch
+#+END_SRC
+   4) Make your change and commit. Use a clear and descriptive commit
+      message, spanning multiple lines if detailed explanation is
+      needed.
+   5) Push to your fork of the repository and then send a pull-request
+      through Github.
+#+BEGIN_SRC shell
+git push mine some-topic-branch
+#+END_SRC
+   6) A Basho engineer or community maintainer will review your patch
+      and merge it into the main repository or send you feedback.

c_src/basho_metrics_nifs.cpp

@@ -1,6 +1,10 @@
 // -------------------------------------------------------------------
+//
+// basho_metrics:  fast performance metrics for Erlang.
 // 
-// basho_metrics_nifs:  fast performance metrics for erlang
+// inspired and partially derived from Coda Hale's 'metrics' 
+// Copyright (c) 2010-2001 Coda Hale
+// https://github.com/codahale/metrics/blob/development/LICENSE.md
 //
 // Copyright (c) 2011 Basho Technologies, Inc. All Rights Reserved.
 //

c_src/basho_metrics_nifs.h

@@ -1,6 +1,10 @@
 // -------------------------------------------------------------------
 //
-// basho_metrics:  fast performance metrics for Erlang. 
+// basho_metrics:  fast performance metrics for erlang
+// 
+// inspired and partially derived from Coda Hale's 'metrics' 
+// Copyright (c) 2010-2001 Coda Hale
+// https://github.com/codahale/metrics/blob/development/LICENSE.md
 //
 // Copyright (c) 2011 Basho Technologies, Inc. All Rights Reserved.
 //

c_src/ewma.hpp

@@ -1,6 +1,10 @@
 // -------------------------------------------------------------------
 //
 // basho_metrics:  fast performance metrics for Erlang.
+// 
+// inspired and partially derived from Coda Hale's 'metrics' 
+// Copyright (c) 2010-2001 Coda Hale
+// https://github.com/codahale/metrics/blob/development/LICENSE.md
 //
 // Copyright (c) 2011 Basho Technologies, Inc. All Rights Reserved.
 //
@@ -24,6 +28,13 @@
 
 #include <cmath>
 
+/**
+ * An exponentially-weighted moving average.
+ *
+ * UNIX Load Average Part 1: How It Works: http://www.teamquest.com/pdfs/whitepaper/ldavg1.pdf
+ * 
+ * UNIX Load Average Part 2: Not Your Average Average: http://www.teamquest.com/pdfs/whitepaper/ldavg2.pdf
+ */
 class ewma
 {
     static const double NANOS = 1000000000.0;
@@ -35,11 +46,17 @@ class ewma
           interval_(interval*NANOS),
           initialized_(false) { } 
 
+    /**
+     * Update the moving average with a new value.
+     */
     void update(long n) 
     {
         uncounted_ += n;
     }
 
+    /**
+     * Mark the passage of time and decay the current rate accordingly.
+     */
     void tick()
     {
         std::size_t count = uncounted_;
@@ -54,7 +71,6 @@ class ewma
         }
     }
 
-
     double rate() const
     {
         return rate_ * (double)NANOS;

c_src/histogram_metric.hpp

@@ -1,6 +1,10 @@
 // -------------------------------------------------------------------
 //
-// basho_metrics: fast performance metrics for Erlang. 
+// basho_metrics:  fast performance metrics for Erlang.
+// 
+// inspired and partially derived from Coda Hale's 'metrics' 
+// Copyright (c) 2010-2001 Coda Hale
+// https://github.com/codahale/metrics/blob/development/LICENSE.md
 //
 // Copyright (c) 2011 Basho Technologies, Inc. All Rights Reserved.
 //
@@ -29,6 +33,12 @@
 #include "sample.hpp"
 
 
+/**
+ * A metric which calculates the distribution of a value.
+ *
+ * @see <a href="http://www.johndcook.com/standard_deviation.html">Accurately
+ * computing running variance</a>
+ */
 template <typename IntType=unsigned long>
 class histogram
 {
@@ -41,16 +51,22 @@ class histogram
       count_(0),
       variance_(-1, 0) { } 
 public:
+    /**
+     * Clears all recorded values.
+     */
     void clear() 
     {
         sample_.clear();
-        min_ = std::numeric_limits<IntType>::max(),
-        max_ = std::numeric_limits<IntType>::min(),
+        min_ = std::numeric_limits<IntType>::max();
+        max_ = std::numeric_limits<IntType>::min();
         sum_ = 0;
         count_ = 0;
         variance_ = std::make_pair(-1, 0);
     }
-
+
+    /**
+     * Adds a recorded value.
+     */        
     void update(IntType value)
     {
         ++count_;
@@ -60,58 +76,76 @@ class histogram
         sum_ += value;
         update_variance(value);
     }
+
+    /**
+     * Returns the largest recorded value.
+     */
+    double max() const 
+    {
+        if (count_ > 0) 
+            return max_;
+        return 0.0;
+    }
 
-   double max() const 
-   {
-       if (count_ > 0) 
-           return max_;
-       return 0.0;
-   }
-
-   double min() const
-   {
-       if (count_ > 0) 
-           return min_;
-       return 0.0;
-   }
-
-   double mean() const
-   {
-       if (count_ > 0) 
-           return sum_ / (double) count_;
-       return 0.0;
-   }
-
-   double stddev() const 
-   {
-       if (count_ > 0) 
-           return std::sqrt(variance());
-       return 0.0;
-   }
-
-   IntType count() const 
-   { 
-       return count_; 
-   }
+    /**
+     * Returns the smallest recorded value.
+     */    
+    double min() const
+    {
+        if (count_ > 0) 
+            return min_;
+        return 0.0;
+    }
 
-   struct calc_percentile
-   {
-       calc_percentile(const std::vector<IntType>& values)
-           : values_(values) { }
+    /**
+     * Returns the arithmetic mean of all recorded values.
+     */
+    double mean() const
+    {
+        if (count_ > 0) 
+            return sum_ / (double) count_;
+        return 0.0;
+    }
 
-       double operator()(double percentile) const
-       {
-           double pos(percentile * (values_.size() + 1));
-           if (pos < 1) return values_[0];
-           if (pos >= values_.size()) return values_[values_.size()-1];
-           double lower = values_[((int)pos)-1];
-           double upper = values_[(int)pos];
-           return lower+(pos-std::floor(pos))*(upper-lower);
-       }
-   private:
-       const std::vector<IntType>& values_;
-   };
+    /**
+     * Returns the standard deviation of all recorded values.
+     */    
+    double stddev() const 
+    {
+        if (count_ > 0) 
+            return std::sqrt(variance());
+        return 0.0;
+    }
+
+    /**
+     * Returns the number of values recorded.
+     */
+    IntType count() const 
+    { 
+        return count_; 
+    }
+
+    struct calc_percentile
+    {
+        calc_percentile(const std::vector<IntType>& values)
+            : values_(values) { }
+
+        double operator()(double percentile) const
+        {
+            double pos(percentile * (values_.size() + 1));
+            if (pos < 1) return values_[0];
+            if (pos >= values_.size()) return values_[values_.size()-1];
+            double lower = values_[((int)pos)-1];
+            double upper = values_[(int)pos];
+            return lower+(pos-std::floor(pos))*(upper-lower);
+        }
+    private:
+        const std::vector<IntType>& values_;
+    };
 
+    /**
+     * Returns an array of values at percentiles passed in pvec
+     */    
     std::vector<double> percentiles(const std::vector<double> pvec)
     {
         std::vector<double> scores(pvec.size(), 0.0);
@@ -129,7 +163,7 @@ class histogram
     {
         if (count_ <= 1) 
             return 0.0;
-        return variance_.first / (count_- 1);
+        return variance_.second / (count_- 1);
     }
 
     void update_variance(IntType value)

c_src/meter_metric.hpp

@@ -1,6 +1,10 @@
 // -------------------------------------------------------------------
 //
 // basho_metrics:  fast performance metrics for erlang
+// 
+// inspired and partially derived from Coda Hale's 'metrics' 
+// Copyright (c) 2010-2001 Coda Hale
+// https://github.com/codahale/metrics/blob/development/LICENSE.md
 //
 // Copyright (c) 2011 Basho Technologies, Inc. All Rights Reserved.
 //
@@ -24,6 +28,12 @@
 
 #include "ewma.hpp"
 
+/**
+ * A meter metric which measures mean throughput and one-, five-, and
+ * fifteen-minute exponentially-weighted moving average throughputs.
+ *
+ * http://en.wikipedia.org/wiki/Moving_average#Exponential_moving_average
+ */
 template <typename IntType=unsigned long>
 class meter
 {
@@ -34,18 +44,28 @@ class meter
           five_(alpha_five()),
           fifteen_(alpha_fifteen()) { } 
 
+
+    /**
+     * Updates the moving averages.
+     */
     void tick()
     {
         one_.tick();
         five_.tick();
         fifteen_.tick();
     }
 
+    /**
+     * Mark the occurrence of an event.
+     */
     void mark()
     {
         mark(1);
     }
 
+    /**
+     * Mark the occurrence of a given number of events.
+     */
     void mark(IntType n)
     {
         count_ += n;
@@ -54,21 +74,45 @@ class meter
         fifteen_.update(n);
     }
 
+    /**
+     * Returns the number of events which have been marked.
+     */
     unsigned long count() const 
     {
         return count_;
     }
-
+
+    /**
+     * Returns the one-minute exponentially-weighted moving average rate at
+     * which events have occurred since the meter was created.
+     *
+     * This rate has the same exponential decay factor as the one-minute load
+     * average in the 'top' Unix command.
+     */    
     double one() const 
     {
         return one_.rate();
     }
 
+    /**
+     * Returns the five-minute exponentially-weighted moving average rate at
+     * which events have occurred since the meter was created.
+
+     * This rate has the same exponential decay factor as the five-minute load
+     * average in the 'top' Unix command.
+     */
     double five() const
     {
         return five_.rate();
     }
 
+    /**
+     * Returns the fifteen-minute exponentially-weighted moving average rate at
+     * which events have occurred since the meter was created.
+     * <p>
+     * This rate has the same exponential decay factor as the fifteen-minute 
+     * load average in the 'top' Unix command.
+     */    
     double fifteen() const
     {
         return fifteen_.rate();