# metrics-clojure / docs / source / metrics / histograms.rst

 Steve Losh ff65daf 2012-03-17 Steve Losh 41f4d65 2012-03-17 Steve Losh ff65daf 2012-03-17 Steve Losh 41f4d65 2012-03-17 Steve Losh ff65daf 2012-03-17 Steve Losh 41f4d65 2012-03-17 Steve Losh ff65daf 2012-03-17 Steve Losh 41f4d65 2012-03-17 Steve Losh ff65daf 2012-03-17 Steve Losh 41f4d65 2012-03-17 Steve Losh ff65daf 2012-03-17 Steve Losh 41f4d65 2012-03-17 Steve Losh ff65daf 2012-03-17 Steve Losh 41f4d65 2012-03-17 Steve Losh ff65daf 2012-03-17 Steve Losh 41f4d65 2012-03-17 Steve Losh ff65daf 2012-03-17 Steve Losh 41f4d65 2012-03-17 Steve Losh ff65daf 2012-03-17 Steve Losh 41f4d65 2012-03-17 Steve Losh ff65daf 2012-03-17   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 Histograms ========== Histograms are used to record the distribution of a piece of data over time. They're used when you have a type of data for which the following are true: * There are distinct "events" for this type of data, such as "user performs a search and we return N results". * Each event has a numeric value (the "N results" in our example). * Comparisons of these numeric values are meaningful. For example: HTTP status codes do *not* fit this because comparisons between the numeric values are not meaingful. The fact that 404 happens to be less than 500 doesn't tell you anything. Contrast this with something like "search results returned": one value being less than the other tells you something meaningful about the data. Histograms can tell you things like: 75% of all searches returned 100 or fewer results, while 95% got 200 or fewer. If the numeric value you're recording is the amount of time taken to do something, you probably want a timer instead of a histogram. Examples of metrics you might want to track with a histogram: * Search results returned ("99% of searches returned 300 or fewer results"). * Response body size ("75% of responses were 30kb or smaller"). **TODO:** More examples. 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)) .. _histograms/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  to the metric title to make it easier to define. Writing ------- Once you've got a histogram you can update it with the numeric values of events as they occur. .. _histograms/update!: update! ~~~~~~~~~~~ Update the histogram when you have a new value to record with update!:: (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. .. _histograms/percentiles: 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 } .. _histograms/number-recorded: 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 .. _histograms/smallest: 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 .. _histograms/largest: 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 .. _histograms/mean: 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 .. _histograms/std-dev: 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 .. _histograms/sample: 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.