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