Permalink
Browse files

Add new metric and sample types to README

  • Loading branch information...
russelldb committed Jul 11, 2012
1 parent 270dfb2 commit 2a71194435d69f292df26c31555f39a540ca233b
Showing with 46 additions and 0 deletions.
  1. +46 −0 README.md
View
@@ -73,6 +73,45 @@ Histograms are collections of values that have statistical analysis done to them
> folsom_metrics:histogram_timed_update(Name, Fun).
> folsom_metrics:notify({Name, Value}).
+###### Histogram sample types
+
+Each histogram draws its values from a `reservoir` of readings. You can select a `sample type` for a histogram by passing the name of the sample type as an atom when you create a new histogram.
+Some sample types have further arguments. The purpose of a sample type is to control the size and charecteristics of the reservoir of readings the histogram performs analysis upon.
+
+Folsom currently provides the following sample types:
+
+###### `uniform`
+
+This is a random uniform sample over the stream of readings. This is the default sample type, bounded in size to 1028 readings. When `size` readings have been taken, new readings replace older readings
+in the reservoir at random. You can set the sample size at creation time:
+
+ > folsom_metrics:new_histogram(Name, uniform, Size::integer()).
+
+Be sure you understand _why_ before you do this.
+
+###### `exdec`
+
+This is a sample that exponentially decays less significant readings over time so as to give greater significance to newer readings. Read more here -
+[Forward Decay...](http://www.research.att.com/people/Cormode_Graham/library/publications/CormodeShkapenyukSrivastavaXu09.pdf).
+Again you can change defaults at creation time, if you think you need to:
+
+ > folsom_metrics:new_histogram(Name, exdec, Size::integer(), Alpha::float()).
+
+###### `slide`
+
+This is a sliding window in time over a stream of readings. The default window size is 60 seconds. Every reading that occurs in a sliding sixty second window is stored,
+with older readings being discarded. If you have a lot of readings per
+minute the `reservoir` may get pretty big and so it will take more time to calculate statistics. You can set the `window` size by providing a number of seconds.
+
+ > folsom_metrics:new_histogram(Name, slide, Seconds::integer()).
+
+###### `slide_uniform`
+
+This is a sliding window in time over a stream of readings with a random uniform sample per second, to bound the size of the total number of readings. The maximum size of the reservoir will be
+ `window size * sample size`. Default is a window of 60 seconds and a sample size of 1028. Again, you can change these at creation time:
+
+ > folsom_metrics:new_histogram(Name, slide_uniform, {Secs::interger(), Size::integer()).
+
##### Histories
Histories are a collection of past events, such as errors or log messages.
@@ -88,6 +127,13 @@ Meters are increment only counters with mean rates and exponentially weighted mo
> folsom_metrics:new_meter(Name).
> folsom_metrics:notify({Name, Value}).
+###### `Spiral` meter
+
+A `spiral` is a type of meter that has a one minute sliding window count. The meter tracks an increment only counter and a total for the last minute. This is a sliding count with older readings dropping off per second.
+
+ > folsom_metrics:new_spiral(Name).
+ > folsom_metrics:notify({Name, Count}).
+
##### Meter Reader
Meter readers are like a meter except that the values passed to it are monotonically increasing, e.g., reading from a water or gas meter, CPU jiffies, or I/O operation count.

0 comments on commit 2a71194

Please sign in to comment.