![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/rrdcreate.txt b/doc/rrdcreate.txt
index 3d2560ce120f5cf46bd109d8ced96c5a9d0c1df8..eaa70c156b29c7826bfb9f998fbbac1678072e31 100644 (file)
--- a/doc/rrdcreate.txt
+++ b/doc/rrdcreate.txt
with _\b*_\bU_\bN_\bK_\bN_\bO_\bW_\bN_\b* data.
_\bf_\bi_\bl_\be_\bn_\ba_\bm_\be
- The name of the R\bRR\bRD\bD you want to create. R\bRR\bRD\bD files should end
- with the extension _\b._\br_\br_\bd. However, R\bRR\bRD\bDt\bto\boo\bol\bl will accept any file-
- name.
+ The name of the R\bRR\bRD\bD you want to create. R\bRR\bRD\bD files should end with
+ the extension _\b._\br_\br_\bd. However, R\bRR\bRD\bDt\bto\boo\bol\bl will accept any filename.
-\b--\b-s\bst\bta\bar\brt\bt|-\b-b\bb _\bs_\bt_\ba_\br_\bt _\bt_\bi_\bm_\be (default: now - 10s)
- Specifies the time in seconds since 1970-01-01 UTC when the
- first value should be added to the R\bRR\bRD\bD. R\bRR\bRD\bDt\bto\boo\bol\bl will not accept
- any data timed before or at the time specified.
+ Specifies the time in seconds since 1970-01-01 UTC when the first
+ value should be added to the R\bRR\bRD\bD. R\bRR\bRD\bDt\bto\boo\bol\bl will not accept any data
+ timed before or at the time specified.
- See also AT-STYLE TIME SPECIFICATION section in the _\br_\br_\bd_\bf_\be_\bt_\bc_\bh
- documentation for other ways to specify time.
+ See also AT-STYLE TIME SPECIFICATION section in the _\br_\br_\bd_\bf_\be_\bt_\bc_\bh docu-
+ mentation for other ways to specify time.
-\b--\b-s\bst\bte\bep\bp|-\b-s\bs _\bs_\bt_\be_\bp (default: 300 seconds)
- Specifies the base interval in seconds with which data will be
- fed into the R\bRR\bRD\bD.
+ Specifies the base interval in seconds with which data will be fed
+ into the R\bRR\bRD\bD.
D\bDS\bS:\b:_\bd_\bs_\b-_\bn_\ba_\bm_\be:\b:_\bD_\bS_\bT:\b:_\bd_\bs_\bt _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs
- A single R\bRR\bRD\bD can accept input from several data sources (D\bDS\bS),
- for example incoming and outgoing traffic on a specific commu-
- nication line. With the D\bDS\bS configuration option you must define
- some basic properties of each data source you want to store in
- the R\bRR\bRD\bD.
-
- _\bd_\bs_\b-_\bn_\ba_\bm_\be is the name you will use to reference this particular
- data source from an R\bRR\bRD\bD. A _\bd_\bs_\b-_\bn_\ba_\bm_\be must be 1 to 19 characters
- long in the characters [a-zA-Z0-9_].
-
- _\bD_\bS_\bT defines the Data Source Type. The remaining arguments of a
- data source entry depend on the data source type. For GAUGE,
- COUNTER, DERIVE, and ABSOLUTE the format for a data source
- entry is:
-
- D\bDS\bS:\b:_\bd_\bs_\b-_\bn_\ba_\bm_\be:\b:_\bG_\bA_\bU_\bG_\bE _\b| _\bC_\bO_\bU_\bN_\bT_\bE_\bR _\b| _\bD_\bE_\bR_\bI_\bV_\bE _\b| _\bA_\bB_\bS_\bO_\bL_\bU_\bT_\bE:\b:_\bh_\be_\ba_\br_\bt_\b-
- _\bb_\be_\ba_\bt:\b:_\bm_\bi_\bn:\b:_\bm_\ba_\bx
-
- For COMPUTE data sources, the format is:
-
- D\bDS\bS:\b:_\bd_\bs_\b-_\bn_\ba_\bm_\be:\b:_\bC_\bO_\bM_\bP_\bU_\bT_\bE:\b:_\br_\bp_\bn_\b-_\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn
-
- In order to decide which data source type to use, review the
- definitions that follow. Also consult the section on "HOW TO
- MEASURE" for further insight.
-
- G\bGA\bAU\bUG\bGE\bE
- is for things like temperatures or number of people in a
- room or the value of a RedHat share.
-
- C\bCO\bOU\bUN\bNT\bTE\bER\bR
- is for continuous incrementing counters like the ifInOctets
- counter in a router. The C\bCO\bOU\bUN\bNT\bTE\bER\bR data source assumes that
- the counter never decreases, except when a counter over-
- flows. The update function takes the overflow into
- account. The counter is stored as a per-second rate. When
- the counter overflows, RRDtool checks if the overflow hap-
- pened at the 32bit or 64bit border and acts accordingly by
- adding an appropriate value to the result.
-
- D\bDE\bER\bRI\bIV\bVE\bE
- will store the derivative of the line going from the last
- to the current value of the data source. This can be useful
- for gauges, for example, to measure the rate of people
- entering or leaving a room. Internally, derive works
- exactly like COUNTER but without overflow checks. So if
- your counter does not reset at 32 or 64 bit you might want
- to use DERIVE and combine it with a MIN value of 0.
-
- NOTE on COUNTER vs DERIVE
- by Don Baarda <don.baarda@baesystems.com>
-
- If you cannot tolerate ever mistaking the occasional
- counter reset for a legitimate counter wrap, and would
- prefer "Unknowns" for all legitimate counter wraps and
- resets, always use DERIVE with min=0. Otherwise, using
- COUNTER with a suitable max will return correct values
- for all legitimate counter wraps, mark some counter
- resets as "Unknown", but can mistake some counter
- resets for a legitimate counter wrap.
-
- For a 5 minute step and 32-bit counter, the probability
- of mistaking a counter reset for a legitimate wrap is
- arguably about 0.8% per 1Mbps of maximum bandwidth.
- Note that this equates to 80% for 100Mbps interfaces,
- so for high bandwidth interfaces and a 32bit counter,
- DERIVE with min=0 is probably preferable. If you are
- using a 64bit counter, just about any max setting will
- eliminate the possibility of mistaking a reset for a
- counter wrap.
-
- A\bAB\bBS\bSO\bOL\bLU\bUT\bTE\bE
- is for counters which get reset upon reading. This is used
- for fast counters which tend to overflow. So instead of
- reading them normally you reset them after every read to
- make sure you have a maximum time available before the next
- overflow. Another usage is for things you count like number
- of messages since the last update.
-
- C\bCO\bOM\bMP\bPU\bUT\bTE\bE
- is for storing the result of a formula applied to other
- data sources in the R\bRR\bRD\bD. This data source is not supplied a
- value on update, but rather its Primary Data Points (PDPs)
- are computed from the PDPs of the data sources according to
- the rpn-expression that defines the formula. Consolidation
- functions are then applied normally to the PDPs of the COM-
- PUTE data source (that is the rpn-expression is only
- applied to generate PDPs). In database software, such data
- sets are referred to as "virtual" or "computed" columns.
-
- _\bh_\be_\ba_\br_\bt_\bb_\be_\ba_\bt defines the maximum number of seconds that may pass
- between two updates of this data source before the value of the
- data source is assumed to be _\b*_\bU_\bN_\bK_\bN_\bO_\bW_\bN_\b*.
-
- _\bm_\bi_\bn and _\bm_\ba_\bx define the expected range values for data supplied
- by a data source. If _\bm_\bi_\bn and/or _\bm_\ba_\bx any value outside the
- defined range will be regarded as _\b*_\bU_\bN_\bK_\bN_\bO_\bW_\bN_\b*. If you do not know
- or care about min and max, set them to U for unknown. Note that
- min and max always refer to the processed values of the DS. For
- a traffic-C\bCO\bOU\bUN\bNT\bTE\bER\bR type DS this would be the maximum and minimum
- data-rate expected from the device.
-
- _\bI_\bf _\bi_\bn_\bf_\bo_\br_\bm_\ba_\bt_\bi_\bo_\bn _\bo_\bn _\bm_\bi_\bn_\bi_\bm_\ba_\bl_\b/_\bm_\ba_\bx_\bi_\bm_\ba_\bl _\be_\bx_\bp_\be_\bc_\bt_\be_\bd _\bv_\ba_\bl_\bu_\be_\bs _\bi_\bs _\ba_\bv_\ba_\bi_\bl_\ba_\bb_\bl_\be_\b,
- _\ba_\bl_\bw_\ba_\by_\bs _\bs_\be_\bt _\bt_\bh_\be _\bm_\bi_\bn _\ba_\bn_\bd_\b/_\bo_\br _\bm_\ba_\bx _\bp_\br_\bo_\bp_\be_\br_\bt_\bi_\be_\bs_\b. _\bT_\bh_\bi_\bs _\bw_\bi_\bl_\bl _\bh_\be_\bl_\bp _\bR_\bR_\bD_\b-
- _\bt_\bo_\bo_\bl _\bi_\bn _\bd_\bo_\bi_\bn_\bg _\ba _\bs_\bi_\bm_\bp_\bl_\be _\bs_\ba_\bn_\bi_\bt_\by _\bc_\bh_\be_\bc_\bk _\bo_\bn _\bt_\bh_\be _\bd_\ba_\bt_\ba _\bs_\bu_\bp_\bp_\bl_\bi_\be_\bd _\bw_\bh_\be_\bn
- _\br_\bu_\bn_\bn_\bi_\bn_\bg _\bu_\bp_\bd_\ba_\bt_\be_\b.
-
- _\br_\bp_\bn_\b-_\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn defines the formula used to compute the PDPs of
- a COMPUTE data source from other data sources in the same
- <RRD>. It is similar to defining a C\bCD\bDE\bEF\bF argument for the graph
- command. Please refer to that manual page for a list and
- description of RPN operations supported. For COMPUTE data
- sources, the following RPN operations are not supported: COUNT,
- PREV, TIME, and LTIME. In addition, in defining the RPN expres-
- sion, the COMPUTE data source may only refer to the names of
- data source listed previously in the create command. This is
- similar to the restriction that C\bCD\bDE\bEF\bFs must refer only to D\bDE\bEF\bFs
- and C\bCD\bDE\bEF\bFs previously defined in the same graph command.
+ A single R\bRR\bRD\bD can accept input from several data sources (D\bDS\bS), for
+ example incoming and outgoing traffic on a specific communication
+ line. With the D\bDS\bS configuration option you must define some basic
+ properties of each data source you want to store in the R\bRR\bRD\bD.
+
+ _\bd_\bs_\b-_\bn_\ba_\bm_\be is the name you will use to reference this particular data
+ source from an R\bRR\bRD\bD. A _\bd_\bs_\b-_\bn_\ba_\bm_\be must be 1 to 19 characters long in
+ the characters [a-zA-Z0-9_].
+
+ _\bD_\bS_\bT defines the Data Source Type. The remaining arguments of a data
+ source entry depend on the data source type. For GAUGE, COUNTER,
+ DERIVE, and ABSOLUTE the format for a data source entry is:
+
+ D\bDS\bS:\b:_\bd_\bs_\b-_\bn_\ba_\bm_\be:\b:_\bG_\bA_\bU_\bG_\bE _\b| _\bC_\bO_\bU_\bN_\bT_\bE_\bR _\b| _\bD_\bE_\bR_\bI_\bV_\bE _\b| _\bA_\bB_\bS_\bO_\bL_\bU_\bT_\bE:\b:_\bh_\be_\ba_\br_\bt_\bb_\be_\ba_\bt:\b:_\bm_\bi_\bn:\b:_\bm_\ba_\bx
+
+ For COMPUTE data sources, the format is:
+
+ D\bDS\bS:\b:_\bd_\bs_\b-_\bn_\ba_\bm_\be:\b:_\bC_\bO_\bM_\bP_\bU_\bT_\bE:\b:_\br_\bp_\bn_\b-_\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn
+
+ In order to decide which data source type to use, review the defi-
+ nitions that follow. Also consult the section on "HOW TO MEASURE"
+ for further insight.
+
+ G\bGA\bAU\bUG\bGE\bE
+ is for things like temperatures or number of people in a room
+ or the value of a RedHat share.
+
+ C\bCO\bOU\bUN\bNT\bTE\bER\bR
+ is for continuous incrementing counters like the ifInOctets
+ counter in a router. The C\bCO\bOU\bUN\bNT\bTE\bER\bR data source assumes that the
+ counter never decreases, except when a counter overflows. The
+ update function takes the overflow into account. The counter
+ is stored as a per-second rate. When the counter overflows,
+ RRDtool checks if the overflow happened at the 32bit or 64bit
+ border and acts accordingly by adding an appropriate value to
+ the result.
+
+ D\bDE\bER\bRI\bIV\bVE\bE
+ will store the derivative of the line going from the last to
+ the current value of the data source. This can be useful for
+ gauges, for example, to measure the rate of people entering or
+ leaving a room. Internally, derive works exactly like COUNTER
+ but without overflow checks. So if your counter does not reset
+ at 32 or 64 bit you might want to use DERIVE and combine it
+ with a MIN value of 0.
+
+ NOTE on COUNTER vs DERIVE
+
+ by Don Baarda <don.baarda@baesystems.com>
+
+ If you cannot tolerate ever mistaking the occasional counter
+ reset for a legitimate counter wrap, and would prefer
+ "Unknowns" for all legitimate counter wraps and resets, always
+ use DERIVE with min=0. Otherwise, using COUNTER with a suitable
+ max will return correct values for all legitimate counter
+ wraps, mark some counter resets as "Unknown", but can mistake
+ some counter resets for a legitimate counter wrap.
+
+ For a 5 minute step and 32-bit counter, the probability of mis-
+ taking a counter reset for a legitimate wrap is arguably about
+ 0.8% per 1Mbps of maximum bandwidth. Note that this equates to
+ 80% for 100Mbps interfaces, so for high bandwidth interfaces
+ and a 32bit counter, DERIVE with min=0 is probably preferable.
+ If you are using a 64bit counter, just about any max setting
+ will eliminate the possibility of mistaking a reset for a
+ counter wrap.
+
+ A\bAB\bBS\bSO\bOL\bLU\bUT\bTE\bE
+ is for counters which get reset upon reading. This is used for
+ fast counters which tend to overflow. So instead of reading
+ them normally you reset them after every read to make sure you
+ have a maximum time available before the next overflow. Another
+ usage is for things you count like number of messages since the
+ last update.
+
+ C\bCO\bOM\bMP\bPU\bUT\bTE\bE
+ is for storing the result of a formula applied to other data
+ sources in the R\bRR\bRD\bD. This data source is not supplied a value on
+ update, but rather its Primary Data Points (PDPs) are computed
+ from the PDPs of the data sources according to the rpn-expres-
+ sion that defines the formula. Consolidation functions are then
+ applied normally to the PDPs of the COMPUTE data source (that
+ is the rpn-expression is only applied to generate PDPs). In
+ database software, such data sets are referred to as "virtual"
+ or "computed" columns.
+
+ _\bh_\be_\ba_\br_\bt_\bb_\be_\ba_\bt defines the maximum number of seconds that may pass
+ between two updates of this data source before the value of the
+ data source is assumed to be _\b*_\bU_\bN_\bK_\bN_\bO_\bW_\bN_\b*.
+
+ _\bm_\bi_\bn and _\bm_\ba_\bx define the expected range values for data supplied by a
+ data source. If _\bm_\bi_\bn and/or _\bm_\ba_\bx any value outside the defined range
+ will be regarded as _\b*_\bU_\bN_\bK_\bN_\bO_\bW_\bN_\b*. If you do not know or care about min
+ and max, set them to U for unknown. Note that min and max always
+ refer to the processed values of the DS. For a traffic-C\bCO\bOU\bUN\bNT\bTE\bER\bR type
+ DS this would be the maximum and minimum data-rate expected from
+ the device.
+
+ _\bI_\bf _\bi_\bn_\bf_\bo_\br_\bm_\ba_\bt_\bi_\bo_\bn _\bo_\bn _\bm_\bi_\bn_\bi_\bm_\ba_\bl_\b/_\bm_\ba_\bx_\bi_\bm_\ba_\bl _\be_\bx_\bp_\be_\bc_\bt_\be_\bd _\bv_\ba_\bl_\bu_\be_\bs _\bi_\bs _\ba_\bv_\ba_\bi_\bl_\ba_\bb_\bl_\be_\b,
+ _\ba_\bl_\bw_\ba_\by_\bs _\bs_\be_\bt _\bt_\bh_\be _\bm_\bi_\bn _\ba_\bn_\bd_\b/_\bo_\br _\bm_\ba_\bx _\bp_\br_\bo_\bp_\be_\br_\bt_\bi_\be_\bs_\b. _\bT_\bh_\bi_\bs _\bw_\bi_\bl_\bl _\bh_\be_\bl_\bp _\bR_\bR_\bD_\bt_\bo_\bo_\bl _\bi_\bn
+ _\bd_\bo_\bi_\bn_\bg _\ba _\bs_\bi_\bm_\bp_\bl_\be _\bs_\ba_\bn_\bi_\bt_\by _\bc_\bh_\be_\bc_\bk _\bo_\bn _\bt_\bh_\be _\bd_\ba_\bt_\ba _\bs_\bu_\bp_\bp_\bl_\bi_\be_\bd _\bw_\bh_\be_\bn _\br_\bu_\bn_\bn_\bi_\bn_\bg
+ _\bu_\bp_\bd_\ba_\bt_\be_\b.
+
+ _\br_\bp_\bn_\b-_\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn defines the formula used to compute the PDPs of a
+ COMPUTE data source from other data sources in the same <RRD>. It
+ is similar to defining a C\bCD\bDE\bEF\bF argument for the graph command.
+ Please refer to that manual page for a list and description of RPN
+ operations supported. For COMPUTE data sources, the following RPN
+ operations are not supported: COUNT, PREV, TIME, and LTIME. In
+ addition, in defining the RPN expression, the COMPUTE data source
+ may only refer to the names of data source listed previously in the
+ create command. This is similar to the restriction that C\bCD\bDE\bEF\bFs must
+ refer only to D\bDE\bEF\bFs and C\bCD\bDE\bEF\bFs previously defined in the same graph
+ command.
R\bRR\bRA\bA:\b:_\bC_\bF:\b:_\bc_\bf _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs
- The purpose of an R\bRR\bRD\bD is to store data in the round robin
- archives (R\bRR\bRA\bA). An archive consists of a number of data values
- or statistics for each of the defined data-sources (D\bDS\bS) and is
- defined with an R\bRR\bRA\bA line.
+ The purpose of an R\bRR\bRD\bD is to store data in the round robin archives
+ (R\bRR\bRA\bA). An archive consists of a number of data values or statistics
+ for each of the defined data-sources (D\bDS\bS) and is defined with an
+ R\bRR\bRA\bA line.
- When data is entered into an R\bRR\bRD\bD, it is first fit into time
- slots of the length defined with the -\b-s\bs option, thus becoming a
- _\bp_\br_\bi_\bm_\ba_\br_\by _\bd_\ba_\bt_\ba _\bp_\bo_\bi_\bn_\bt.
+ When data is entered into an R\bRR\bRD\bD, it is first fit into time slots
+ of the length defined with the -\b-s\bs option, thus becoming a _\bp_\br_\bi_\bm_\ba_\br_\by
+ _\bd_\ba_\bt_\ba _\bp_\bo_\bi_\bn_\bt.
- The data is also processed with the consolidation function (_\bC_\bF)
- of the archive. There are several consolidation functions that
- consolidate primary data points via an aggregate function:
- A\bAV\bVE\bER\bRA\bAG\bGE\bE, M\bMI\bIN\bN, M\bMA\bAX\bX, L\bLA\bAS\bST\bT. The format of R\bRR\bRA\bA line for these con-
- solidation functions is:
+ The data is also processed with the consolidation function (_\bC_\bF) of
+ the archive. There are several consolidation functions that consol-
+ idate primary data points via an aggregate function: A\bAV\bVE\bER\bRA\bAG\bGE\bE, M\bMI\bIN\bN,
+ M\bMA\bAX\bX, L\bLA\bAS\bST\bT. The format of R\bRR\bRA\bA line for these consolidation functions
+ is:
- R\bRR\bRA\bA:\b:_\bA_\bV_\bE_\bR_\bA_\bG_\bE _\b| _\bM_\bI_\bN _\b| _\bM_\bA_\bX _\b| _\bL_\bA_\bS_\bT:\b:_\bx_\bf_\bf:\b:_\bs_\bt_\be_\bp_\bs:\b:_\br_\bo_\bw_\bs
+ R\bRR\bRA\bA:\b:_\bA_\bV_\bE_\bR_\bA_\bG_\bE _\b| _\bM_\bI_\bN _\b| _\bM_\bA_\bX _\b| _\bL_\bA_\bS_\bT:\b:_\bx_\bf_\bf:\b:_\bs_\bt_\be_\bp_\bs:\b:_\br_\bo_\bw_\bs
- _\bx_\bf_\bf The xfiles factor defines what part of a consolidation
- interval may be made up from _\b*_\bU_\bN_\bK_\bN_\bO_\bW_\bN_\b* data while the consoli-
- dated value is still regarded as known. It is given as the
- ratio of allowed _\b*_\bU_\bN_\bK_\bN_\bO_\bW_\bN_\b* PDPs to the number of PDPs in the
- interval. Thus, it ranges from 0 to 1 (exclusive).
+ _\bx_\bf_\bf The xfiles factor defines what part of a consolidation interval
+ may be made up from _\b*_\bU_\bN_\bK_\bN_\bO_\bW_\bN_\b* data while the consolidated value is
+ still regarded as known. It is given as the ratio of allowed
+ _\b*_\bU_\bN_\bK_\bN_\bO_\bW_\bN_\b* PDPs to the number of PDPs in the interval. Thus, it
+ ranges from 0 to 1 (exclusive).
- _\bs_\bt_\be_\bp_\bs defines how many of these _\bp_\br_\bi_\bm_\ba_\br_\by _\bd_\ba_\bt_\ba _\bp_\bo_\bi_\bn_\bt_\bs are used to
- build a _\bc_\bo_\bn_\bs_\bo_\bl_\bi_\bd_\ba_\bt_\be_\bd _\bd_\ba_\bt_\ba _\bp_\bo_\bi_\bn_\bt which then goes into the
- archive.
+ _\bs_\bt_\be_\bp_\bs defines how many of these _\bp_\br_\bi_\bm_\ba_\br_\by _\bd_\ba_\bt_\ba _\bp_\bo_\bi_\bn_\bt_\bs are used to
+ build a _\bc_\bo_\bn_\bs_\bo_\bl_\bi_\bd_\ba_\bt_\be_\bd _\bd_\ba_\bt_\ba _\bp_\bo_\bi_\bn_\bt which then goes into the archive.
- _\br_\bo_\bw_\bs defines how many generations of data values are kept in an
- R\bRR\bRA\bA.
+ _\br_\bo_\bw_\bs defines how many generations of data values are kept in an
+ R\bRR\bRA\bA.
A\bAb\bbe\ber\brr\bra\ban\bnt\bt B\bBe\beh\bha\bav\bvi\bio\bor\br D\bDe\bet\bte\bec\bct\bti\bio\bon\bn w\bwi\bit\bth\bh H\bHo\bol\blt\bt-\b-W\bWi\bin\bnt\bte\ber\brs\bs F\bFo\bor\bre\bec\bca\bas\bst\bti\bin\bng\bg
In addition to the aggregate functions, there are a set of specialized
-1.2.26 2007-11-20 RRDCREATE(1)
+1.2.27 2008-02-17 RRDCREATE(1)