src/rrd_format.h

   1 /*****************************************************************************
   2  * RRDtool 1.2.99907080300  Copyright by Tobi Oetiker, 1997-2007
   3  *****************************************************************************
   4  * rrd_format.h  RRD Database Format header
   5  *****************************************************************************/
   6
   7 #ifndef _RRD_FORMAT_H
   8 #define _RRD_FORMAT_H
   9
  10 #include "rrd.h"
  11
  12 /*****************************************************************************
  13  * put this in your /usr/lib/magic file (/etc/magic on HPUX)
  14  *
  15  *  # rrd database format
  16  *  0       string          RRD\0           rrd file
  17  *  >5      string          >\0             version '%s'
  18  *
  19  *****************************************************************************/
  20
  21 #define RRD_COOKIE    "RRD"
  22 /* #define RRD_VERSION   "0002" */
  23 /* changed because microsecond precision requires another field */
  24 #define RRD_VERSION   "0004"
  25 #define RRD_VERSION3  "0003"
  26 #define FLOAT_COOKIE  8.642135E130
  27
  28 #include "rrd_nan_inf.h"
  29
  30 typedef union unival {
  31     unsigned long u_cnt;
  32     rrd_value_t u_val;
  33 } unival;
  34
  35
  36 /****************************************************************************
  37  * The RRD Database Structure
  38  * ---------------------------
  39  *
  40  * In oder to properly describe the database structure lets define a few
  41  * new words:
  42  *
  43  * ds - Data Source (ds) providing input to the database. A Data Source (ds)
  44  *       can be a traffic counter, a temperature, the number of users logged
  45  *       into a system. The rrd database format can handle the input of
  46  *       several Data Sources (ds) in a singe database.
  47  *
  48  * dst - Data Source Type (dst). The Data Source Type (dst) defines the rules
  49  *       applied to Build Primary Data Points from the input provided by the
  50  *       data sources (ds).
  51  *
  52  * pdp - Primary Data Point (pdp). After the database has accepted the
  53  *       input from the data sources (ds). It starts building Primary
  54  *       Data Points (pdp) from the data. Primary Data Points (pdp)
  55  *       are evenly spaced along the time axis (pdp_step). The values
  56  *       of the Primary Data Points are calculated from the values of
  57  *       the data source (ds) and the exact time these values were
  58  *       provided by the data source (ds).
  59  *
  60  * pdp_st - PDP Start (pdp_st). The moments (pdp_st) in time where
  61  *       these steps occur are defined by the moments where the
  62  *       number of seconds since 1970-jan-1 modulo pdp_step equals
  63  *       zero (pdp_st).
  64  *
  65  * cf -  Consolidation Function (cf). An arbitrary Consolidation Function (cf)
  66  *       (averaging, min, max) is applied to the primary data points (pdp) to
  67  *       calculate the consolidated data point.
  68  *
  69  * cdp - Consolidated Data Point (cdp) is the long term storage format for data
  70  *       in the rrd database. Consolidated Data Points represent one or
  71  *       several primary data points collected along the time axis. The
  72  *       Consolidated Data Points (cdp) are stored in Round Robin Archives
  73  *       (rra).
  74  *
  75  * rra - Round Robin Archive (rra). This is the place where the
  76  *       consolidated data points (cdp) get stored. The data is
  77  *       organized in rows (row) and columns (col). The Round Robin
  78  *       Archive got its name from the method data is stored in
  79  *       there. An RRD database can contain several Round Robin
  80  *       Archives. Each Round Robin Archive can have a different row
  81  *       spacing along the time axis (pdp_cnt) and a different
  82  *       consolidation function (cf) used to build its consolidated
  83  *       data points (cdp).
  84  *
  85  * rra_st - RRA Start (rra_st). The moments (rra_st) in time where
  86  *       Consolidated Data Points (cdp) are added to an rra are
  87  *       defined by the moments where the number of seconds since
  88  *       1970-jan-1 modulo pdp_cnt*pdp_step equals zero (rra_st).
  89  *
  90  * row - Row (row). A row represent all consolidated data points (cdp)
  91  *       in a round robin archive who are of the same age.
  92  *
  93  * col - Column (col). A column (col) represent all consolidated
  94  *       data points (cdp) in a round robin archive (rra) who
  95  *       originated from the same data source (ds).
  96  *
  97  */
  98
  99 /****************************************************************************
 100  * POS 1: stat_head_t                           static header of the database
 101  ****************************************************************************/
 102
 103 typedef struct stat_head_t {
 104
 105     /* Data Base Identification Section ** */
 106     char      cookie[4];    /* RRD */
 107     char      version[5];   /* version of the format */
 108     double    float_cookie; /* is it the correct double
 109                              * representation ?  */
 110
 111     /* Data Base Structure Definition **** */
 112     unsigned long ds_cnt;   /* how many different ds provide
 113                              * input to the rrd */
 114     unsigned long rra_cnt;  /* how many rras will be maintained
 115                              * in the rrd */
 116     unsigned long pdp_step; /* pdp interval in seconds */
 117
 118     unival    par[10];  /* global parameters ... unused
 119                            at the moment */
 120 } stat_head_t;
 121
 122
 123 /****************************************************************************
 124  * POS 2: ds_def_t  (* ds_cnt)                        Data Source definitions
 125  ****************************************************************************/
 126
 127 enum dst_en { DST_COUNTER = 0,  /* data source types available */
 128     DST_ABSOLUTE,
 129     DST_GAUGE,
 130     DST_DERIVE,
 131     DST_CDEF
 132 };
 133
 134 enum ds_param_en { DS_mrhb_cnt = 0, /* minimum required heartbeat. A
 135                                      * data source must provide input at
 136                                      * least every ds_mrhb seconds,
 137                                      * otherwise it is regarded dead and
 138                                      * will be set to UNKNOWN */
 139     DS_min_val,         /* the processed input of a ds must */
 140     DS_max_val,         /* be between max_val and min_val
 141                          * both can be set to UNKNOWN if you
 142                          * do not care. Data outside the limits
 143                          * set to UNKNOWN */
 144     DS_cdef = DS_mrhb_cnt
 145 };                      /* pointer to encoded rpn
 146                          * expression only applies to DST_CDEF */
 147
 148 /* The magic number here is one less than DS_NAM_SIZE */
 149 #define DS_NAM_FMT    "%19[a-zA-Z0-9_-]"
 150 #define DS_NAM_SIZE   20
 151
 152 #define DST_FMT    "%19[A-Z]"
 153 #define DST_SIZE   20
 154
 155 typedef struct ds_def_t {
 156     char      ds_nam[DS_NAM_SIZE];  /* Name of the data source (null terminated) */
 157     char      dst[DST_SIZE];    /* Type of data source (null terminated) */
 158     unival    par[10];  /* index of this array see ds_param_en */
 159 } ds_def_t;
 160
 161 /****************************************************************************
 162  * POS 3: rra_def_t ( *  rra_cnt)         one for each store to be maintained
 163  ****************************************************************************/
 164 enum cf_en { CF_AVERAGE = 0,    /* data consolidation functions */
 165     CF_MINIMUM,
 166     CF_MAXIMUM,
 167     CF_LAST,
 168     CF_HWPREDICT,
 169     /* An array of predictions using the seasonal
 170      * Holt-Winters algorithm. Requires an RRA of type
 171      * CF_SEASONAL for this data source. */
 172     CF_SEASONAL,
 173     /* An array of seasonal effects. Requires an RRA of
 174      * type CF_HWPREDICT for this data source. */
 175     CF_DEVPREDICT,
 176     /* An array of deviation predictions based upon
 177      * smoothed seasonal deviations. Requires an RRA of
 178      * type CF_DEVSEASONAL for this data source. */
 179     CF_DEVSEASONAL,
 180     /* An array of smoothed seasonal deviations. Requires
 181      * an RRA of type CF_HWPREDICT for this data source.
 182      * */
 183     CF_FAILURES,
 184     /* HWPREDICT that follows a moving baseline */
 185     CF_MHWPREDICT
 186         /* new entries must come last !!! */
 187 };
 188
 189                        /* A binary array of failure indicators: 1 indicates
 190                         * that the number of violations in the prescribed
 191                         * window exceeded the prescribed threshold. */
 192
 193 #define MAX_RRA_PAR_EN 10
 194 enum rra_par_en { RRA_cdp_xff_val = 0,  /* what part of the consolidated
 195                                          * datapoint must be known, to produce a
 196                                          * valid entry in the rra */
 197     /* CF_HWPREDICT: */
 198     RRA_hw_alpha = 1,
 199     /* exponential smoothing parameter for the intercept in
 200      * the Holt-Winters prediction algorithm. */
 201     RRA_hw_beta = 2,
 202     /* exponential smoothing parameter for the slope in
 203      * the Holt-Winters prediction algorithm. */
 204
 205     RRA_dependent_rra_idx = 3,
 206     /* For CF_HWPREDICT: index of the RRA with the seasonal
 207      * effects of the Holt-Winters algorithm (of type
 208      * CF_SEASONAL).
 209      * For CF_DEVPREDICT: index of the RRA with the seasonal
 210      * deviation predictions (of type CF_DEVSEASONAL).
 211      * For CF_SEASONAL: index of the RRA with the Holt-Winters
 212      * intercept and slope coefficient (of type CF_HWPREDICT).
 213      * For CF_DEVSEASONAL: index of the RRA with the
 214      * Holt-Winters prediction (of type CF_HWPREDICT).
 215      * For CF_FAILURES: index of the CF_DEVSEASONAL array.
 216      * */
 217
 218     /* CF_SEASONAL and CF_DEVSEASONAL: */
 219     RRA_seasonal_gamma = 1,
 220     /* exponential smoothing parameter for seasonal effects. */
 221
 222     RRA_seasonal_smoothing_window = 2,
 223     /* fraction of the season to include in the running average
 224      * smoother */
 225
 226     /* RRA_dependent_rra_idx = 3, */
 227
 228     RRA_seasonal_smooth_idx = 4,
 229     /* an integer between 0 and row_count - 1 which
 230      * is index in the seasonal cycle for applying
 231      * the period smoother. */
 232
 233     /* CF_FAILURES: */
 234     RRA_delta_pos = 1,  /* confidence bound scaling parameters */
 235     RRA_delta_neg = 2,
 236     /* RRA_dependent_rra_idx = 3, */
 237     RRA_window_len = 4,
 238     RRA_failure_threshold = 5,
 239     /* For CF_FAILURES, number of violations within the last
 240      * window required to mark a failure. */
 241 };
 242
 243                     /* For CF_FAILURES, the length of the window for measuring
 244                      * failures. */
 245
 246 #define CF_NAM_FMT    "%19[A-Z]"
 247 #define CF_NAM_SIZE   20
 248
 249 typedef struct rra_def_t {
 250     char      cf_nam[CF_NAM_SIZE];  /* consolidation function (null term) */
 251     unsigned long row_cnt;  /* number of entries in the store */
 252     unsigned long pdp_cnt;  /* how many primary data points are
 253                              * required for a consolidated data
 254                              * point?*/
 255     unival    par[MAX_RRA_PAR_EN];  /* index see rra_param_en */
 256
 257 } rra_def_t;
 258
 259
 260 /****************************************************************************
 261  ****************************************************************************
 262  ****************************************************************************
 263  * LIVE PART OF THE HEADER. THIS WILL BE WRITTEN ON EVERY UPDATE         *
 264  ****************************************************************************
 265  ****************************************************************************
 266  ****************************************************************************/
 267 /****************************************************************************
 268  * POS 4: live_head_t
 269  ****************************************************************************/
 270
 271 typedef struct live_head_t {
 272     time_t    last_up;  /* when was rrd last updated */
 273     long      last_up_usec; /* micro seconds part of the
 274                                update timestamp. Always >= 0 */
 275 } live_head_t;
 276
 277
 278 /****************************************************************************
 279  * POS 5: pdp_prep_t  (* ds_cnt)                     here we prepare the pdps
 280  ****************************************************************************/
 281 #define LAST_DS_LEN 30  /* DO NOT CHANGE THIS ... */
 282
 283 enum pdp_par_en { PDP_unkn_sec_cnt = 0, /* how many seconds of the current
 284                                          * pdp value is unknown data? */
 285
 286     PDP_val
 287 };                      /* current value of the pdp.
 288                            this depends on dst */
 289
 290 typedef struct pdp_prep_t {
 291     char      last_ds[LAST_DS_LEN]; /* the last reading from the data
 292                                      * source.  this is stored in ASCII
 293                                      * to cater for very large counters
 294                                      * we might encounter in connection
 295                                      * with SNMP. */
 296     unival    scratch[10];  /* contents according to pdp_par_en */
 297 } pdp_prep_t;
 298
 299 /* data is passed from pdp to cdp when seconds since epoch modulo pdp_step == 0
 300    obviously the updates do not occur at these times only. Especially does the
 301    format allow for updates to occur at different times for each data source.
 302    The rules which makes this work is as follows:
 303
 304    * DS updates may only occur at ever increasing points in time
 305    * When any DS update arrives after a cdp update time, the *previous*
 306      update cycle gets executed. All pdps are transfered to cdps and the
 307      cdps feed the rras where necessary. Only then the new DS value
 308      is loaded into the PDP.                                                   */
 309
 310
 311 /****************************************************************************
 312  * POS 6: cdp_prep_t (* rra_cnt * ds_cnt )      data prep area for cdp values
 313  ****************************************************************************/
 314 #define MAX_CDP_PAR_EN 10
 315 #define MAX_CDP_FAILURES_IDX 8
 316 /* max CDP scratch entries avail to record violations for a FAILURES RRA */
 317 #define MAX_FAILURES_WINDOW_LEN 28
 318 enum cdp_par_en { CDP_val = 0,
 319     /* the base_interval is always an
 320      * average */
 321     CDP_unkn_pdp_cnt,
 322     /* how many unknown pdp were
 323      * integrated. This and the cdp_xff
 324      * will decide if this is going to
 325      * be a UNKNOWN or a valid value */
 326     CDP_hw_intercept,
 327     /* Current intercept coefficient for the Holt-Winters
 328      * prediction algorithm. */
 329     CDP_hw_last_intercept,
 330     /* Last iteration intercept coefficient for the Holt-Winters
 331      * prediction algorihtm. */
 332     CDP_hw_slope,
 333     /* Current slope coefficient for the Holt-Winters
 334      * prediction algorithm. */
 335     CDP_hw_last_slope,
 336     /* Last iteration slope coeffient. */
 337     CDP_null_count,
 338     /* Number of sequential Unknown (DNAN) values + 1 preceding
 339      * the current prediction.
 340      * */
 341     CDP_last_null_count,
 342     /* Last iteration count of Unknown (DNAN) values. */
 343     CDP_primary_val = 8,
 344     /* optimization for bulk updates: the value of the first CDP
 345      * value to be written in the bulk update. */
 346     CDP_secondary_val = 9,
 347     /* optimization for bulk updates: the value of subsequent
 348      * CDP values to be written in the bulk update. */
 349     CDP_hw_seasonal = CDP_hw_intercept,
 350     /* Current seasonal coefficient for the Holt-Winters
 351      * prediction algorithm. This is stored in CDP prep to avoid
 352      * redundant seek operations. */
 353     CDP_hw_last_seasonal = CDP_hw_last_intercept,
 354     /* Last iteration seasonal coeffient. */
 355     CDP_seasonal_deviation = CDP_hw_intercept,
 356     CDP_last_seasonal_deviation = CDP_hw_last_intercept,
 357     CDP_init_seasonal = CDP_null_count
 358 };
 359
 360                    /* init_seasonal is a flag which when > 0, forces smoothing updates
 361                     * to occur when rra_ptr.cur_row == 0 */
 362
 363 typedef struct cdp_prep_t {
 364     unival    scratch[MAX_CDP_PAR_EN];
 365     /* contents according to cdp_par_en *
 366      * init state should be NAN */
 367
 368 } cdp_prep_t;
 369
 370 /****************************************************************************
 371  * POS 7: rra_ptr_t (* rra_cnt)       pointers to the current row in each rra
 372  ****************************************************************************/
 373
 374 typedef struct rra_ptr_t {
 375     unsigned long cur_row;  /* current row in the rra */
 376 } rra_ptr_t;
 377
 378
 379 /****************************************************************************
 380  ****************************************************************************
 381  * One single struct to hold all the others. For convenience.
 382  ****************************************************************************
 383  ****************************************************************************/
 384 typedef struct rrd_t {
 385     stat_head_t *stat_head; /* the static header */
 386     ds_def_t *ds_def;   /* list of data source definitions */
 387     rra_def_t *rra_def; /* list of round robin archive def */
 388     live_head_t *live_head;
 389     pdp_prep_t *pdp_prep;   /* pdp data prep area */
 390     cdp_prep_t *cdp_prep;   /* cdp prep area */
 391     rra_ptr_t *rra_ptr; /* list of rra pointers */
 392     rrd_value_t *rrd_value; /* list of rrd values */
 393 } rrd_t;
 394
 395 /****************************************************************************
 396  ****************************************************************************
 397  * AFTER the header section we have the DATA STORAGE AREA it is made up from
 398  * Consolidated Data Points organized in Round Robin Archives.
 399  ****************************************************************************
 400  ****************************************************************************
 401
 402  *RRA 0
 403  (0,0) .................... ( ds_cnt -1 , 0)
 404  .
 405  .
 406  .
 407  (0, row_cnt -1) ... (ds_cnt -1, row_cnt -1)
 408
 409  *RRA 1
 410  *RRA 2
 411
 412  *RRA rra_cnt -1
 413
 414  ****************************************************************************/
 415
 416
 417 #endif