Diff from to

# 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]`
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.