src/rrd_tune.c

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