Steve Losh avatar Steve Losh committed 0a3a634

Update to prepare for metrics-clojure-ring.

Comments (0)

Files changed (16)

docs/source/conf.py

 # built documents.
 #
 # The short X.Y version.
-version = '0.6.0'
+version = '0.7.0'
 # The full version, including alpha/beta/rc tags.
-release = '0.6.0'
+release = '0.7.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/source/gauges.rst

 
 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::
+``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)])
 
 -------
 
 There's only one way to get data from a gauge.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-
 
 ``value``
 ~~~~~~~~~

docs/source/index.rst

    names
    removing
    sideeffects
+   ring
    contributing

docs/source/installation.rst

 
 Add this to your ``project.clj``'s dependencies::
 
-    [metrics-clojure "0.6.0"]
+    [metrics-clojure "0.7.0"]
 
 That's it.

docs/source/meters.rst

 
     (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".
+The second argument to ``meter`` is a string describing the "units" for the
+meter.  In this example it's "files", as in "18732 files".
 
 Writing
 -------

docs/source/ring.rst

+Extras for Ring
+===============
+
+``metrics-clojure`` contains some extra glue code you can use with your `Ring
+<https://github.com/mmcgrana/ring>`_ apps.
+
+Installation
+------------
+
+The extra Ring-related functionality is in a separate ``metrics-clojure-ring``
+library so you don't have to install it unless you want it.
+
+To install it, add this to your ``project.clj``'s dependencies::
+
+    [metrics-clojure-ring "0.7.0"]
+
+**Note:** the versions of ``metrics-clojure`` and ``metrics-clojure-ring``
+should always be the same.
+
+
+Exposing Metrics as JSON
+------------------------
+
+You can expose your app's metrics as JSON by using the
+``expose-metrics-as-json`` middleware::
+
+    (use '[metrics.ring.expose :only (expose-metrics-as-json)])
+
+    (def app (expose-metrics-as-json app))
+
+This will add a ``/metrics/`` URL that will show all the metrics for the app.
+The trailing slash is required.
+
+If you want to use a different endpoint you can pass it as a parameter::
+
+    (use '[metrics.ring.expose :only (expose-metrics-as-json)])
+
+    (def app (expose-metrics-as-json app "/admin/stats/"))
+
+**WARNING**: this URL will not be protected by a username or password in any way
+(yet), so if you have sensitive metrics you might want to think twice about
+using it (or protect it yourself).
+
+JSON Format
+~~~~~~~~~~~
+
+Here's an example of the JSON format::
+
+    {
+        "default.default.sample-metric": {
+            "type": "counter",
+            "value": 10
+        }
+    }
+
+The JSON is an object that maps metric names to their data.
+
+Each metric object will have a ``type`` attribute.  The rest of the attributes
+will depend on the type of metric.
+
+**TODO**: Document each individual type.

docs/source/sideeffects.rst

 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
+``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

docs/source/timers.rst

            (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::
+``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!)])
 
-(defproject metrics-clojure "0.6.0"
+(defproject metrics-clojure "0.7.0"
   :description "A Clojure façade for Coda Hale's metrics library."
   :dependencies [[org.clojure/clojure "[1.2.1,1.3.0]"]
                  [com.yammer.metrics/metrics-core "2.0.1"]]

src/metrics/core.clj

   (:import (java.util.concurrent TimeUnit)))
 
 
-(defn remove-metric [title]
+(defn remove-metric
+  "Remove the metric with the given title."
+  [title]
   (.removeMetric (Metrics/defaultRegistry) (metric-name title)))
 
 
-(defn report-to-console [seconds]
+(defn report-to-console
+  "Report all metrics to standard out every few seconds."
+  [seconds]
   (ConsoleReporter/enable seconds TimeUnit/SECONDS))
+
+

src/metrics/counters.clj

 
 
 ; Create ----------------------------------------------------------------------
-(defn counter [title]
+(defn counter
+  "Create and return a new Counter metric with the given title.
+
+  Title can be a plain string like \"foo\" or a vector of three strings like:
+
+      [\"myapp\" \"webserver\" \"connections\"]
+
+  "
+  [title]
   (Metrics/newCounter (metric-name title)))
 
 
 ; Read ------------------------------------------------------------------------
-(defn value [^Counter c]
+(defn value
+  "Return the current value of the counter."
+  [^Counter c]
   (.count c))
 
 
 ; Write -----------------------------------------------------------------------
 (defn inc!
+  "Increment the counter by the given amount (or 1 if not specified)."
   ([^Counter c] (inc! c 1))
   ([^Counter c n]
    (.inc c n)
    c))
 
 (defn dec!
+  "Decrement the counter by the given amount (or 1 if not specified)."
   ([^Counter c] (dec! c 1))
   ([^Counter c n]
    (.dec c n)
    c))
 
-(defn clear! [^Counter c]
+(defn clear!
+  "Clear the given counter, resetting its value to zero."
+  [^Counter c]
   (.clear c)
   c)
 

src/metrics/gauges.clj

 
 
 ; Create ----------------------------------------------------------------------
-(defmacro gauge [title & body]
+(defmacro gauge
+  "Create a new Gauge metric with the given title.
+
+  The body exprs will be used to retrieve the value of the Gauge when requested."
+  [title & body]
   `(Metrics/newGauge (metric-name ~title)
                      (proxy [Gauge] []
                        (value [] (do ~@body)))))
 
 
 ; Read ------------------------------------------------------------------------
-(defn gauge-fn [title f]
+(defn gauge-fn
+  "Create a new Gauge metric with the given title.
+
+  The given function will be called (with no arguments) to retrieve the value of
+  the Gauge when requested."
+  [title f]
   (Metrics/newGauge (metric-name title)
                     (proxy [Gauge] []
                       (value [] (f)))))
 
 
 ; Read ------------------------------------------------------------------------
-(defn value [^Gauge g]
+(defn value
+  "Return the value of the given Gauge."
+  [^Gauge g]
   (.value g))
+

src/metrics/histograms.clj

 (ns metrics.histograms
-  (use [metrics.utils :only (metric-name get-percentiles)])
-  (import (com.yammer.metrics Metrics))
-  (import (com.yammer.metrics.core Histogram MetricName)))
+  (:use [metrics.utils :only (metric-name get-percentiles)])
+  (:import (com.yammer.metrics Metrics))
+  (:import (com.yammer.metrics.core Histogram MetricName)))
 
 
 ; Create ----------------------------------------------------------------------
 (defn histogram
+  "Create and return a Histogram metric with the given title.
+
+  By default a biased Histogram is created.  This is probably what you want, but
+  if you know what you're doing you can pass false to create a uniform one
+  instead."
   ([title] (histogram title true))
   ([title biased]
    (Metrics/newHistogram
 
 
 ; Read ------------------------------------------------------------------------
-(defn mean [^Histogram h]
+(defn mean
+  "Return the mean value of the given Histogram."
+  [^Histogram h]
   (.mean h))
 
-(defn std-dev [^Histogram h]
+(defn std-dev
+  "Return the standard deviation of the given Histogram."
+  [^Histogram h]
   (.stdDev h))
 
 (defn percentiles
+  "Return a mapping of percentiles to their values for the given Histogram.
+
+  For example:
+
+    (percentiles myhistogram [0.5 0.9 1.0])
+    ;=> {0.5 200, 0.9 240, 1.0 500}
+
+  This means that:
+
+  * 50% of the values recorded by this Histogram were less than or equal to 200
+  * 90% were less than or equal to 240
+  * 100% were less than or equal to 500
+
+  If you don't pass a list of desired percentiles, the default will be
+  [0.75 0.95 0.99 0.999 1.0]."
   ([^Histogram h]
    (percentiles h [0.75 0.95 0.99 0.999 1.0]))
   ([^Histogram h ps]
    (get-percentiles h ps)))
 
 
-(defn number-recorded [^Histogram h]
+(defn number-recorded
+  "Return the number of values recorded by the given Histogram."
+  [^Histogram h]
   (.count h))
 
-(defn largest [^Histogram h]
+(defn largest
+  "Return the largest value recorded by the given Histogram."
+  [^Histogram h]
   (.max h))
 
-(defn smallest [^Histogram h]
+(defn smallest
+  "Return the smallest value recorded by the given Histogram."
+  [^Histogram h]
   (.min h))
 
-(defn sample [^Histogram h]
+(defn sample
+  "Return the values in the given Histogram's current sampling.
+
+  This is almost certainly NOT what you want.  Read up on how these histograms
+  work and make sure you understand it before using this function."
+  [^Histogram h]
   (.getValues (.getSnapshot h)))
 
 
 ; Write -----------------------------------------------------------------------
-(defn update! [^Histogram h n]
+(defn update!
+  "Record a value in the given Histogram."
+  [^Histogram h n]
   (.update h (long n))
   h)
 
-(defn clear! [^Histogram h]
+(defn clear!
+  "Clear all data from the given Histogram."
+  [^Histogram h]
   (.clear h)
   h)
 

src/metrics/meters.clj

 (ns metrics.meters
-  (use [metrics.utils :only (metric-name)])
-  (import (com.yammer.metrics Metrics))
-  (import (com.yammer.metrics.core Meter))
-  (import (java.util.concurrent TimeUnit)))
+  (:use [metrics.utils :only (metric-name)])
+  (:import (com.yammer.metrics Metrics))
+  (:import (com.yammer.metrics.core Meter))
+  (:import (java.util.concurrent TimeUnit)))
 
 
 ; Create ----------------------------------------------------------------------
   ([^Meter m n]
    (.mark m (long n))
    m))
+

src/metrics/timers.clj

 (ns metrics.timers
-  (use [metrics.utils :only (metric-name get-percentiles)])
-  (import (com.yammer.metrics Metrics))
-  (import (com.yammer.metrics.core Timer MetricName))
-  (import (java.util.concurrent TimeUnit)))
+  (:use [metrics.utils :only (metric-name get-percentiles)])
+  (:import (com.yammer.metrics Metrics))
+  (:import (com.yammer.metrics.core Timer MetricName))
+  (:import (java.util.concurrent TimeUnit)))
 
 
 ; Create ----------------------------------------------------------------------
 
 (defn clear! [^Timer t]
   (.clear t))
+

src/metrics/utils.clj

 (ns metrics.utils
-  (import (com.yammer.metrics.core Sampling MetricName)))
+  (:import (com.yammer.metrics Metrics))
+  (:import (com.yammer.metrics.core Sampling MetricName)))
 
 
 (defn get-percentile [^Sampling metric ^double percentile]
          ^String (first title)
          ^String (second title)
          ^String (last title))))
+
+(defn all-metrics []
+  (letfn [(parse-name [metric-name]
+            (str (.getGroup metric-name)
+                 "." (.getType metric-name)
+                 "." (.getName metric-name)))
+          (parse-entry [[metric-name metric]]
+            [(parse-name metric-name)
+             metric])]
+    (into {} (map parse-entry (.allMetrics (Metrics/defaultRegistry))))))
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.