bindings/python/rrd_format.h

   1 /*
   2  *  This file is part of RRDtool.
   3  *
   4  *  RRDtool is free software; you can redistribute it and/or modify
   5  *  it under the terms of the GNU General Public License as published
   6  *  by the Free Software Foundation; either version 2 of the License, or
   7  *  (at your option) any later version.
   8  *
   9  *  RRDtool is distributed in the hope that it will be useful,
  10  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  *  GNU General Public License for more details.
  13  *
  14  *  You should have received a copy of the GNU General Public License
  15  *  along with Foobar; if not, write to the Free Software
  16  *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  17  */
  18
  19 /*****************************************************************************
  20  * RRDtool 1.0.37  Copyright Tobias Oetiker, 1997, 1998, 1999
  21  *****************************************************************************
  22  * rrd_format.h  RRD Database Format header
  23  *****************************************************************************/
  24
  25 #ifndef _RRD_FORMAT_H
  26 #define _RRD_FORMAT_H
  27
  28 #include "rrd.h"
  29
  30 /*****************************************************************************
  31  * put this in your /usr/lib/magic file (/etc/magic on HPUX)
  32  *
  33  *  # rrd database format
  34  *  0       string          RRD\0           rrd file
  35  *  >5      string          >\0             version '%s'
  36  *
  37  *****************************************************************************/
  38
  39 #define RRD_COOKIE    "RRD"
  40 #define RRD_VERSION   "0001"
  41 #define FLOAT_COOKIE  8.642135E130
  42
  43 #if defined(WIN32)
  44 #define DNAN          ((double)fmod(0.0,0.0))
  45 #define DINF          ((double)log(0.0))
  46 #else
  47
  48 #define DNAN          ((double)(0.0/0.0))     /* we use a DNAN to
  49                                                * represent the UNKNOWN
  50                                                * */
  51 #define DINF          ((double)(1.0/0.0))     /* we use a DINF to
  52                                                * represent a value at the upper or
  53                                                * lower border of the graph ...
  54                                                * */
  55 #endif
  56
  57 typedef union unival {
  58     unsigned long u_cnt;
  59     rrd_value_t   u_val;
  60 } unival;
  61
  62
  63 /****************************************************************************
  64  * The RRD Database Structure
  65  * ---------------------------
  66  *
  67  * In oder to properly describe the database structure lets define a few
  68  * new words:
  69  *
  70  * ds - Data Source (ds) providing input to the database. A Data Source (ds)
  71  *       can be a traffic counter, a temperature, the number of users logged
  72  *       into a system. The rrd database format can handle the input of
  73  *       several Data Sources (ds) in a singe database.
  74  *
  75  * dst - Data Source Type (dst). The Data Source Type (dst) defines the rules
  76  *       applied to Build Primary Data Points from the input provided by the
  77  *       data sources (ds).
  78  *
  79  * pdp - Primary Data Point (pdp). After the database has accepted the
  80  *       input from the data sources (ds). It starts building Primary
  81  *       Data Points (pdp) from the data. Primary Data Points (pdp)
  82  *       are evenly spaced along the time axis (pdp_step). The values
  83  *       of the Primary Data Points are calculated from the values of
  84  *       the data source (ds) and the exact time these values were
  85  *       provided by the data source (ds).
  86  *
  87  * pdp_st - PDP Start (pdp_st). The moments (pdp_st) in time where
  88  *       these steps occur are defined by the moments where the
  89  *       number of seconds since 1970-jan-1 modulo pdp_step equals
  90  *       zero (pdp_st).
  91  *
  92  * cf -  Consolidation Function (cf). An arbitrary Consolidation Function (cf)
  93  *       (averaging, min, max) is applied to the primary data points (pdp) to
  94  *       calculate the consolidated data point.
  95  *
  96  * cdp - Consolidated Data Point (cdp) is the long term storage format for data
  97  *       in the rrd database. Consolidated Data Points represent one or
  98  *       several primary data points collected along the time axis. The
  99  *       Consolidated Data Points (cdp) are stored in Round Robin Archives
 100  *       (rra).
 101  *
 102  * rra - Round Robin Archive (rra). This is the place where the
 103  *       consolidated data points (cdp) get stored. The data is
 104  *       organized in rows (row) and columns (col). The Round Robin
 105  *       Archive got its name from the method data is stored in
 106  *       there. An RRD database can contain several Round Robin
 107  *       Archives. Each Round Robin Archive can have a different row
 108  *       spacing along the time axis (pdp_cnt) and a different
 109  *       consolidation function (cf) used to build its consolidated
 110  *       data points (cdp).
 111  *
 112  * rra_st - RRA Start (rra_st). The moments (rra_st) in time where
 113  *       Consolidated Data Points (cdp) are added to an rra are
 114  *       defined by the moments where the number of seconds since
 115  *       1970-jan-1 modulo pdp_cnt*pdp_step equals zero (rra_st).
 116  *
 117  * row - Row (row). A row represent all consolidated data points (cdp)
 118  *       in a round robin archive who are of the same age.
 119  *
 120  * col - Column (col). A column (col) represent all consolidated
 121  *       data points (cdp) in a round robin archive (rra) who
 122  *       originated from the same data source (ds).
 123  *
 124  */
 125
 126 /****************************************************************************
 127  * POS 1: stat_head_t                           static header of the database
 128  ****************************************************************************/
 129
 130 typedef struct stat_head_t {
 131
 132     /* Data Base Identification Section ***/
 133     char             cookie[4];          /* RRD */
 134     char             version[5];         /* version of the format */
 135     double           float_cookie;       /* is it the correct double
 136                                           * representation ?  */
 137
 138     /* Data Base Structure Definition *****/
 139     unsigned long    ds_cnt;             /* how many different ds provide
 140                                           * input to the rrd */
 141     unsigned long    rra_cnt;            /* how many rras will be maintained
 142                                           * in the rrd */
 143     unsigned long    pdp_step;           /* pdp interval in seconds */
 144
 145     unival           par[10];            /* global parameters ... unused
 146                                             at the moment */
 147 } stat_head_t;
 148
 149
 150 /****************************************************************************
 151  * POS 2: ds_def_t  (* ds_cnt)                        Data Source definitions
 152  ****************************************************************************/
 153
 154 enum dst_en          { DST_COUNTER=0,     /* data source types available */
 155                        DST_ABSOLUTE,
 156                        DST_GAUGE,
 157                        DST_DERIVE};
 158
 159 enum ds_param_en {   DS_mrhb_cnt=0,       /* minimum required heartbeat. A
 160                                            * data source must provide input at
 161                                            * least every ds_mrhb seconds,
 162                                            * otherwise it is regarded dead and
 163                                            * will be set to UNKNOWN */
 164                      DS_min_val,          /* the processed input of a ds must */
 165                      DS_max_val };        /* be between max_val and min_val
 166                                            * both can be set to UNKNOWN if you
 167                                            * do not care. Data outside the limits
 168                                            * set to UNKNOWN */
 169
 170 /* The magic number here is one less than DS_NAM_SIZE */
 171 #define DS_NAM_FMT    "%19[a-zA-Z0-9_-]"
 172 #define DS_NAM_SIZE   20
 173
 174 #define DST_FMT    "%19[A-Z]"
 175 #define DST_SIZE   20
 176
 177 typedef struct ds_def_t {
 178     char             ds_nam[DS_NAM_SIZE]; /* Name of the data source (null terminated)*/
 179     char             dst[DST_SIZE];       /* Type of data source (null terminated)*/
 180     unival           par[10];             /* index of this array see ds_param_en */
 181 } ds_def_t;
 182
 183 /****************************************************************************
 184  * POS 3: rra_def_t ( *  rra_cnt)         one for each store to be maintained
 185  ****************************************************************************/
 186 enum cf_en           { CF_AVERAGE=0,     /* data consolidation functions */
 187                        CF_MINIMUM,
 188                        CF_MAXIMUM,
 189                        CF_LAST};
 190
 191 enum rra_par_en {   RRA_cdp_xff_val=0};   /* what part of the consolidated
 192                                             datapoint may be unknown, while
 193                                             still a valid entry in goes into the rra */
 194
 195 #define CF_NAM_FMT    "%19[A-Z]"
 196 #define CF_NAM_SIZE   20
 197
 198 typedef struct rra_def_t {
 199     char             cf_nam[CF_NAM_SIZE];/* consolidation function (null term) */
 200     unsigned long    row_cnt;            /* number of entries in the store */
 201     unsigned long    pdp_cnt;            /* how many primary data points are
 202                                           * required for a consolidated data
 203                                           * point?*/
 204     unival           par[10];            /* index see rra_param_en */
 205
 206 } rra_def_t;
 207
 208
 209 /****************************************************************************
 210  ****************************************************************************
 211  ****************************************************************************
 212  * LIVE PART OF THE HEADER. THIS WILL BE WRITTEN ON EVERY UPDATE         *
 213  ****************************************************************************
 214  ****************************************************************************
 215  ****************************************************************************/
 216 /****************************************************************************
 217  * POS 4: live_head_t
 218  ****************************************************************************/
 219
 220 typedef struct live_head_t {
 221     time_t           last_up;            /* when was rrd last updated */
 222 } live_head_t;
 223
 224
 225 /****************************************************************************
 226  * POS 5: pdp_prep_t  (* ds_cnt)                     here we prepare the pdps
 227  ****************************************************************************/
 228 #define LAST_DS_LEN 30 /* DO NOT CHANGE THIS ... */
 229
 230 enum pdp_par_en {   PDP_unkn_sec_cnt=0,  /* how many seconds of the current
 231                                           * pdp value is unknown data? */
 232
 233                     PDP_val};            /* current value of the pdp.
 234                                             this depends on dst */
 235
 236 typedef struct pdp_prep_t{
 237     char last_ds[LAST_DS_LEN];           /* the last reading from the data
 238                                           * source.  this is stored in ASCII
 239                                           * to cater for very large counters
 240                                           * we might encounter in connection
 241                                           * with SNMP. */
 242     unival          scratch[10];         /* contents according to pdp_par_en */
 243 } pdp_prep_t;
 244
 245 /* data is passed from pdp to cdp when seconds since epoch modulo pdp_step == 0
 246    obviously the updates do not occur at these times only. Especially does the
 247    format allow for updates to occur at different times for each data source.
 248    The rules which makes this work is as follows:
 249
 250    * DS updates may only occur at ever increasing points in time
 251    * When any DS update arrives after a cdp update time, the *previous*
 252      update cycle gets executed. All pdps are transfered to cdps and the
 253      cdps feed the rras where necessary. Only then the new DS value
 254      is loaded into the PDP.                                                   */
 255
 256
 257 /****************************************************************************
 258  * POS 6: cdp_prep_t (* rra_cnt * ds_cnt )      data prep area for cdp values
 259  ****************************************************************************/
 260 enum cdp_par_en {  CDP_val=0,          /* the base_interval is always an
 261                                           * average */
 262                    CDP_unkn_pdp_cnt };       /* how many unknown pdp were
 263                                           * integrated. This and the cdp_xff
 264                                             will decide if this is going to
 265                                             be a UNKNOWN or a valid value */
 266
 267 typedef struct cdp_prep_t{
 268     unival         scratch[10];          /* contents according to cdp_par_en *
 269                                           * init state should be NAN */
 270
 271 } cdp_prep_t;
 272
 273 /****************************************************************************
 274  * POS 7: rra_ptr_t (* rra_cnt)       pointers to the current row in each rra
 275  ****************************************************************************/
 276
 277 typedef struct rra_ptr_t {
 278     unsigned long    cur_row;            /* current row in the rra*/
 279 } rra_ptr_t;
 280
 281
 282 /****************************************************************************
 283  ****************************************************************************
 284  * One single struct to hold all the others. For convenience.
 285  ****************************************************************************
 286  ****************************************************************************/
 287 typedef struct rrd_t {
 288     stat_head_t      *stat_head;          /* the static header */
 289     ds_def_t         *ds_def;             /* list of data source definitions */
 290     rra_def_t        *rra_def;            /* list of round robin archive def */
 291     live_head_t      *live_head;
 292     pdp_prep_t       *pdp_prep;           /* pdp data prep area */
 293     cdp_prep_t       *cdp_prep;           /* cdp prep area */
 294     rra_ptr_t        *rra_ptr;            /* list of rra pointers */
 295     rrd_value_t      *rrd_value;          /* list of rrd values */
 296 } rrd_t;
 297
 298 /****************************************************************************
 299  ****************************************************************************
 300  * AFTER the header section we have the DATA STORAGE AREA it is made up from
 301  * Consolidated Data Points organized in Round Robin Archives.
 302  ****************************************************************************
 303  ****************************************************************************
 304
 305  *RRA 0
 306  (0,0) .................... ( ds_cnt -1 , 0)
 307  .
 308  .
 309  .
 310  (0, row_cnt -1) ... (ds_cnt -1, row_cnt -1)
 311
 312  *RRA 1
 313  *RRA 2
 314
 315  *RRA rra_cnt -1
 316
 317  ****************************************************************************/
 318
 319
 320 #endif
 321
 322
 323
 324