src/rrd_format.h

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