Permalink
Browse files

Merge pull request #1 from basho/docs

Bugfixes and docs.
  • Loading branch information...
2 parents 5531774 + 404bcce commit 5bd4bcb339f3eb0de94f9d73e1039248c5825fa6 @argv0 argv0 committed Sep 1, 2011
Showing with 270 additions and 70 deletions.
  1. +35 −0 README.org
  2. +5 −1 c_src/basho_metrics_nifs.cpp
  3. +5 −1 c_src/basho_metrics_nifs.h
  4. +17 −1 c_src/ewma.hpp
  5. +87 −53 c_src/histogram_metric.hpp
  6. +45 −1 c_src/meter_metric.hpp
  7. +57 −2 c_src/sample.hpp
  8. +19 −11 src/basho_metrics_nifs.erl
View
@@ -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.
@@ -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.
//
@@ -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.
//
View
@@ -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;
View
@@ -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)
View
@@ -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();
Oops, something went wrong.

0 comments on commit 5bd4bcb

Please sign in to comment.