1 /**
2 * collectd - src/utils_latency.c
3 * Copyright (C) 2013 Florian Forster
4 *
5 * Permission is hereby granted, free of charge, to any person obtaining a
6 * copy of this software and associated documentation files (the "Software"),
7 * to deal in the Software without restriction, including without limitation
8 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
9 * and/or sell copies of the Software, and to permit persons to whom the
10 * Software is furnished to do so, subject to the following conditions:
11 *
12 * The above copyright notice and this permission notice shall be included in
13 * all copies or substantial portions of the Software.
14 *
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
20 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
21 * DEALINGS IN THE SOFTWARE.
22 *
23 * Authors:
24 * Florian Forster <ff at octo.it>
25 **/
27 #include "collectd.h"
28 #include "plugin.h"
29 #include "utils_latency.h"
30 #include "common.h"
32 #include <math.h>
34 #ifndef HISTOGRAM_NUM_BINS
35 # define HISTOGRAM_NUM_BINS 1000
36 #endif
38 static const int HISTOGRAM_DEFAULT_BIN_WIDTH = 1;
40 struct latency_counter_s
41 {
42 cdtime_t start_time;
44 cdtime_t sum;
45 size_t num;
47 cdtime_t min;
48 cdtime_t max;
50 int bin_width;
51 int histogram[HISTOGRAM_NUM_BINS];
52 };
54 /*
55 * Histogram represents the distribution of data, it has a list of "bins".
56 * Each bin represents an interval and has a count (frequency) of
57 * number of values fall within its interval.
58 *
59 * Histogram's range is determined by the number of bins and the bin width,
60 * There are 1000 bins and all bins have the same width of default 1 millisecond.
61 * When a value above this range is added, Histogram's range is increased by
62 * increasing the bin width (note that number of bins remains always at 1000).
63 * This operation of increasing bin width is little expensive as each bin need
64 * to be visited to update it's count. To reduce frequent change of bin width,
65 * new bin width will be the next nearest power of 2. Example: 2, 4, 8, 16, 32,
66 * 64, 128, 256, 512, 1024, 2048, 5086, ...
67 *
68 * So, if the required bin width is 300, then new bin width will be 512 as it is
69 * the next nearest power of 2.
70 *
71 */
72 void change_bin_width (latency_counter_t *lc, size_t val) /* {{{ */
73 {
74 int i=0;
75 /* This function is called because the new value is above histogram's range.
76 * First find the required bin width:
77 * requiredBinWidth = (value + 1) / numBins
78 * then get the next nearest power of 2
79 * newBinWidth = 2^(ceil(log2(requiredBinWidth)))
80 */
81 double required_bin_width = (double)(val + 1) / HISTOGRAM_NUM_BINS;
82 double required_bin_width_logbase2 = log(required_bin_width) / log(2.0);
83 int new_bin_width = (int)(pow(2.0, ceil( required_bin_width_logbase2)));
84 int old_bin_width = lc->bin_width;
85 lc->bin_width = new_bin_width;
87 /*
88 * bin width has been increased, now iterate through all bins and move the
89 * old bin's count to new bin.
90 */
91 if (lc->num > 0) // if the histogram has data then iterate else skip
92 {
93 double width_change_ratio = old_bin_width / new_bin_width;
94 for (i=0; i<HISTOGRAM_NUM_BINS; i++)
95 {
96 int new_bin = (int)(i * width_change_ratio);
97 if (i == new_bin)
98 continue;
99 lc->histogram[new_bin] += lc->histogram[i];
100 lc->histogram[i] = 0;
101 }
102 DEBUG("utils_latency: change_bin_width: fixed all bins");
103 }
105 DEBUG("utils_latency: change_bin_width: val-[%zu], oldBinWidth-[%d], "
106 "newBinWidth-[%d], required_bin_width-[%f], "
107 "required_bin_width_logbase2-[%f]",
108 val, old_bin_width, new_bin_width, required_bin_width,
109 required_bin_width_logbase2);
111 } /* }}} void change_bin_width */
113 latency_counter_t *latency_counter_create () /* {{{ */
114 {
115 latency_counter_t *lc;
117 lc = malloc (sizeof (*lc));
118 if (lc == NULL)
119 return (NULL);
121 latency_counter_reset (lc);
122 lc->bin_width = HISTOGRAM_DEFAULT_BIN_WIDTH;
123 return (lc);
124 } /* }}} latency_counter_t *latency_counter_create */
126 void latency_counter_destroy (latency_counter_t *lc) /* {{{ */
127 {
128 sfree (lc);
129 } /* }}} void latency_counter_destroy */
131 void latency_counter_add (latency_counter_t *lc, cdtime_t latency) /* {{{ */
132 {
133 size_t latency_ms;
135 if ((lc == NULL) || (latency == 0))
136 return;
138 lc->sum += latency;
139 lc->num++;
141 if ((lc->min == 0) && (lc->max == 0))
142 lc->min = lc->max = latency;
143 if (lc->min > latency)
144 lc->min = latency;
145 if (lc->max < latency)
146 lc->max = latency;
148 /* A latency of _exactly_ 1.0 ms should be stored in the buffer 0, so
149 * subtract one from the cdtime_t value so that exactly 1.0 ms get sorted
150 * accordingly. */
151 latency_ms = (size_t) CDTIME_T_TO_MS (latency - 1);
153 int bin = (int)(latency_ms / lc->bin_width);
154 if (bin >= HISTOGRAM_NUM_BINS)
155 {
156 change_bin_width(lc, latency_ms);
157 bin = (int)(latency_ms / lc->bin_width);
158 if (bin >= HISTOGRAM_NUM_BINS)
159 {
160 ERROR("utils_latency: latency_counter_add: Invalid bin %d", bin);
161 return;
162 }
163 }
164 lc->histogram[bin]++;
165 } /* }}} void latency_counter_add */
167 void latency_counter_reset (latency_counter_t *lc) /* {{{ */
168 {
169 if (lc == NULL)
170 return;
172 int bin_width = lc->bin_width;
173 memset (lc, 0, sizeof (*lc));
175 /* preserve bin width */
176 lc->bin_width = bin_width;
177 lc->start_time = cdtime ();
178 } /* }}} void latency_counter_reset */
180 cdtime_t latency_counter_get_min (latency_counter_t *lc) /* {{{ */
181 {
182 if (lc == NULL)
183 return (0);
184 return (lc->min);
185 } /* }}} cdtime_t latency_counter_get_min */
187 cdtime_t latency_counter_get_max (latency_counter_t *lc) /* {{{ */
188 {
189 if (lc == NULL)
190 return (0);
191 return (lc->max);
192 } /* }}} cdtime_t latency_counter_get_max */
194 cdtime_t latency_counter_get_sum (latency_counter_t *lc) /* {{{ */
195 {
196 if (lc == NULL)
197 return (0);
198 return (lc->sum);
199 } /* }}} cdtime_t latency_counter_get_sum */
201 size_t latency_counter_get_num (latency_counter_t *lc) /* {{{ */
202 {
203 if (lc == NULL)
204 return (0);
205 return (lc->num);
206 } /* }}} size_t latency_counter_get_num */
208 cdtime_t latency_counter_get_average (latency_counter_t *lc) /* {{{ */
209 {
210 double average;
212 if ((lc == NULL) || (lc->num == 0))
213 return (0);
215 average = CDTIME_T_TO_DOUBLE (lc->sum) / ((double) lc->num);
216 return (DOUBLE_TO_CDTIME_T (average));
217 } /* }}} cdtime_t latency_counter_get_average */
219 cdtime_t latency_counter_get_percentile (latency_counter_t *lc,
220 double percent)
221 {
222 double percent_upper;
223 double percent_lower;
224 double ms_upper;
225 double ms_lower;
226 double ms_interpolated;
227 int sum;
228 size_t i;
230 if ((lc == NULL) || (lc->num == 0) || !((percent > 0.0) && (percent < 100.0)))
231 return (0);
233 /* Find index i so that at least "percent" events are within i+1 ms. */
234 percent_upper = 0.0;
235 percent_lower = 0.0;
236 sum = 0;
237 for (i = 0; i < HISTOGRAM_NUM_BINS; i++)
238 {
239 percent_lower = percent_upper;
240 sum += lc->histogram[i];
241 if (sum == 0)
242 percent_upper = 0.0;
243 else
244 percent_upper = 100.0 * ((double) sum) / ((double) lc->num);
246 if (percent_upper >= percent)
247 break;
248 }
250 if (i >= HISTOGRAM_NUM_BINS)
251 return (0);
253 assert (percent_upper >= percent);
254 assert (percent_lower < percent);
256 ms_upper = (double) ( (i + 1) * lc->bin_width );
257 ms_lower = (double) ( i * lc->bin_width );
258 if (i == 0)
259 return (MS_TO_CDTIME_T (ms_upper));
261 ms_interpolated = (((percent_upper - percent) * ms_lower)
262 + ((percent - percent_lower) * ms_upper))
263 / (percent_upper - percent_lower);
265 return (MS_TO_CDTIME_T (ms_interpolated));
266 } /* }}} cdtime_t latency_counter_get_percentile */
268 /* vim: set sw=2 sts=2 et fdm=marker : */