src/rrd_tune.c

   1 /*****************************************************************************
   2  * RRDtool 1.2.23  Copyright by Tobi Oetiker, 1997-2007
   3  *****************************************************************************
   4  * change header parameters of an rrd
   5  *****************************************************************************
   6  * $Id$
   7  * $Log$
   8  * Revision 1.6  2004/05/26 22:11:12  oetiker
   9  * reduce compiler warnings. Many small fixes. -- Mike Slifcak <slif@bellsouth.net>
  10  *
  11  * Revision 1.5  2002/02/01 20:34:49  oetiker
  12  * fixed version number and date/time
  13  *
  14  * Revision 1.4  2001/08/22 22:29:07  jake
  15  * Contents of this patch:
  16  * (1) Adds/revises documentation for rrd tune in rrd_tool.c and pod files.
  17  * (2) Moves some initialization code from rrd_create.c to rrd_hw.c.
  18  * (3) Adds another pass to smoothing for SEASONAL and DEVSEASONAL RRAs.
  19  * This pass computes the coefficients as deviations from an average; the
  20  * average is added the baseline coefficient of HWPREDICT. Statistical texts
  21  * suggest this to preserve algorithm stability. It will not invalidate
  22  * RRD files created and smoothed with the old code.
  23  * (4) Adds the aberrant-reset flag to rrd tune. This operation, which is
  24  * specified for a single data source, causes the holt-winters algorithm to
  25  * forget everthing it has learned and start over.
  26  * (5) Fixes a few out-of-date code comments.
  27  *
  28  * Revision 1.3  2001/03/07 21:21:54  oetiker
  29  * complete rewrite of rrdgraph documentation. This also includs info
  30  * on upcomming/planned changes to the rrdgraph interface and functionality
  31  * -- Alex van den Bogaerdt <alex@slot.hollandcasino.nl>
  32  *
  33  * Revision 1.2  2001/03/04 13:01:55  oetiker
  34  * Aberrant Behavior Detection support. A brief overview added to rrdtool.pod.
  35  * Major updates to rrd_update.c, rrd_create.c. Minor update to other core files.
  36  * This is backwards compatible! But new files using the Aberrant stuff are not readable
  37  * by old rrdtool versions. See http://cricket.sourceforge.net/aberrant/rrd_hw.htm
  38  * -- Jake Brutlag <jakeb@corp.webtv.net>
  39  *
  40  *****************************************************************************/
  41
  42 #include "rrd_tool.h"
  43 #include "rrd_rpncalc.h"
  44 #include "rrd_hw.h"
  45
  46 int       set_hwarg(
  47     rrd_t *rrd,
  48     enum cf_en cf,
  49     enum rra_par_en rra_par,
  50     char *arg);
  51 int       set_deltaarg(
  52     rrd_t *rrd,
  53     enum rra_par_en rra_par,
  54     char *arg);
  55 int       set_windowarg(
  56     rrd_t *rrd,
  57     enum rra_par_en,
  58     char *arg);
  59
  60 int rrd_tune(
  61     int argc,
  62     char **argv)
  63 {
  64     rrd_t     rrd;
  65     int       matches;
  66     int       optcnt = 0;
  67     long      ds;
  68     char      ds_nam[DS_NAM_SIZE];
  69     char      ds_new[DS_NAM_SIZE];
  70     long      heartbeat;
  71     double    min;
  72     double    max;
  73     char      dst[DST_SIZE];
  74     rrd_file_t *rrd_file;
  75
  76     optind = 0;
  77     opterr = 0;         /* initialize getopt */
  78
  79
  80     rrd_file = rrd_open(argv[1], &rrd, RRD_READWRITE);
  81     if (rrd_file == NULL) {
  82         rrd_free(&rrd);
  83         return -1;
  84     }
  85
  86     while (1) {
  87         static struct option long_options[] = {
  88             {"heartbeat", required_argument, 0, 'h'},
  89             {"minimum", required_argument, 0, 'i'},
  90             {"maximum", required_argument, 0, 'a'},
  91             {"data-source-type", required_argument, 0, 'd'},
  92             {"data-source-rename", required_argument, 0, 'r'},
  93             /* added parameter tuning options for aberrant behavior detection */
  94             {"deltapos", required_argument, 0, 'p'},
  95             {"deltaneg", required_argument, 0, 'n'},
  96             {"window-length", required_argument, 0, 'w'},
  97             {"failure-threshold", required_argument, 0, 'f'},
  98             {"alpha", required_argument, 0, 'x'},
  99             {"beta", required_argument, 0, 'y'},
 100             {"gamma", required_argument, 0, 'z'},
 101             {"gamma-deviation", required_argument, 0, 'v'},
 102             {"aberrant-reset", required_argument, 0, 'b'},
 103             {0, 0, 0, 0}
 104         };
 105         int       option_index = 0;
 106         int       opt;
 107
 108         opt = getopt_long(argc, argv, "h:i:a:d:r:p:n:w:f:x:y:z:v:b:",
 109                           long_options, &option_index);
 110         if (opt == EOF)
 111             break;
 112
 113         optcnt++;
 114         switch (opt) {
 115         case 'h':
 116             if ((matches =
 117                  sscanf(optarg, DS_NAM_FMT ":%ld", ds_nam,
 118                         &heartbeat)) != 2) {
 119                 rrd_set_error("invalid arguments for heartbeat");
 120                 rrd_free(&rrd);
 121                 rrd_close(rrd_file);
 122                 return -1;
 123             }
 124             if ((ds = ds_match(&rrd, ds_nam)) == -1) {
 125                 rrd_free(&rrd);
 126                 rrd_close(rrd_file);
 127                 return -1;
 128             }
 129             rrd.ds_def[ds].par[DS_mrhb_cnt].u_cnt = heartbeat;
 130             break;
 131
 132         case 'i':
 133             if ((matches =
 134                  sscanf(optarg, DS_NAM_FMT ":%lf", ds_nam, &min)) < 1) {
 135                 rrd_set_error("invalid arguments for minimum ds value");
 136                 rrd_free(&rrd);
 137                 rrd_close(rrd_file);
 138                 return -1;
 139             }
 140             if ((ds = ds_match(&rrd, ds_nam)) == -1) {
 141                 rrd_free(&rrd);
 142                 rrd_close(rrd_file);
 143                 return -1;
 144             }
 145
 146             if (matches == 1)
 147                 min = DNAN;
 148             rrd.ds_def[ds].par[DS_min_val].u_val = min;
 149             break;
 150
 151         case 'a':
 152             if ((matches =
 153                  sscanf(optarg, DS_NAM_FMT ":%lf", ds_nam, &max)) < 1) {
 154                 rrd_set_error("invalid arguments for maximum ds value");
 155                 rrd_free(&rrd);
 156                 rrd_close(rrd_file);
 157                 return -1;
 158             }
 159             if ((ds = ds_match(&rrd, ds_nam)) == -1) {
 160                 rrd_free(&rrd);
 161                 rrd_close(rrd_file);
 162                 return -1;
 163             }
 164             if (matches == 1)
 165                 max = DNAN;
 166             rrd.ds_def[ds].par[DS_max_val].u_val = max;
 167             break;
 168
 169         case 'd':
 170             if ((matches =
 171                  sscanf(optarg, DS_NAM_FMT ":" DST_FMT, ds_nam, dst)) != 2) {
 172                 rrd_set_error("invalid arguments for data source type");
 173                 rrd_free(&rrd);
 174                 rrd_close(rrd_file);
 175                 return -1;
 176             }
 177             if ((ds = ds_match(&rrd, ds_nam)) == -1) {
 178                 rrd_free(&rrd);
 179                 rrd_close(rrd_file);
 180                 return -1;
 181             }
 182             if ((int) dst_conv(dst) == -1) {
 183                 rrd_free(&rrd);
 184                 rrd_close(rrd_file);
 185                 return -1;
 186             }
 187             strncpy(rrd.ds_def[ds].dst, dst, DST_SIZE - 1);
 188             rrd.ds_def[ds].dst[DST_SIZE - 1] = '\0';
 189
 190             rrd.pdp_prep[ds].last_ds[0] = 'U';
 191             rrd.pdp_prep[ds].last_ds[1] = 'N';
 192             rrd.pdp_prep[ds].last_ds[2] = 'K';
 193             rrd.pdp_prep[ds].last_ds[3] = 'N';
 194             rrd.pdp_prep[ds].last_ds[4] = '\0';
 195
 196             break;
 197         case 'r':
 198             if ((matches =
 199                  sscanf(optarg, DS_NAM_FMT ":" DS_NAM_FMT, ds_nam,
 200                         ds_new)) != 2) {
 201                 rrd_set_error("invalid arguments for data source type");
 202                 rrd_free(&rrd);
 203                 rrd_close(rrd_file);
 204                 return -1;
 205             }
 206             if ((ds = ds_match(&rrd, ds_nam)) == -1) {
 207                 rrd_free(&rrd);
 208                 rrd_close(rrd_file);
 209                 return -1;
 210             }
 211             strncpy(rrd.ds_def[ds].ds_nam, ds_new, DS_NAM_SIZE - 1);
 212             rrd.ds_def[ds].ds_nam[DS_NAM_SIZE - 1] = '\0';
 213             break;
 214         case 'p':
 215             if (set_deltaarg(&rrd, RRA_delta_pos, optarg)) {
 216                 rrd_free(&rrd);
 217                 return -1;
 218             }
 219             break;
 220         case 'n':
 221             if (set_deltaarg(&rrd, RRA_delta_neg, optarg)) {
 222                 rrd_free(&rrd);
 223                 return -1;
 224             }
 225             break;
 226         case 'f':
 227             if (set_windowarg(&rrd, RRA_failure_threshold, optarg)) {
 228                 rrd_free(&rrd);
 229                 return -1;
 230             }
 231             break;
 232         case 'w':
 233             if (set_windowarg(&rrd, RRA_window_len, optarg)) {
 234                 rrd_free(&rrd);
 235                 return -1;
 236             }
 237             break;
 238         case 'x':
 239             if (set_hwarg(&rrd, CF_HWPREDICT, RRA_hw_alpha, optarg)) {
 240                 if (set_hwarg(&rrd, CF_MHWPREDICT, RRA_hw_alpha, optarg)) {
 241                     rrd_free(&rrd);
 242                     return -1;
 243                 }
 244                 rrd_clear_error();
 245             }
 246             break;
 247         case 'y':
 248             if (set_hwarg(&rrd, CF_HWPREDICT, RRA_hw_beta, optarg)) {
 249                 if (set_hwarg(&rrd, CF_MHWPREDICT, RRA_hw_beta, optarg)) {
 250                     rrd_free(&rrd);
 251                     return -1;
 252                 }
 253                 rrd_clear_error();
 254             }
 255             break;
 256         case 'z':
 257             if (set_hwarg(&rrd, CF_SEASONAL, RRA_seasonal_gamma, optarg)) {
 258                 rrd_free(&rrd);
 259                 return -1;
 260             }
 261             break;
 262         case 'v':
 263             if (set_hwarg(&rrd, CF_DEVSEASONAL, RRA_seasonal_gamma, optarg)) {
 264                 rrd_free(&rrd);
 265                 return -1;
 266             }
 267             break;
 268         case 'b':
 269             if (sscanf(optarg, DS_NAM_FMT, ds_nam) != 1) {
 270                 rrd_set_error("invalid argument for aberrant-reset");
 271                 rrd_free(&rrd);
 272                 rrd_close(rrd_file);
 273                 return -1;
 274             }
 275             if ((ds = ds_match(&rrd, ds_nam)) == -1) {
 276                 /* ds_match handles it own errors */
 277                 rrd_free(&rrd);
 278                 rrd_close(rrd_file);
 279                 return -1;
 280             }
 281             reset_aberrant_coefficients(&rrd, rrd_file, (unsigned long) ds);
 282             if (rrd_test_error()) {
 283                 rrd_free(&rrd);
 284                 rrd_close(rrd_file);
 285                 return -1;
 286             }
 287             break;
 288         case '?':
 289             if (optopt != 0)
 290                 rrd_set_error("unknown option '%c'", optopt);
 291             else
 292                 rrd_set_error("unknown option '%s'", argv[optind - 1]);
 293             rrd_free(&rrd);
 294             rrd_close(rrd_file);
 295             return -1;
 296         }
 297     }
 298     if (optcnt > 0) {
 299         rrd_seek(rrd_file, 0, SEEK_SET);
 300         rrd_write(rrd_file, rrd.stat_head, sizeof(stat_head_t) * 1);
 301         rrd_write(rrd_file, rrd.ds_def,
 302                   sizeof(ds_def_t) * rrd.stat_head->ds_cnt);
 303         /* need to write rra_defs for RRA parameter changes */
 304         rrd_write(rrd_file, rrd.rra_def,
 305                   sizeof(rra_def_t) * rrd.stat_head->rra_cnt);
 306     } else {
 307         int       i;
 308
 309         for (i = 0; i < (int) rrd.stat_head->ds_cnt; i++)
 310             if (dst_conv(rrd.ds_def[i].dst) != DST_CDEF) {
 311                 printf("DS[%s] typ: %s\thbt: %ld\tmin: %1.4f\tmax: %1.4f\n",
 312                        rrd.ds_def[i].ds_nam,
 313                        rrd.ds_def[i].dst,
 314                        rrd.ds_def[i].par[DS_mrhb_cnt].u_cnt,
 315                        rrd.ds_def[i].par[DS_min_val].u_val,
 316                        rrd.ds_def[i].par[DS_max_val].u_val);
 317             } else {
 318                 char     *buffer = NULL;
 319
 320                 rpn_compact2str((rpn_cdefds_t *) &
 321                                 (rrd.ds_def[i].par[DS_cdef]), rrd.ds_def,
 322                                 &buffer);
 323                 printf("DS[%s] typ: %s\tcdef: %s\n", rrd.ds_def[i].ds_nam,
 324                        rrd.ds_def[i].dst, buffer);
 325                 free(buffer);
 326             }
 327     }
 328     rrd_close(rrd_file);
 329     rrd_free(&rrd);
 330     return 0;
 331 }
 332
 333 int set_hwarg(
 334     rrd_t *rrd,
 335     enum cf_en cf,
 336     enum rra_par_en rra_par,
 337     char *arg)
 338 {
 339     double    param;
 340     unsigned long i;
 341     signed short rra_idx = -1;
 342
 343     /* read the value */
 344     param = atof(arg);
 345     if (param <= 0.0 || param >= 1.0) {
 346         rrd_set_error("Holt-Winters parameter must be between 0 and 1");
 347         return -1;
 348     }
 349     /* does the appropriate RRA exist?  */
 350     for (i = 0; i < rrd->stat_head->rra_cnt; ++i) {
 351         if (cf_conv(rrd->rra_def[i].cf_nam) == cf) {
 352             rra_idx = i;
 353             break;
 354         }
 355     }
 356     if (rra_idx == -1) {
 357         rrd_set_error("Holt-Winters RRA does not exist in this RRD");
 358         return -1;
 359     }
 360
 361     /* set the value */
 362     rrd->rra_def[rra_idx].par[rra_par].u_val = param;
 363     return 0;
 364 }
 365
 366 int set_deltaarg(
 367     rrd_t *rrd,
 368     enum rra_par_en rra_par,
 369     char *arg)
 370 {
 371     rrd_value_t param;
 372     unsigned long i;
 373     signed short rra_idx = -1;
 374
 375     param = atof(arg);
 376     if (param < 0.1) {
 377         rrd_set_error("Parameter specified is too small");
 378         return -1;
 379     }
 380     /* does the appropriate RRA exist?  */
 381     for (i = 0; i < rrd->stat_head->rra_cnt; ++i) {
 382         if (cf_conv(rrd->rra_def[i].cf_nam) == CF_FAILURES) {
 383             rra_idx = i;
 384             break;
 385         }
 386     }
 387     if (rra_idx == -1) {
 388         rrd_set_error("Failures RRA does not exist in this RRD");
 389         return -1;
 390     }
 391
 392     /* set the value */
 393     rrd->rra_def[rra_idx].par[rra_par].u_val = param;
 394     return 0;
 395 }
 396
 397 int set_windowarg(
 398     rrd_t *rrd,
 399     enum rra_par_en rra_par,
 400     char *arg)
 401 {
 402     unsigned long param;
 403     unsigned long i, cdp_idx;
 404     signed short rra_idx = -1;
 405
 406     /* read the value */
 407     param = atoi(arg);
 408     if (param < 1 || param > MAX_FAILURES_WINDOW_LEN) {
 409         rrd_set_error("Parameter must be between %d and %d",
 410                       1, MAX_FAILURES_WINDOW_LEN);
 411         return -1;
 412     }
 413     /* does the appropriate RRA exist?  */
 414     for (i = 0; i < rrd->stat_head->rra_cnt; ++i) {
 415         if (cf_conv(rrd->rra_def[i].cf_nam) == CF_FAILURES) {
 416             rra_idx = i;
 417             break;
 418         }
 419     }
 420     if (rra_idx == -1) {
 421         rrd_set_error("Failures RRA does not exist in this RRD");
 422         return -1;
 423     }
 424
 425     /* set the value */
 426     rrd->rra_def[rra_idx].par[rra_par].u_cnt = param;
 427
 428     /* erase existing violations */
 429     for (i = 0; i < rrd->stat_head->ds_cnt; i++) {
 430         cdp_idx = rra_idx * (rrd->stat_head->ds_cnt) + i;
 431         erase_violations(rrd, cdp_idx, rra_idx);
 432     }
 433     return 0;
 434 }