Steve Losh avatar Steve Losh committed 6eb0284

Moar docs.

Comments (0)

Files changed (8)

docs/source/contributing.rst

+Contributing
+============
+
+Want to contribute?  Cool.  Send a pull request.
+
+Run the test cases first with ``lein test`` to make sure you're not crazy.
+
+Fixing a bug?  Add a test case in ``test/``.
+
+Adding a feature?  Add some documentation in ``docs/``.

docs/source/counters.rst

 Counters
 ========
 
+Counters are values you can increment and decrement.
+
 Creating
 --------
 
 
     (def users-connected (counter "users-connected"))
 
-Reading
--------
-
 Writing
 -------
 
     (dec! users-connected)
     (dec! users-connected 2)
 
+Reading
+-------
 
+There's only one way to get data from a counter.
+
+``value``
+~~~~~~~~~
+
+You can get the current value of a counter with ``value``::
+
+    (use '[metrics.counters :only (value)])
+
+    (value users-connected)

docs/source/gauges.rst

       (gauge-fn "files-open"
              #(return-number-of-files-open ...)))
 
+Writing
+-------
+
+There is no writing.  Gauges execute the form(s) (or function) you passed when
+creating them every time they're read.  You don't need to do anything else.
+
 Reading
 -------
 
+There's only one way to get data from a gauge.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+
+``value``
+~~~~~~~~~
+
 You can read the value of a gauge at any time with ``value``::
 
     (use '[metrics.gauges :only (value)])

docs/source/histograms.rst

 Histograms
 ==========
 
+Histograms are used to record the distribution of a piece of data over time.
+
 Creating
 --------
 
     (def search-results-returned-biased
       (histogram "search-results-returned-biased" true))
 
-Reading
--------
-
 Writing
 -------
 
 
     (update! search-results-returned 10)
 
+Reading
+-------
+
+The data of a histogram metrics can be retrived in a bunch of different ways.
+
+``percentiles``
+~~~~~~~~~~~~~~~
+
+The function you'll usually want to use to pull data from a histogram is
+``percentiles``::
+
+    (use '[metrics.histograms :only (percentiles)])
+
+    (percentiles search-results-returned)
+    => { 0.75   180
+         0.95   299
+         0.99   300
+         0.999  340
+         1.0   1345 }
+
+This returns a map of the percentiles you probably care about.  The keys are the
+percentiles (doubles between 0 and 1 inclusive) and the values are the maximum
+value for that percentile.  In this example:
+
+* 75% of searches returned 180 or fewer results.
+* 95% of searches returned 299 or fewer results.
+* ... etc.
+
+If you want a different set of percentiles just pass them as a sequence::
+
+    (use '[metrics.histograms :only (percentiles)])
+
+    (percentiles search-results-returned [0.50 0.75])
+    => { 0.50 100
+         0.75 180 }
+
+``number-recorded``
+~~~~~~~~~~~~~~~~~~~
+
+To get the number of data points recorded over the entire lifetime of this
+histogram::
+
+    (use '[metrics.histograms :only (number-recorded)])
+
+    (number-recorded search-results-returned)
+    => 12882
+
+``smallest``
+~~~~~~~~~~~~
+
+To get the smallest data point recorded over the entire lifetime of this
+histogram::
+
+    (use '[metrics.histograms :only (smallest)])
+
+    (smallest search-results-returned)
+    => 4
+
+``largest``
+~~~~~~~~~~~
+
+To get the largest data point recorded over the entire lifetime of this
+histogram::
+
+    (use '[metrics.histograms :only (largest)])
+
+    (largest search-results-returned)
+    => 1345
+
+``mean``
+~~~~~~~~
+
+To get the mean of the data points recorded over the entire lifetime of this
+histogram::
+
+    (use '[metrics.histograms :only (mean)])
+
+    (mean search-results-returned)
+    => 233.12
+
+``std-dev``
+~~~~~~~~~~~
+
+To get the standard deviation of the data points recorded over the entire
+lifetime of this histogram::
+
+    (use '[metrics.histograms :only (std-dev)])
+
+    (std-dev search-results-returned)
+    => 80.2
+
+``sample``
+~~~~~~~~~~
+
+You can get the current sample points the histogram is using with ``sample``,
+but you almost *certainly* don't care about this.  If you use it make sure you
+know what you're doing.
+
+::
+
+    (use '[metrics.histograms :only (sample)])
+
+    (sample search-results-returned)
+    => [12 2232 234 122]

docs/source/index.rst

 metrics-clojure
 ===============
 
-`metrics-clojure <http://github.com/sjl/metrics-clojure>`_ is a thin Clojure
-façade around Coda Hale's wonderful `metrics
-<http://github.com/codahale/metrics/>`_ library.
+`metrics-clojure <http://metrics-clojure.rtfd.org/>`_ is a thin Clojure façade
+around Coda Hale's wonderful `metrics <http://github.com/codahale/metrics/>`_
+library.
 
 **metrics-clojure is currently being built.  A lot of things work, but don't
 complain if things change in backwards-incompatible ways.  Once it hits 1.0.0
    names
    removing
    sideeffects
+   contributing

docs/source/meters.rst

 Meters
 ======
 
+Meters are metrics that let you "mark" when something happens and tell you how
+often it occurs.
+
 Creating
 --------
 
 The second argument to `meter` is a string describing the "units" for the meter.
 In this example it's "files", as in "18732 files".
 
-Reading
--------
-
 Writing
 -------
 
     (use '[metrics.meters :only (mark!)])
 
     (mark! files-served)
+
+Reading
+-------
+
+There are a few functions you can use to retrieve the rate at which the metered
+events occur.
+
+``rates``
+~~~~~~~~~
+
+You can get a map containing the mean rates of the event considering the last
+one, five, and fifteen minute periods with ``rates``::
+
+    (use '[metrics.meters :only (rates)])
+
+    (rates files-served)
+    => { 1 100.0,
+         5 120.0,
+        15 76.0}
+
+In this example the event happened approximately 100 times per second during the
+last one minute period, 120 times per second in the last five minute period, and
+76 times per second in the last fifteen minute period.
+
+``rate-one``
+~~~~~~~~~~~~
+
+If you only care about the rate of events during the last minute you can use
+``rate-one``::
+
+    (use '[metrics.meters :only (rate-one)])
+
+    (rate-one files-served)
+    => 100.0
+
+``rate-five``
+~~~~~~~~~~~~~
+
+If you only care about the rate of events during the last five minutes you can
+use ``rate-five``::
+
+    (use '[metrics.meters :only (rate-five)])
+
+    (rate-five files-served)
+    => 120.0
+
+``rate-fifteen``
+~~~~~~~~~~~~~~~~
+
+If you only care about the rate of events during the last fifteen minutes you
+can use ``rate-fifteen``::
+
+    (use '[metrics.meters :only (rate-fifteen)])
+
+    (rate-fifteen files-served)
+    => 76.0
+
+``rate-mean``
+~~~~~~~~~~~~~
+
+If you really want the mean rate of events over the lifetime of the meter (hint:
+you probably don't) you can use ``rate-mean``::
+
+    (use '[metrics.meters :only (rate-mean)])
+
+    (rate-mean files-served)
+    => 204.123

docs/source/timers.rst

 Timers
 ======
 
+Timers record the time it takes to do stuff.
+
 Creating
 --------
 
 
     (def image-processing-time (timer "image-processing-time"))
 
-Reading
--------
-
 Writing
 -------
 
                 (process-image-part-1 ...)
                 (process-image-part-2 ...)))
 
+Reading
+-------
+
+``percentiles``
+~~~~~~~~~~~~~~~
+
+You can use ``percentiles`` to find the percentage of actions that take less
+than or equal to a certain amount of time::
+
+    (use '[metrics.timers :only (percentiles)])
+
+    (percentiles image-processing-time)
+    => { 0.75  232.00
+         0.95  240.23
+         0.99  280.01
+         0.999 400.232
+         1.0   903.1 }
+
+This returns a map of the percentiles you probably care about.  The keys are the
+percentiles (doubles between 0 and 1 inclusive) and the values are the maximum
+time taken for that percentile.  In this example:
+
+* 75% of images were processed in 232.00 milliseconds or less.
+* 95% of images were processed in 240.23 milliseconds or less.
+* ... etc.
+
+If you want a different set of percentiles just pass them as a sequence::
+
+    (use '[metrics.timers :only (percentiles)])
+
+    (percentiles image-processing-time [0.50 0.75])
+    => { 0.50 182.11
+         0.75 232.00 }
+
+``number-recorded``
+~~~~~~~~~~~~~~~~~~~
+
+To get the number of data points recorded over the entire lifetime of this
+timers::
+
+    (use '[metrics.timers :only (number-recorded)])
+
+    (number-recorded image-processing-time)
+    => 12882
+
+``smallest``
+~~~~~~~~~~~~
+
+To get the smallest data point recorded over the entire lifetime of this
+timer::
+
+    (use '[metrics.timers :only (smallest)])
+
+    (smallest image-processing-time)
+    => 80.66
+
+``largest``
+~~~~~~~~~~~
+
+To get the largest data point recorded over the entire lifetime of this
+timer::
+
+    (use '[metrics.timers :only (largest)])
+
+    (largest image-processing-time)
+    => 903.1
+
+``mean``
+~~~~~~~~
+
+To get the mean of the data points recorded over the entire lifetime of this
+timer::
+
+    (use '[metrics.timers :only (mean)])
+
+    (mean image-processing-time)
+    => 433.12
+
+``std-dev``
+~~~~~~~~~~~
+
+To get the standard deviation of the data points recorded over the entire
+lifetime of this timer::
+
+    (use '[metrics.histograms :only (std-dev)])
+
+    (std-dev image-processing-time)
+    => 300.51
+
+``sample``
+~~~~~~~~~~
+
+You can get the current sample points the timer is using with ``sample``, but
+you almost *certainly* don't care about this.  If you use it make sure you know
+what you're doing.
+
+::
+
+    (use '[metrics.timers :only (sample)])
+
+    (sample image-processing-time)
+    => [803.234 102.223 ...]
+
+
+TODO: Rates
+~~~~~~~~~~~

src/metrics/histograms.clj

 
 
 ; Write -----------------------------------------------------------------------
-(defn update!
-  ([^HistogramMetric h] (update! h 1))
-  ([^HistogramMetric h n]
-   (.update h (long n))
-   h))
+(defn update! [^HistogramMetric h n]
+  (.update h (long n))
+  h)
 
 (defn clear! [^HistogramMetric h]
   (.clear h)
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.