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 #include <limits.h>
  34
  35 #ifndef HISTOGRAM_NUM_BINS
  36 # define HISTOGRAM_NUM_BINS 1000
  37 #endif
  38
  39 #ifndef HISTOGRAM_DEFAULT_BIN_WIDTH
  40 /* 1048576 = 2^20 ^= 1/1024 s */
  41 # define HISTOGRAM_DEFAULT_BIN_WIDTH 1048576
  42 #endif
  43
  44 struct latency_counter_s
  45 {
  46   cdtime_t start_time;
  47
  48   cdtime_t sum;
  49   size_t num;
  50
  51   cdtime_t min;
  52   cdtime_t max;
  53
  54   cdtime_t bin_width;
  55   int histogram[HISTOGRAM_NUM_BINS];
  56 };
  57
  58 /*
  59 * Histogram represents the distribution of data, it has a list of "bins".
  60 * Each bin represents an interval and has a count (frequency) of
  61 * number of values fall within its interval.
  62 *
  63 * Histogram's range is determined by the number of bins and the bin width,
  64 * There are 1000 bins and all bins have the same width of default 1 millisecond.
  65 * When a value above this range is added, Histogram's range is increased by
  66 * increasing the bin width (note that number of bins remains always at 1000).
  67 * This operation of increasing bin width is little expensive as each bin need
  68 * to be visited to update it's count. To reduce frequent change of bin width,
  69 * new bin width will be the next nearest power of 2. Example: 2, 4, 8, 16, 32,
  70 * 64, 128, 256, 512, 1024, 2048, 5086, ...
  71 *
  72 * So, if the required bin width is 300, then new bin width will be 512 as it is
  73 * the next nearest power of 2.
  74 */
  75 void change_bin_width (latency_counter_t *lc, cdtime_t latency) /* {{{ */
  76 {
  77   /* This function is called because the new value is above histogram's range.
  78    * First find the required bin width:
  79    *           requiredBinWidth = (value + 1) / numBins
  80    * then get the next nearest power of 2
  81    *           newBinWidth = 2^(ceil(log2(requiredBinWidth)))
  82    */
  83   double required_bin_width = ((double) (latency + 1)) / ((double) HISTOGRAM_NUM_BINS);
  84   double required_bin_width_logbase2 = log (required_bin_width) / log (2.0);
  85   cdtime_t new_bin_width = (cdtime_t) (pow (2.0, ceil (required_bin_width_logbase2)) + .5);
  86   cdtime_t old_bin_width = lc->bin_width;
  87
  88   lc->bin_width = new_bin_width;
  89
  90   /* bin_width has been increased, now iterate through all bins and move the
  91    * old bin's count to new bin. */
  92   if (lc->num > 0) // if the histogram has data then iterate else skip
  93   {
  94       double width_change_ratio = ((double) old_bin_width) / ((double) new_bin_width);
  95       size_t i;
  96
  97       for (i = 0; i < HISTOGRAM_NUM_BINS; i++)
  98       {
  99          size_t new_bin = (size_t) (((double) i) * width_change_ratio);
 100          if (i == new_bin)
 101              continue;
 102          assert (new_bin < i);
 103
 104          lc->histogram[new_bin] += lc->histogram[i];
 105          lc->histogram[i] = 0;
 106       }
 107   }
 108
 109   DEBUG("utils_latency: change_bin_width: latency = %.3f; "
 110       "old_bin_width = %.3f; new_bin_width = %.3f;",
 111       CDTIME_T_TO_DOUBLE (latency),
 112       CDTIME_T_TO_DOUBLE (old_bin_width),
 113       CDTIME_T_TO_DOUBLE (new_bin_width));
 114 } /* }}} void change_bin_width */
 115
 116 latency_counter_t *latency_counter_create () /* {{{ */
 117 {
 118   latency_counter_t *lc;
 119
 120   lc = malloc (sizeof (*lc));
 121   if (lc == NULL)
 122     return (NULL);
 123   memset (lc, 0, sizeof (*lc));
 124
 125   latency_counter_reset (lc);
 126   lc->bin_width = HISTOGRAM_DEFAULT_BIN_WIDTH;
 127   return (lc);
 128 } /* }}} latency_counter_t *latency_counter_create */
 129
 130 void latency_counter_destroy (latency_counter_t *lc) /* {{{ */
 131 {
 132   sfree (lc);
 133 } /* }}} void latency_counter_destroy */
 134
 135 void latency_counter_add (latency_counter_t *lc, cdtime_t latency) /* {{{ */
 136 {
 137   cdtime_t bin;
 138
 139   if ((lc == NULL) || (latency == 0) || (latency > ((cdtime_t) LLONG_MAX)))
 140     return;
 141
 142   lc->sum += latency;
 143   lc->num++;
 144
 145   if ((lc->min == 0) && (lc->max == 0))
 146     lc->min = lc->max = latency;
 147   if (lc->min > latency)
 148     lc->min = latency;
 149   if (lc->max < latency)
 150     lc->max = latency;
 151
 152   /* A latency of _exactly_ 1.0 ms should be stored in the buffer 0, so
 153    * subtract one from the cdtime_t value so that exactly 1.0 ms get sorted
 154    * accordingly. */
 155   bin = (latency - 1) / lc->bin_width;
 156   if (bin >= HISTOGRAM_NUM_BINS)
 157   {
 158       change_bin_width (lc, latency);
 159       bin = (latency - 1) / lc->bin_width;
 160       if (bin >= HISTOGRAM_NUM_BINS)
 161       {
 162           ERROR ("utils_latency: latency_counter_add: Invalid bin %lu", bin);
 163           return;
 164       }
 165   }
 166   lc->histogram[bin]++;
 167 } /* }}} void latency_counter_add */
 168
 169 void latency_counter_reset (latency_counter_t *lc) /* {{{ */
 170 {
 171   if (lc == NULL)
 172     return;
 173
 174   cdtime_t bin_width = lc->bin_width;
 175   memset (lc, 0, sizeof (*lc));
 176
 177   /* preserve bin width */
 178   lc->bin_width = bin_width;
 179   lc->start_time = cdtime ();
 180 } /* }}} void latency_counter_reset */
 181
 182 cdtime_t latency_counter_get_min (latency_counter_t *lc) /* {{{ */
 183 {
 184   if (lc == NULL)
 185     return (0);
 186   return (lc->min);
 187 } /* }}} cdtime_t latency_counter_get_min */
 188
 189 cdtime_t latency_counter_get_max (latency_counter_t *lc) /* {{{ */
 190 {
 191   if (lc == NULL)
 192     return (0);
 193   return (lc->max);
 194 } /* }}} cdtime_t latency_counter_get_max */
 195
 196 cdtime_t latency_counter_get_sum (latency_counter_t *lc) /* {{{ */
 197 {
 198   if (lc == NULL)
 199     return (0);
 200   return (lc->sum);
 201 } /* }}} cdtime_t latency_counter_get_sum */
 202
 203 size_t latency_counter_get_num (latency_counter_t *lc) /* {{{ */
 204 {
 205   if (lc == NULL)
 206     return (0);
 207   return (lc->num);
 208 } /* }}} size_t latency_counter_get_num */
 209
 210 cdtime_t latency_counter_get_average (latency_counter_t *lc) /* {{{ */
 211 {
 212   double average;
 213
 214   if ((lc == NULL) || (lc->num == 0))
 215     return (0);
 216
 217   average = CDTIME_T_TO_DOUBLE (lc->sum) / ((double) lc->num);
 218   return (DOUBLE_TO_CDTIME_T (average));
 219 } /* }}} cdtime_t latency_counter_get_average */
 220
 221 cdtime_t latency_counter_get_percentile (latency_counter_t *lc, /* {{{ */
 222     double percent)
 223 {
 224   double percent_upper;
 225   double percent_lower;
 226   double p;
 227   cdtime_t latency_lower;
 228   cdtime_t latency_interpolated;
 229   int sum;
 230   size_t i;
 231
 232   if ((lc == NULL) || (lc->num == 0) || !((percent > 0.0) && (percent < 100.0)))
 233     return (0);
 234
 235   /* Find index i so that at least "percent" events are within i+1 ms. */
 236   percent_upper = 0.0;
 237   percent_lower = 0.0;
 238   sum = 0;
 239   for (i = 0; i < HISTOGRAM_NUM_BINS; i++)
 240   {
 241     percent_lower = percent_upper;
 242     sum += lc->histogram[i];
 243     if (sum == 0)
 244       percent_upper = 0.0;
 245     else
 246       percent_upper = 100.0 * ((double) sum) / ((double) lc->num);
 247
 248     if (percent_upper >= percent)
 249       break;
 250   }
 251
 252   if (i >= HISTOGRAM_NUM_BINS)
 253     return (0);
 254
 255   assert (percent_upper >= percent);
 256   assert (percent_lower < percent);
 257
 258   if (i == 0)
 259     return (lc->bin_width);
 260
 261   latency_lower = ((cdtime_t) i) * lc->bin_width;
 262   p = (percent - percent_lower) / (percent_upper - percent_lower);
 263
 264   latency_interpolated = latency_lower
 265     + DOUBLE_TO_CDTIME_T (p * CDTIME_T_TO_DOUBLE (lc->bin_width));
 266
 267   DEBUG ("latency_counter_get_percentile: latency_interpolated = %.3f",
 268       CDTIME_T_TO_DOUBLE (latency_interpolated));
 269   return (latency_interpolated);
 270 } /* }}} cdtime_t latency_counter_get_percentile */
 271
 272 /* vim: set sw=2 sts=2 et fdm=marker : */