Commits

Steve Losh committed ff65daf

Refactor the docs a bit.

Comments (0)

Files changed (17)

docs/source/counters.rst

-Counters
-========
-
-Counters are values you can increment and decrement.
-
-Creating
---------
-
-Create your counter::
-
-    (use '[metrics.counters :only (counter)])
-
-    (def users-connected (counter "users-connected"))
-
-.. _defcounter:
-
-You can also use the ``defcounter`` macro to create a counter and bind it to a var
-in one concise, easy step::
-
-    (use '[metrics.counters :only (defcounter)])
-
-    (defcounter users-connected)
-
-All the ``def[metric]`` macros do some :ref:`magic <desugaring>` to the metric
-title to make it easier to define.
-
-Writing
--------
-
-Now increment and decrement it::
-
-    (use '[metrics.counters :only (inc! dec!)])
-
-    (inc! users-connected)
-    (inc! users-connected 2)
-
-    (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

-Gauges
-======
-
-Gauges are used to measure the instantaneous value of something.
-
-Creating
---------
-
-Create your gauge::
-
-    (use '[metrics.gauges :only (gauge)])
-
-    (def files-open
-      (gauge "files-open"
-             (return-number-of-files-open ...)))
-
-That's it.  Pretty simple.
-
-``gauge`` is a macro.  If you need a function instead you can use ``gauge-fn``,
-but you have to pass it a function, not just a body::
-
-    (use '[metrics.gauges :only (gauge-fn)])
-
-    (def files-open
-      (gauge-fn "files-open"
-             #(return-number-of-files-open ...)))
-
-.. _defgauge:
-
-You can also use the ``defgauge`` macro to create a gauge and bind it to a var
-in one concise, easy step::
-
-    (use '[metrics.gauges :only (defgauge)])
-
-    (defgauge files-open
-      (return-number-of-files-open ...))
-
-``defgauge`` can take a body of statements like ``gauge`` or a function like
-``gauge-fn``.
-
-All the ``def[metric]`` macros do some :ref:`magic <desugaring>` to the metric
-title to make it easier to define.
-
-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)])
-
-    (value files-open)

docs/source/histograms.rst

-Histograms
-==========
-
-Histograms are used to record the distribution of a piece of data over time.
-
-Creating
---------
-
-Create your histogram::
-
-    (use '[metrics.histograms :only (histogram)])
-
-    (def search-results-returned
-      (histogram "search-results-returned"))
-
-You can create an unbiased histogram by passing an extra boolean argument
-(though you probably don't want to)::
-
-    (def search-results-returned-biased
-      (histogram "search-results-returned-unbiased" false))
-
-.. _defhistogram:
-
-You can also use the ``defhistogram`` macro to create a histogram and bind it to
-a var in one concise, easy step::
-
-    (use '[metrics.histograms :only (defhistogram)])
-
-    (defhistogram search-results-returned)
-
-All the ``def[metric]`` macros do some :ref:`magic <desugaring>` to the metric
-title to make it easier to define.
-
-Writing
--------
-
-Update the histogram when you have a new value to record::
-
-    (use '[metrics.histograms :only (update!)])
-
-    (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

 complain if things change in backwards-incompatible ways.  Once it hits 1.0.0
 it'll be stable, but until then use it at your own risk.**
 
-``metrics-clojure`` is a thin wrapper around metrics, so if you don't know what
-any of the words in this documentaion mean you should probably read the `metrics
+metrics-clojure is a thin wrapper around metrics, so if you don't know what any
+of the words in this documentaion mean you should probably read the `metrics
 documentation <https://github.com/codahale/metrics/tree/development/docs>`_
 and/or watch the `talk
 <http://pivotallabs.com/talks/139-metrics-metrics-everywhere>`_.
 -----------------
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    installation
-   counters
-   gauges
-   meters
-   histograms
-   timers
+   metrics/counters
+   metrics/gauges
+   metrics/meters
+   metrics/histograms
+   metrics/timers
    reporting
    names
    removing

docs/source/meters.rst

-Meters
-======
-
-Meters are metrics that let you "mark" when something happens and tell you how
-often it occurs.
-
-Creating
---------
-
-Create your meter::
-
-    (use '[metrics.meters :only (meter)])
-
-    (def files-served (meter "files-served" "files"))
-
-The second argument to ``meter`` is a string describing the "units" for the
-meter.  In this example it's "files", as in "18732 files".
-
-.. _defmeter:
-
-You can also use the ``defmeter`` macro to create a meter and bind it to a var
-in one concise, easy step::
-
-    (use '[metrics.meters :only (defmeter)])
-
-    (defmeter files-served "files")
-
-All the ``def[metric]`` macros do some :ref:`magic <desugaring>` to the metric
-title to make it easier to define.
-
-Writing
--------
-
-Mark the meter every time the event happens::
-
-    (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/metrics/counters.rst

+Counters
+========
+
+Counters are values you can increment and decrement.
+
+Creating
+--------
+
+Create your counter::
+
+    (use '[metrics.counters :only (counter)])
+
+    (def users-connected (counter "users-connected"))
+
+.. _defcounter:
+
+You can also use the ``defcounter`` macro to create a counter and bind it to a var
+in one concise, easy step::
+
+    (use '[metrics.counters :only (defcounter)])
+
+    (defcounter users-connected)
+
+All the ``def[metric]`` macros do some :ref:`magic <desugaring>` to the metric
+title to make it easier to define.
+
+Writing
+-------
+
+Now increment and decrement it::
+
+    (use '[metrics.counters :only (inc! dec!)])
+
+    (inc! users-connected)
+    (inc! users-connected 2)
+
+    (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/metrics/gauges.rst

+Gauges
+======
+
+Gauges are used to measure the instantaneous value of something.
+
+Creating
+--------
+
+Create your gauge::
+
+    (use '[metrics.gauges :only (gauge)])
+
+    (def files-open
+      (gauge "files-open"
+             (return-number-of-files-open ...)))
+
+That's it.  Pretty simple.
+
+``gauge`` is a macro.  If you need a function instead you can use ``gauge-fn``,
+but you have to pass it a function, not just a body::
+
+    (use '[metrics.gauges :only (gauge-fn)])
+
+    (def files-open
+      (gauge-fn "files-open"
+             #(return-number-of-files-open ...)))
+
+.. _defgauge:
+
+You can also use the ``defgauge`` macro to create a gauge and bind it to a var
+in one concise, easy step::
+
+    (use '[metrics.gauges :only (defgauge)])
+
+    (defgauge files-open
+      (return-number-of-files-open ...))
+
+``defgauge`` can take a body of statements like ``gauge`` or a function like
+``gauge-fn``.
+
+All the ``def[metric]`` macros do some :ref:`magic <desugaring>` to the metric
+title to make it easier to define.
+
+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)])
+
+    (value files-open)

docs/source/metrics/histograms.rst

+Histograms
+==========
+
+Histograms are used to record the distribution of a piece of data over time.
+
+Creating
+--------
+
+Create your histogram::
+
+    (use '[metrics.histograms :only (histogram)])
+
+    (def search-results-returned
+      (histogram "search-results-returned"))
+
+You can create an unbiased histogram by passing an extra boolean argument
+(though you probably don't want to)::
+
+    (def search-results-returned-biased
+      (histogram "search-results-returned-unbiased" false))
+
+.. _defhistogram:
+
+You can also use the ``defhistogram`` macro to create a histogram and bind it to
+a var in one concise, easy step::
+
+    (use '[metrics.histograms :only (defhistogram)])
+
+    (defhistogram search-results-returned)
+
+All the ``def[metric]`` macros do some :ref:`magic <desugaring>` to the metric
+title to make it easier to define.
+
+Writing
+-------
+
+Update the histogram when you have a new value to record::
+
+    (use '[metrics.histograms :only (update!)])
+
+    (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/metrics/meters.rst

+Meters
+======
+
+Meters are metrics that let you "mark" when something happens and tell you how
+often it occurs.
+
+Creating
+--------
+
+Create your meter::
+
+    (use '[metrics.meters :only (meter)])
+
+    (def files-served (meter "files-served" "files"))
+
+The second argument to ``meter`` is a string describing the "units" for the
+meter.  In this example it's "files", as in "18732 files".
+
+.. _defmeter:
+
+You can also use the ``defmeter`` macro to create a meter and bind it to a var
+in one concise, easy step::
+
+    (use '[metrics.meters :only (defmeter)])
+
+    (defmeter files-served "files")
+
+All the ``def[metric]`` macros do some :ref:`magic <desugaring>` to the metric
+title to make it easier to define.
+
+Writing
+-------
+
+Mark the meter every time the event happens::
+
+    (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/metrics/timers.rst

+Timers
+======
+
+Timers record the time it takes to do stuff.
+
+Creating
+--------
+
+Create your timer::
+
+    (use '[metrics.timers :only (timer)])
+
+    (def image-processing-time (timer "image-processing-time"))
+
+.. _deftimer:
+
+You can also use the ``deftimer`` macro to create a timer and bind it to a var
+in one concise, easy step::
+
+    (use '[metrics.timers :only (deftimer)])
+
+    (deftimer image-processing-time)
+
+All the ``def[metric]`` macros do some :ref:`magic <desugaring>` to the metric
+title to make it easier to define.
+
+Writing
+-------
+
+Now time something::
+
+    (use '[metrics.timers :only (time!)])
+
+    (time! image-processing-time
+           (process-image-part-1 ...)
+           (process-image-part-2 ...))
+
+``time!`` is a macro.  If you need a function instead, you can use ``time-fn!``,
+but you'll need to pass it a function instead of just a body::
+
+    (use '[metrics.timers :only (time-fn!)])
+
+    (time-fn! image-processing-time
+              (fn []
+                (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
+~~~~~~~~~~~

docs/source/names.rst

+.. _metric-names:
+
 Metric Names
 ============
 
-In all these examples we've used a string to name the metric.  The ``metrics``
-library actually names metrics with three-part names.  In Java and Scala those
-names are usually the package and class where the timer is being used.
+In all the examples we've used a string to name the metric.  The ``metrics``
+library actually names metrics with three-part names, sometimes called "group",
+"type", and "metric name".
+
+In Java and Scala those names are usually set to the package and class where the
+metric is being used.
 
 In Clojure you usually won't have a meaningful class name to record, and the
-package name would be a pain to find, so ``metrics-clojure`` uses "default" and
+package name would be a pain to find, so metrics-clojure uses "default" and
 "default" for those parts.  This results in a name like
 "default.default.my-metric".
 

docs/source/removing.rst

 
     (remove-metric "files-served")
 
-You can use the sequence form of metric names here too, of course::
+You can use the sequence form of :ref:`metric names <metric-names>` here too, of
+course::
 
     (remove-metric ["webservice" "views" "response-time"])
 

docs/source/reporting.rst

 Reporting
 =========
 
-Currently ``metrics-clojure`` supports reporting metrics through the
-console (on standard error)::
+Once you've started tracking some metrics there are several ways you can read
+their values.
+
+More reporting methods will be added in the future.  Pull requests are welcome.
+
+Console
+-------
+
+metrics-clojure supports reporting metrics through the console (on standard
+error)::
 
     (use '[metrics.core :only (report-to-console)])
 
 This will tell ``metrics`` to print all metrics to the console every ten
 seconds.
 
-``metrics-clojure`` also supports [JMX reporting][jmx], since it's built into
+JMX and ``jvisualvm``
+---------------------
+
+metrics-clojure also supports `JMX reporting
+<http://metrics.codahale.com/manual.html#jmx-reporter>`_, since it's built into
 ``metrics`` itself.
 
-More reporting methods will be added in the future.  Pull requests are welcome.
-
-[jmx]: http://metrics.codahale.com/manual.html#jmx-reporter
+In a nutshell: you can open ``jvisualvm`` (which you probably already have as
+it's included in many Java distributions), connect to a process, and view
+metrics in the MBeans tab.

docs/source/ring.rst

 Extras for Ring
 ===============
 
-``metrics-clojure`` contains some extra glue code you can use with your `Ring
+metrics-clojure contains some extra glue code you can use with your `Ring
 <https://github.com/mmcgrana/ring>`_ apps.
 
 Installation
 
     [metrics-clojure-ring "0.7.1"]
 
-**Note:** the versions of ``metrics-clojure`` and ``metrics-clojure-ring``
-should always be the same.
+**Note:** the versions of metrics-clojure and metrics-clojure-ring should always
+be the same.
 
 
 Exposing Metrics as JSON

docs/source/sideeffects.rst

 Side Effects and Agents
 =======================
 
-Pretty much everything ``metrics-clojure`` does causes side effects.  If you're
+Pretty much everything metrics-clojure does causes side effects.  If you're
 recording metrics inside of a ``dosync`` they may be recorded multiple times if
 the transaction is restarted.
 
 If you're recording how many responses get sent to a user, then you probably
 don't want to overcount them.
 
-``metrics-clojure`` doesn't try to decide for you.  It leaves it up to you to
-handle the issue.
+metrics-clojure doesn't try to decide for you.  It leaves it up to you to handle
+the issue.
 
 If you don't want to record something multiple times, an agent may be a good way
 to handle things::

docs/source/timers.rst

-Timers
-======
-
-Timers record the time it takes to do stuff.
-
-Creating
---------
-
-Create your timer::
-
-    (use '[metrics.timers :only (timer)])
-
-    (def image-processing-time (timer "image-processing-time"))
-
-.. _deftimer:
-
-You can also use the ``deftimer`` macro to create a timer and bind it to a var
-in one concise, easy step::
-
-    (use '[metrics.timers :only (deftimer)])
-
-    (deftimer image-processing-time)
-
-All the ``def[metric]`` macros do some :ref:`magic <desugaring>` to the metric
-title to make it easier to define.
-
-Writing
--------
-
-Now time something::
-
-    (use '[metrics.timers :only (time!)])
-
-    (time! image-processing-time
-           (process-image-part-1 ...)
-           (process-image-part-2 ...))
-
-``time!`` is a macro.  If you need a function instead, you can use ``time-fn!``,
-but you'll need to pass it a function instead of just a body::
-
-    (use '[metrics.timers :only (time-fn!)])
-
-    (time-fn! image-processing-time
-              (fn []
-                (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
-~~~~~~~~~~~

docs/source/title-desugaring.rst

 argument.
 
 All of the macros will use this title as a symbol when binding it to a var, and
-will convert it to a string to use as the name of the metric.
+will convert it to a string to use as the :ref:`name <metric-names>` of the
+metric.
 
 For example, this::
 
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.