Code

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