metrics-clojure / 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 a biased histogram by passing an extra boolean argument:

(def search-results-returned-biased
  (histogram "search-results-returned-biased" true))

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