src/utils_latency.c

   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  **/
  26
  27 #include "collectd.h"
  28 #include "plugin.h"
  29 #include "utils_latency.h"
  30 #include "common.h"
  31
  32 #include <math.h>
  33
  34 #ifndef HISTOGRAM_NUM_BINS
  35 # define HISTOGRAM_NUM_BINS 1000
  36 #endif
  37
  38 static const int HISTOGRAM_DEFAULT_BIN_WIDTH = 1;
  39
  40 struct latency_counter_s
  41 {
  42   cdtime_t start_time;
  43
  44   cdtime_t sum;
  45   size_t num;
  46
  47   cdtime_t min;
  48   cdtime_t max;
  49
  50   int bin_width;
  51   int histogram[HISTOGRAM_NUM_BINS];
  52 };
  53
  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;
  86
  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   }
 104
 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);
 110
 111 } /* }}} void change_bin_width */
 112
 113 latency_counter_t *latency_counter_create () /* {{{ */
 114 {
 115   latency_counter_t *lc;
 116
 117   lc = malloc (sizeof (*lc));
 118   if (lc == NULL)
 119     return (NULL);
 120   memset (lc, 0, sizeof (*lc));
 121
 122   latency_counter_reset (lc);
 123   lc->bin_width = HISTOGRAM_DEFAULT_BIN_WIDTH;
 124   return (lc);
 125 } /* }}} latency_counter_t *latency_counter_create */
 126
 127 void latency_counter_destroy (latency_counter_t *lc) /* {{{ */
 128 {
 129   sfree (lc);
 130 } /* }}} void latency_counter_destroy */
 131
 132 void latency_counter_add (latency_counter_t *lc, cdtime_t latency) /* {{{ */
 133 {
 134   size_t latency_ms;
 135
 136   if ((lc == NULL) || (latency == 0))
 137     return;
 138
 139   lc->sum += latency;
 140   lc->num++;
 141
 142   if ((lc->min == 0) && (lc->max == 0))
 143     lc->min = lc->max = latency;
 144   if (lc->min > latency)
 145     lc->min = latency;
 146   if (lc->max < latency)
 147     lc->max = latency;
 148
 149   /* A latency of _exactly_ 1.0 ms should be stored in the buffer 0, so
 150    * subtract one from the cdtime_t value so that exactly 1.0 ms get sorted
 151    * accordingly. */
 152   latency_ms = (size_t) CDTIME_T_TO_MS (latency - 1);
 153
 154   int bin = (int)(latency_ms / lc->bin_width);
 155   if (bin >= HISTOGRAM_NUM_BINS)
 156   {
 157       change_bin_width(lc, latency_ms);
 158       bin = (int)(latency_ms / lc->bin_width);
 159       if (bin >= HISTOGRAM_NUM_BINS)
 160       {
 161           ERROR("utils_latency: latency_counter_add: Invalid bin %d", bin);
 162           return;
 163       }
 164   }
 165   lc->histogram[bin]++;
 166 } /* }}} void latency_counter_add */
 167
 168 void latency_counter_reset (latency_counter_t *lc) /* {{{ */
 169 {
 170   if (lc == NULL)
 171     return;
 172
 173   int bin_width = lc->bin_width;
 174   memset (lc, 0, sizeof (*lc));
 175
 176   /* preserve bin width */
 177   lc->bin_width = bin_width;
 178   lc->start_time = cdtime ();
 179 } /* }}} void latency_counter_reset */
 180
 181 cdtime_t latency_counter_get_min (latency_counter_t *lc) /* {{{ */
 182 {
 183   if (lc == NULL)
 184     return (0);
 185   return (lc->min);
 186 } /* }}} cdtime_t latency_counter_get_min */
 187
 188 cdtime_t latency_counter_get_max (latency_counter_t *lc) /* {{{ */
 189 {
 190   if (lc == NULL)
 191     return (0);
 192   return (lc->max);
 193 } /* }}} cdtime_t latency_counter_get_max */
 194
 195 cdtime_t latency_counter_get_sum (latency_counter_t *lc) /* {{{ */
 196 {
 197   if (lc == NULL)
 198     return (0);
 199   return (lc->sum);
 200 } /* }}} cdtime_t latency_counter_get_sum */
 201
 202 size_t latency_counter_get_num (latency_counter_t *lc) /* {{{ */
 203 {
 204   if (lc == NULL)
 205     return (0);
 206   return (lc->num);
 207 } /* }}} size_t latency_counter_get_num */
 208
 209 cdtime_t latency_counter_get_average (latency_counter_t *lc) /* {{{ */
 210 {
 211   double average;
 212
 213   if ((lc == NULL) || (lc->num == 0))
 214     return (0);
 215
 216   average = CDTIME_T_TO_DOUBLE (lc->sum) / ((double) lc->num);
 217   return (DOUBLE_TO_CDTIME_T (average));
 218 } /* }}} cdtime_t latency_counter_get_average */
 219
 220 cdtime_t latency_counter_get_percentile (latency_counter_t *lc,
 221     double percent)
 222 {
 223   double percent_upper;
 224   double percent_lower;
 225   double ms_upper;
 226   double ms_lower;
 227   double ms_interpolated;
 228   int sum;
 229   size_t i;
 230
 231   if ((lc == NULL) || (lc->num == 0) || !((percent > 0.0) && (percent < 100.0)))
 232     return (0);
 233
 234   /* Find index i so that at least "percent" events are within i+1 ms. */
 235   percent_upper = 0.0;
 236   percent_lower = 0.0;
 237   sum = 0;
 238   for (i = 0; i < HISTOGRAM_NUM_BINS; i++)
 239   {
 240     percent_lower = percent_upper;
 241     sum += lc->histogram[i];
 242     if (sum == 0)
 243       percent_upper = 0.0;
 244     else
 245       percent_upper = 100.0 * ((double) sum) / ((double) lc->num);
 246
 247     if (percent_upper >= percent)
 248       break;
 249   }
 250
 251   if (i >= HISTOGRAM_NUM_BINS)
 252     return (0);
 253
 254   assert (percent_upper >= percent);
 255   assert (percent_lower < percent);
 256
 257   ms_upper = (double) ( (i + 1) * lc->bin_width );
 258   ms_lower = (double) ( i * lc->bin_width );
 259   if (i == 0)
 260     return (MS_TO_CDTIME_T (ms_upper));
 261
 262   ms_interpolated = (((percent_upper - percent) * ms_lower)
 263       + ((percent - percent_lower) * ms_upper))
 264     / (percent_upper - percent_lower);
 265
 266   return (MS_TO_CDTIME_T (ms_interpolated));
 267 } /* }}} cdtime_t latency_counter_get_percentile */
 268
 269 /* vim: set sw=2 sts=2 et fdm=marker : */