src/rrd_tune.c

   1 /*****************************************************************************
   2  * RRDtool 1.3.2  Copyright by Tobi Oetiker, 1997-2008
   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 <stdlib.h>
  43 #include <locale.h>
  44
  45 #include "rrd_tool.h"
  46 #include "rrd_rpncalc.h"
  47 #include "rrd_hw.h"
  48
  49 int       set_hwarg(
  50     rrd_t *rrd,
  51     enum cf_en cf,
  52     enum rra_par_en rra_par,
  53     char *arg);
  54 int       set_deltaarg(
  55     rrd_t *rrd,
  56     enum rra_par_en rra_par,
  57     char *arg);
  58 int       set_windowarg(
  59     rrd_t *rrd,
  60     enum rra_par_en,
  61     char *arg);
  62
  63 int rrd_tune(
  64     int argc,
  65     char **argv)
  66 {
  67     rrd_t     rrd;
  68     int       matches;
  69     int       optcnt = 0;
  70     long      ds;
  71     char      ds_nam[DS_NAM_SIZE];
  72     char      ds_new[DS_NAM_SIZE];
  73     long      heartbeat;
  74     double    min;
  75     double    max;
  76     char      dst[DST_SIZE];
  77     rrd_file_t *rrd_file;
  78     struct option long_options[] = {
  79         {"heartbeat", required_argument, 0, 'h'},
  80         {"minimum", required_argument, 0, 'i'},
  81         {"maximum", required_argument, 0, 'a'},
  82         {"data-source-type", required_argument, 0, 'd'},
  83         {"data-source-rename", required_argument, 0, 'r'},
  84         /* added parameter tuning options for aberrant behavior detection */
  85         {"deltapos", required_argument, 0, 'p'},
  86         {"deltaneg", required_argument, 0, 'n'},
  87         {"window-length", required_argument, 0, 'w'},
  88         {"failure-threshold", required_argument, 0, 'f'},
  89         {"alpha", required_argument, 0, 'x'},
  90         {"beta", required_argument, 0, 'y'},
  91         {"gamma", required_argument, 0, 'z'},
  92         {"gamma-deviation", required_argument, 0, 'v'},
  93         {"smoothing-window", required_argument, 0, 's'},
  94         {"smoothing-window-deviation", required_argument, 0, 'S'},
  95         {"aberrant-reset", required_argument, 0, 'b'},
  96         {0, 0, 0, 0}
  97     };
  98
  99     optind = 0;
 100     opterr = 0;         /* initialize getopt */
 101
 102
 103     rrd_init(&rrd);
 104     rrd_file = rrd_open(argv[1], &rrd, RRD_READWRITE);
 105     if (rrd_file == NULL) {
 106         rrd_free(&rrd);
 107         return -1;
 108     }
 109
 110     while (1) {
 111         int       option_index = 0;
 112         int       opt;
 113         char     *old_locale = "";
 114
 115         opt = getopt_long(argc, argv, "h:i:a:d:r:p:n:w:f:x:y:z:v:b:",
 116                           long_options, &option_index);
 117         if (opt == EOF)
 118             break;
 119
 120         optcnt++;
 121         switch (opt) {
 122         case 'h':
 123             old_locale = setlocale(LC_NUMERIC, "C");
 124             if ((matches =
 125                  sscanf(optarg, DS_NAM_FMT ":%ld", ds_nam,
 126                         &heartbeat)) != 2) {
 127                 rrd_set_error("invalid arguments for heartbeat");
 128                 rrd_free(&rrd);
 129                 rrd_close(rrd_file);
 130                 setlocale(LC_NUMERIC, old_locale);
 131                 return -1;
 132             }
 133             setlocale(LC_NUMERIC, old_locale);
 134             if ((ds = ds_match(&rrd, ds_nam)) == -1) {
 135                 rrd_free(&rrd);
 136                 rrd_close(rrd_file);
 137                 return -1;
 138             }
 139             rrd.ds_def[ds].par[DS_mrhb_cnt].u_cnt = heartbeat;
 140             break;
 141
 142         case 'i':
 143             old_locale = setlocale(LC_NUMERIC, "C");
 144             if ((matches =
 145                  sscanf(optarg, DS_NAM_FMT ":%lf", ds_nam, &min)) < 1) {
 146                 rrd_set_error("invalid arguments for minimum ds value");
 147                 rrd_free(&rrd);
 148                 rrd_close(rrd_file);
 149                 setlocale(LC_NUMERIC, old_locale);
 150                 return -1;
 151             }
 152             setlocale(LC_NUMERIC, old_locale);
 153             if ((ds = ds_match(&rrd, ds_nam)) == -1) {
 154                 rrd_free(&rrd);
 155                 rrd_close(rrd_file);
 156                 return -1;
 157             }
 158
 159             if (matches == 1)
 160                 min = DNAN;
 161             rrd.ds_def[ds].par[DS_min_val].u_val = min;
 162             break;
 163
 164         case 'a':
 165             old_locale = setlocale(LC_NUMERIC, "C");
 166             if ((matches =
 167                  sscanf(optarg, DS_NAM_FMT ":%lf", ds_nam, &max)) < 1) {
 168                 rrd_set_error("invalid arguments for maximum ds value");
 169                 rrd_free(&rrd);
 170                 rrd_close(rrd_file);
 171                 setlocale(LC_NUMERIC, old_locale);
 172                 return -1;
 173             }
 174             setlocale(LC_NUMERIC, old_locale);
 175             if ((ds = ds_match(&rrd, ds_nam)) == -1) {
 176                 rrd_free(&rrd);
 177                 rrd_close(rrd_file);
 178                 return -1;
 179             }
 180             if (matches == 1)
 181                 max = DNAN;
 182             rrd.ds_def[ds].par[DS_max_val].u_val = max;
 183             break;
 184
 185         case 'd':
 186             if ((matches =
 187                  sscanf(optarg, DS_NAM_FMT ":" DST_FMT, ds_nam, dst)) != 2) {
 188                 rrd_set_error("invalid arguments for data source type");
 189                 rrd_free(&rrd);
 190                 rrd_close(rrd_file);
 191                 return -1;
 192             }
 193             if ((ds = ds_match(&rrd, ds_nam)) == -1) {
 194                 rrd_free(&rrd);
 195                 rrd_close(rrd_file);
 196                 return -1;
 197             }
 198             if ((int) dst_conv(dst) == -1) {
 199                 rrd_free(&rrd);
 200                 rrd_close(rrd_file);
 201                 return -1;
 202             }
 203             /* only reset when something is changed */
 204             if (strncmp(rrd.ds_def[ds].dst, dst, DST_SIZE - 1) != 0) {
 205                 strncpy(rrd.ds_def[ds].dst, dst, DST_SIZE - 1);
 206                 rrd.ds_def[ds].dst[DST_SIZE - 1] = '\0';
 207
 208                 rrd.pdp_prep[ds].last_ds[0] = 'U';
 209                 rrd.pdp_prep[ds].last_ds[1] = 'N';
 210                 rrd.pdp_prep[ds].last_ds[2] = 'K';
 211                 rrd.pdp_prep[ds].last_ds[3] = 'N';
 212                 rrd.pdp_prep[ds].last_ds[4] = '\0';
 213             }
 214             break;
 215         case 'r':
 216             if ((matches =
 217                  sscanf(optarg, DS_NAM_FMT ":" DS_NAM_FMT, ds_nam,
 218                         ds_new)) != 2) {
 219                 rrd_set_error("invalid arguments for data source type");
 220                 rrd_free(&rrd);
 221                 rrd_close(rrd_file);
 222                 return -1;
 223             }
 224             if ((ds = ds_match(&rrd, ds_nam)) == -1) {
 225                 rrd_free(&rrd);
 226                 rrd_close(rrd_file);
 227                 return -1;
 228             }
 229             strncpy(rrd.ds_def[ds].ds_nam, ds_new, DS_NAM_SIZE - 1);
 230             rrd.ds_def[ds].ds_nam[DS_NAM_SIZE - 1] = '\0';
 231             break;
 232         case 'p':
 233             if (set_deltaarg(&rrd, RRA_delta_pos, optarg)) {
 234                 rrd_free(&rrd);
 235                 return -1;
 236             }
 237             break;
 238         case 'n':
 239             if (set_deltaarg(&rrd, RRA_delta_neg, optarg)) {
 240                 rrd_free(&rrd);
 241                 return -1;
 242             }
 243             break;
 244         case 'f':
 245             if (set_windowarg(&rrd, RRA_failure_threshold, optarg)) {
 246                 rrd_free(&rrd);
 247                 return -1;
 248             }
 249             break;
 250         case 'w':
 251             if (set_windowarg(&rrd, RRA_window_len, optarg)) {
 252                 rrd_free(&rrd);
 253                 return -1;
 254             }
 255             break;
 256         case 'x':
 257             if (set_hwarg(&rrd, CF_HWPREDICT, RRA_hw_alpha, optarg)) {
 258                 if (set_hwarg(&rrd, CF_MHWPREDICT, RRA_hw_alpha, optarg)) {
 259                     rrd_free(&rrd);
 260                     return -1;
 261                 }
 262                 rrd_clear_error();
 263             }
 264             break;
 265         case 'y':
 266             if (set_hwarg(&rrd, CF_HWPREDICT, RRA_hw_beta, optarg)) {
 267                 if (set_hwarg(&rrd, CF_MHWPREDICT, RRA_hw_beta, optarg)) {
 268                     rrd_free(&rrd);
 269                     return -1;
 270                 }
 271                 rrd_clear_error();
 272             }
 273             break;
 274         case 'z':
 275             if (set_hwarg(&rrd, CF_SEASONAL, RRA_seasonal_gamma, optarg)) {
 276                 rrd_free(&rrd);
 277                 return -1;
 278             }
 279             break;
 280         case 'v':
 281             if (set_hwarg(&rrd, CF_DEVSEASONAL, RRA_seasonal_gamma, optarg)) {
 282                 rrd_free(&rrd);
 283                 return -1;
 284             }
 285             break;
 286         case 'b':
 287             if (sscanf(optarg, DS_NAM_FMT, ds_nam) != 1) {
 288                 rrd_set_error("invalid argument for aberrant-reset");
 289                 rrd_free(&rrd);
 290                 rrd_close(rrd_file);
 291                 return -1;
 292             }
 293             if ((ds = ds_match(&rrd, ds_nam)) == -1) {
 294                 /* ds_match handles it own errors */
 295                 rrd_free(&rrd);
 296                 rrd_close(rrd_file);
 297                 return -1;
 298             }
 299             reset_aberrant_coefficients(&rrd, rrd_file, (unsigned long) ds);
 300             if (rrd_test_error()) {
 301                 rrd_free(&rrd);
 302                 rrd_close(rrd_file);
 303                 return -1;
 304             }
 305             break;
 306         case 's':
 307             strcpy(rrd.stat_head->version, RRD_VERSION);    /* smoothing_window causes Version 4 */
 308             if (set_hwsmootharg
 309                 (&rrd, CF_SEASONAL, RRA_seasonal_smoothing_window, optarg)) {
 310                 rrd_free(&rrd);
 311                 return -1;
 312             }
 313             break;
 314         case 'S':
 315             strcpy(rrd.stat_head->version, RRD_VERSION);    /* smoothing_window causes Version 4 */
 316             if (set_hwsmootharg
 317                 (&rrd, CF_DEVSEASONAL, RRA_seasonal_smoothing_window,
 318                  optarg)) {
 319                 rrd_free(&rrd);
 320                 return -1;
 321             }
 322             break;
 323         case '?':
 324             if (optopt != 0)
 325                 rrd_set_error("unknown option '%c'", optopt);
 326             else
 327                 rrd_set_error("unknown option '%s'", argv[optind - 1]);
 328             rrd_free(&rrd);
 329             rrd_close(rrd_file);
 330             return -1;
 331         }
 332     }
 333     if (optcnt > 0) {
 334         rrd_seek(rrd_file, 0, SEEK_SET);
 335         rrd_write(rrd_file, rrd.stat_head, sizeof(stat_head_t) * 1);
 336         rrd_write(rrd_file, rrd.ds_def,
 337                   sizeof(ds_def_t) * rrd.stat_head->ds_cnt);
 338         /* need to write rra_defs for RRA parameter changes */
 339         rrd_write(rrd_file, rrd.rra_def,
 340                   sizeof(rra_def_t) * rrd.stat_head->rra_cnt);
 341     } else {
 342         int       i;
 343
 344         for (i = 0; i < (int) rrd.stat_head->ds_cnt; i++)
 345             if (dst_conv(rrd.ds_def[i].dst) != DST_CDEF) {
 346                 printf("DS[%s] typ: %s\thbt: %ld\tmin: %1.4f\tmax: %1.4f\n",
 347                        rrd.ds_def[i].ds_nam,
 348                        rrd.ds_def[i].dst,
 349                        rrd.ds_def[i].par[DS_mrhb_cnt].u_cnt,
 350                        rrd.ds_def[i].par[DS_min_val].u_val,
 351                        rrd.ds_def[i].par[DS_max_val].u_val);
 352             } else {
 353                 char     *buffer = NULL;
 354
 355                 rpn_compact2str((rpn_cdefds_t *) &
 356                                 (rrd.ds_def[i].par[DS_cdef]), rrd.ds_def,
 357                                 &buffer);
 358                 printf("DS[%s] typ: %s\tcdef: %s\n", rrd.ds_def[i].ds_nam,
 359                        rrd.ds_def[i].dst, buffer);
 360                 free(buffer);
 361             }
 362     }
 363     rrd_close(rrd_file);
 364     rrd_free(&rrd);
 365     return 0;
 366 }
 367
 368 int set_hwarg(
 369     rrd_t *rrd,
 370     enum cf_en cf,
 371     enum rra_par_en rra_par,
 372     char *arg)
 373 {
 374     double    param;
 375     unsigned long i;
 376     signed short rra_idx = -1;
 377
 378     /* read the value */
 379     param = atof(arg);
 380     if (param <= 0.0 || param >= 1.0) {
 381         rrd_set_error("Holt-Winters parameter must be between 0 and 1");
 382         return -1;
 383     }
 384     /* does the appropriate RRA exist?  */
 385     for (i = 0; i < rrd->stat_head->rra_cnt; ++i) {
 386         if (cf_conv(rrd->rra_def[i].cf_nam) == cf) {
 387             rra_idx = i;
 388             break;
 389         }
 390     }
 391     if (rra_idx == -1) {
 392         rrd_set_error("Holt-Winters RRA does not exist in this RRD");
 393         return -1;
 394     }
 395
 396     /* set the value */
 397     rrd->rra_def[rra_idx].par[rra_par].u_val = param;
 398     return 0;
 399 }
 400
 401 int set_hwsmootharg(
 402     rrd_t *rrd,
 403     enum cf_en cf,
 404     enum rra_par_en rra_par,
 405     char *arg)
 406 {
 407     double    param;
 408     unsigned long i;
 409     signed short rra_idx = -1;
 410
 411     /* read the value */
 412     param = atof(arg);
 413     /* in order to avoid smoothing of SEASONAL or DEVSEASONAL, we need to
 414      * the 0.0 value*/
 415     if (param < 0.0 || param > 1.0) {
 416         rrd_set_error("Holt-Winters parameter must be between 0 and 1");
 417         return -1;
 418     }
 419     /* does the appropriate RRA exist?  */
 420     for (i = 0; i < rrd->stat_head->rra_cnt; ++i) {
 421         if (cf_conv(rrd->rra_def[i].cf_nam) == cf) {
 422             rra_idx = i;
 423             break;
 424         }
 425     }
 426     if (rra_idx == -1) {
 427         rrd_set_error("Holt-Winters RRA does not exist in this RRD");
 428         return -1;
 429     }
 430
 431     /* set the value */
 432     rrd->rra_def[rra_idx].par[rra_par].u_val = param;
 433     return 0;
 434 }
 435
 436 int set_deltaarg(
 437     rrd_t *rrd,
 438     enum rra_par_en rra_par,
 439     char *arg)
 440 {
 441     rrd_value_t param;
 442     unsigned long i;
 443     signed short rra_idx = -1;
 444
 445     param = atof(arg);
 446     if (param < 0.1) {
 447         rrd_set_error("Parameter specified is too small");
 448         return -1;
 449     }
 450     /* does the appropriate RRA exist?  */
 451     for (i = 0; i < rrd->stat_head->rra_cnt; ++i) {
 452         if (cf_conv(rrd->rra_def[i].cf_nam) == CF_FAILURES) {
 453             rra_idx = i;
 454             break;
 455         }
 456     }
 457     if (rra_idx == -1) {
 458         rrd_set_error("Failures RRA does not exist in this RRD");
 459         return -1;
 460     }
 461
 462     /* set the value */
 463     rrd->rra_def[rra_idx].par[rra_par].u_val = param;
 464     return 0;
 465 }
 466
 467 int set_windowarg(
 468     rrd_t *rrd,
 469     enum rra_par_en rra_par,
 470     char *arg)
 471 {
 472     unsigned long param;
 473     unsigned long i, cdp_idx;
 474     signed short rra_idx = -1;
 475
 476     /* read the value */
 477     param = atoi(arg);
 478     if (param < 1 || param > MAX_FAILURES_WINDOW_LEN) {
 479         rrd_set_error("Parameter must be between %d and %d",
 480                       1, MAX_FAILURES_WINDOW_LEN);
 481         return -1;
 482     }
 483     /* does the appropriate RRA exist?  */
 484     for (i = 0; i < rrd->stat_head->rra_cnt; ++i) {
 485         if (cf_conv(rrd->rra_def[i].cf_nam) == CF_FAILURES) {
 486             rra_idx = i;
 487             break;
 488         }
 489     }
 490     if (rra_idx == -1) {
 491         rrd_set_error("Failures RRA does not exist in this RRD");
 492         return -1;
 493     }
 494
 495     /* set the value */
 496     rrd->rra_def[rra_idx].par[rra_par].u_cnt = param;
 497
 498     /* erase existing violations */
 499     for (i = 0; i < rrd->stat_head->ds_cnt; i++) {
 500         cdp_idx = rra_idx * (rrd->stat_head->ds_cnt) + i;
 501         erase_violations(rrd, cdp_idx, rra_idx);
 502     }
 503     return 0;
 504 }