Steve Losh avatar Steve Losh committed 8546f91

Document the def* macros.

Comments (0)

Files changed (11)

docs/source/counters.rst

 
     (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
 -------
 

docs/source/gauges.rst

       (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
 -------
 

docs/source/histograms.rst

     (def search-results-returned
       (histogram "search-results-returned"))
 
-You can create a biased histogram by passing an extra boolean argument::
+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-biased" true))
+      (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
 -------

docs/source/index.rst

    names
    removing
    sideeffects
+   title-desugaring
    ring
    contributing

docs/source/meters.rst

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

docs/source/timers.rst

 
     (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
 -------
 

docs/source/title-desugaring.rst

+.. _desugaring:
+
+Title Desugaring by the ``def[metric]`` Macros
+==============================================
+
+All of the ``def[metric]`` macros (:ref:`defcounter <defcounter>`,
+:ref:`defgauge <defgauge>`, :ref:`defhistogram <defhistogram>`, :ref:`defmeter
+<defmeter>`, and :ref:`deftimer <deftimer>`) take a title as their first
+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.
+
+For example, this::
+
+    (defmeter post-requests)
+
+is equivalent to::
+
+    (def post-requests (meter "post-requests"))
+
+If you want to define a metric with a name outside of the default group/type,
+you can use a vector of three strings and/or symbols instead of a bare symbol.
+The last entry in the vector will be used as the symbol for the var (and will be
+coerced if necessary). For example, all of these::
+
+    (defcounter ["mysite.http" api post-requests])
+    (defcounter ["mysite.http" "api" post-requests])
+    (defcounter ["mysite.http" "api" "post-requests"])
+
+are equivalent to::
+
+    (def post-requests (meter ["mysite.http" "api" "post-requests"]))
+
+If you need more control than this (e.g.: if you want a var named differently
+than the last segment of the metric name) you should use the normal creation
+methods.  These macros are only a bit of syntactic sugar to reduce typing.

metrics-clojure-core/src/metrics/histograms.clj

 
 (defmacro defhistogram
   "Define a Histogram metric with the given title.
-  
+
   The title uses some basic desugaring to let you concisely define metrics:
 
     ; Define a histogram titled \"default.default.foo\" into var foo

metrics-clojure-ring/src/metrics/ring/expose.clj

   (:use [cheshire.core :only [generate-string]]))
 
 
+; Define rendering protocol ---------------------------------------------------
 (defprotocol RenderableMetric
   (render-to-basic [metric] "Turn a metric into a basic Clojure datastructure."))
 
     {:type :counter
      :value (counters/value c)}))
 
+
+; Utils -----------------------------------------------------------------------
 (defn- ensure-leading-slash [s]
   (if (not= \/ (first s))
     (str \/ s)
 (defn- render-metric [[metric-name metric]]
   [metric-name (render-to-basic metric)])
 
+
+; Exposing --------------------------------------------------------------------
 (defn- metrics-json [request]
   (let [metrics-map (into {} (map render-metric (all-metrics)))
         json (generate-string metrics-map)]

metrics-clojure-ring/src/metrics/ring/instrument.clj

         [metrics.meters :only (meter mark!)]
         [metrics.timers :only (timer time!)]))
 
+
 (defn- mark-in! [metric-map k]
   (when-let [metric (metric-map k)]
     (mark! metric)))
 (defn instrument
   "Instrument a ring handler.
 
-  This middleware should be added as late as possible for maximum effect."
+  This middleware should be added as late as possible (nearest to the outside of
+  the \"chain\") for maximum effect.
+  "
   ([handler]
    (let [active-requests (counter ["ring" "requests" "active"])
          requests (meter ["ring" "requests" "rate"] "requests")

metrics-clojure-ring/src/metrics/ring/rendering.clj

-(ns metrics.rendering)
-
-
-(defprotocol RenderableMetric
-  (render-to-basic [metric] "Turn a metric into a basic Clojure datastructure."))
-
-(defn render-metric)
-
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.