program/src/rrd_tune.c

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