2 * This file is part of RRDtool.
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.
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.
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
19 /*****************************************************************************
20 * RRDtool 1.0.37 Copyright Tobias Oetiker, 1997, 1998, 1999
21 *****************************************************************************
22 * rrd_format.h RRD Database Format header
23 *****************************************************************************/
30 /*****************************************************************************
31 * put this in your /usr/lib/magic file (/etc/magic on HPUX)
33 * # rrd database format
34 * 0 string RRD\0 rrd file
35 * >5 string >\0 version '%s'
37 *****************************************************************************/
39 #define RRD_COOKIE "RRD"
40 #define RRD_VERSION "0001"
41 #define FLOAT_COOKIE 8.642135E130
44 #define DNAN ((double)fmod(0.0,0.0))
45 #define DINF ((double)log(0.0))
48 #define DNAN ((double)(0.0/0.0)) /* we use a DNAN to
49 * represent the UNKNOWN
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 ...
57 typedef union unival {
63 /****************************************************************************
64 * The RRD Database Structure
65 * ---------------------------
67 * In oder to properly describe the database structure lets define a few
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.
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
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).
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
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.
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
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
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).
117 * row - Row (row). A row represent all consolidated data points (cdp)
118 * in a round robin archive who are of the same age.
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).
126 /****************************************************************************
127 * POS 1: stat_head_t static header of the database
128 ****************************************************************************/
130 typedef struct stat_head_t {
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 ? */
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
143 unsigned long pdp_step; /* pdp interval in seconds */
145 unival par[10]; /* global parameters ... unused
150 /****************************************************************************
151 * POS 2: ds_def_t (* ds_cnt) Data Source definitions
152 ****************************************************************************/
154 enum dst_en { DST_COUNTER=0, /* data source types available */
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
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
174 #define DST_FMT "%19[A-Z]"
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 */
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 */
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 */
195 #define CF_NAM_FMT "%19[A-Z]"
196 #define CF_NAM_SIZE 20
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
204 unival par[10]; /* index see rra_param_en */
209 /****************************************************************************
210 ****************************************************************************
211 ****************************************************************************
212 * LIVE PART OF THE HEADER. THIS WILL BE WRITTEN ON EVERY UPDATE *
213 ****************************************************************************
214 ****************************************************************************
215 ****************************************************************************/
216 /****************************************************************************
218 ****************************************************************************/
220 typedef struct live_head_t {
221 time_t last_up; /* when was rrd last updated */
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 ... */
230 enum pdp_par_en { PDP_unkn_sec_cnt=0, /* how many seconds of the current
231 * pdp value is unknown data? */
233 PDP_val}; /* current value of the pdp.
234 this depends on dst */
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
242 unival scratch[10]; /* contents according to pdp_par_en */
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:
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. */
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
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 */
267 typedef struct cdp_prep_t{
268 unival scratch[10]; /* contents according to cdp_par_en *
269 * init state should be NAN */
273 /****************************************************************************
274 * POS 7: rra_ptr_t (* rra_cnt) pointers to the current row in each rra
275 ****************************************************************************/
277 typedef struct rra_ptr_t {
278 unsigned long cur_row; /* current row in the rra*/
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 */
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 ****************************************************************************
306 (0,0) .................... ( ds_cnt -1 , 0)
310 (0, row_cnt -1) ... (ds_cnt -1, row_cnt -1)
317 ****************************************************************************/