src/rrd_tune.c

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