=head1 NAME
-bin_dec_hex - About Binary, Decimal, Hexadecimal
+bin_dec_hex - How to use binary, decimal, and hexadecimal notation.
+
+=for html <div align="right"><a href="bin_dec_hex.pdf">PDF</a> version.</div>
=head1 DESCRIPTION
Most people use the decimal numbering system. This system uses ten
symbols to represent numbers. When those ten symbols are used up, they
-start all over again and increment the position just before this. The
+start all over again and increment the position to the left. The
digit 0 is only shown if it is the only symbol in the sequence, or if
it is not the first one.
-If this sounds cryptic to you, this is what I've said in numbers:
+If this sounds cryptic to you, this is what I've just said in numbers:
0
1
and so on.
-Each time the digit nine should be incremented, it is reset to 0 and the
-position before is incremented. Then number 9 can be seen as "00009" and
-when we should increment 9, we reset it to zero and increment the digit
-just before the 9 so the number becomes "00010". For zero's we write a
-space if it is not the only digit (so: number 0) and if it is the first
-digit: "00010" -> " 0010" -> " 010" -> " 10". It is not " 1 ".
+Each time the digit nine is incremented, it is reset to 0 and the
+position before (to the left) is incremented (from 0 to 1). Then
+number 9 can be seen as "00009" and when we should increment 9, we
+reset it to zero and increment the digit just before the 9 so the
+number becomes "00010". Leading zeros we don't write except if it is
+the only digit (number 0). And of course, we write zeros if they occur
+anywhere inside or at the end of a number:
+
+ "00010" -> " 0010" -> " 010" -> " 10", but not " 1 ".
-This was pretty basic, you already knew this. Why did I tell it ?
-Well, computers do not represent numbers with 10 different digits. They
-know of only two different symbols, being 0 and 1. Apply the same rules
-to this set of digits and you get the binary numbering system:
+This was pretty basic, you already knew this. Why did I tell it?
+Well, computers usually do not represent numbers with 10 different
+digits. They only use two different symbols, namely "0" and "1". Apply
+the same rules to this set of digits and you get the binary numbering
+system:
0
1
and so on.
If you count the number of rows, you'll see that these are again 14
-different numbers. The numbers are the same and mean the same. It is
-only a different representation. This means that you have to know the
-representation used, or as it is called the numbering system or base.
-Normally if we do not speak about the numbering system used, we're
-using the decimal system. If we are talking about another numbering
-system, we'll have to make that clear. There are a few wide-spread
-methods to do so. One common form is to write 1010(2) which means that
-you wrote down a number in the binary form. It is the number ten.
-If you would write 1010 it means the number one thousand and ten.
-
-In books, another form is most used. It uses subscript (little chars,
-more or less in between two rows). You can leave out the parentheses
-in that case and write down the number in normal characters followed
-with a little two just behind it.
-
-The numbering system used is also called the base. We talk of the number
-1100 base 2, the number 12 base 10.
-
-For the binary system, is is common to write leading zero's. The numbers
-are written down in series of four, eight or sixteen depending on the
-context.
-
-We can use the binary form when talking to computers (...programming...)
-but the numbers will have large representations. The number 65535 would
-be written down as 1111111111111111(2) which is 16 times the digit 1.
-This is difficult and prone to errors. Therefore we normally would use
+different numbers. The numbers are the same and mean the same as in
+the first list, we just used a different representation. This means
+that you have to know the representation used, or as it is called the
+numbering system or base. Normally, if we do not explicitly specify
+the numbering system used, we implicitly use the decimal system. If we
+want to use any other numbering system, we'll have to make that
+clear. There are a few widely adopted methods to do so. One common
+form is to write 1010(2) which means that you wrote down a number in
+its binary representation. It is the number ten. If you would write
+1010 without specifying the base, the number is interpreted as one
+thousand and ten using base 10.
+
+In books, another form is common. It uses subscripts (little
+characters, more or less in between two rows). You can leave out the
+parentheses in that case and write down the number in normal
+characters followed by a little two just behind it.
+
+As the numbering system used is also called the base, we talk of the
+number 1100 base 2, the number 12 base 10.
+
+Within the binary system, it is common to write leading zeros. The
+numbers are written down in series of four, eight or sixteen depending
+on the context.
+
+We can use the binary form when talking to computers
+(...programming...), but the numbers will have large
+representations. The number 65'535 (often in the decimal system a ' is
+used to separate blocks of three digits for readability) would be
+written down as 1111111111111111(2) which is 16 times the digit 1.
+This is difficult and prone to errors. Therefore, we usually would use
another base, called hexadecimal. It uses 16 different symbols. First
the symbols from the decimal system are used, thereafter we continue
-with the alphabetic characters. We get 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A,
-B, C, D, E and F. This system is chosen because the hexadecimal form
-can be converted into the binary system very easy (and back).
+with alphabetic characters. We get 0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
+A, B, C, D, E and F. This system is chosen because the hexadecimal
+form can be converted into the binary system very easily (and back).
There is yet another system in use, called the octal system. This was
-more common in the old days but not anymore. You will find it in use
-on some places so get used to it. The same story applies, but now with
-only eight different symbols.
+more common in the old days, but is not used very often anymore. As
+you might find it in use sometimes, you should get used to it and
+we'll show it below. It's the same story as with the other
+representations, but with eight different symbols.
Binary (2)
Octal (8)
Most computers used nowadays are using bytes of eight bits. This means
that they store eight bits at a time. You can see why the octal system
-is not the most preferred for that: You'd need three digits to represent
+is not the most practical for that: You'd need three digits to represent
the eight bits and this means that you'd have to use one complete digit
to represent only two bits (2+3+3=8). This is a waste. For hexadecimal
digits, you need only two digits which are used completely:
(2) (8) (10) (16)
11111111 377 255 FF
-You can see why binary and hexadecimal can be converted quickly:
-For each hexadecimal digit there are exactly four binary digits.
-Take a binary number. Each time take four digits from the right and make
-a hexadecimal digit from it (see the table above). Stop when there are
-no more digits.
-Other way around: Take a hexadecimal number. For each digit, write down
-its binary equivalent.
-
-Computers (or rather the parsers running on them) would have a hard time
-converting a number like 1234(16). Therefore hexadecimal numbers get a
-prefix. This prefix depends on the language you're writing in. Some of
-the prefixes are "0x" for C, "$" for Pascal, "#" for HTML.
-It is common to assume that if a number starts with a zero, it is octal.
-It does not matter what is used as long as you know what it is.
-I will use "0x" for hexadecimal, "%" for binary and "0" for octal.
-The following numbers are all the same, just the way they are written is
-different: 021 0x11 17 %00010001
+You can see why binary and hexadecimal can be converted quickly: For
+each hexadecimal digit there are exactly four binary digits. Take a
+binary number: take four digits from the right and make a hexadecimal
+digit from it (see the table above). Repeat this until there are no
+more digits. And the other way around: Take a hexadecimal number. For
+each digit, write down its binary equivalent.
+
+Computers (or rather the parsers running on them) would have a hard
+time converting a number like 1234(16). Therefore hexadecimal numbers
+are specified with a prefix. This prefix depends on the language
+you're writing in. Some of the prefixes are "0x" for C, "$" for
+Pascal, "#" for HTML. It is common to assume that if a number starts
+with a zero, it is octal. It does not matter what is used as long as
+you know what it is. I will use "0x" for hexadecimal, "%" for binary
+and "0" for octal. The following numbers are all the same, just their represenatation (base) is different: 021 0x11 17 %00010001
To do arithmetics and conversions you need to understand one more thing.
It is something you already know but perhaps you do not "see" it yet:
-If you write down 1234, (so it is decimal) you are talking about the
-number one thousand, two hundred and thirty four. In sort of a formula:
+If you write down 1234, (no prefix, so it is decimal) you are talking
+about the number one thousand, two hundred and thirty four. In sort of
+a formula:
1 * 1000 = 1000
2 * 100 = 200
3 * 8^1
4 * 8^0
-This example can not be done for binary as that system can only use two
+This example can not be done for binary as that system only uses two
symbols. Another example:
%1010 would be
1 * 2^1
0 * 2^0
-It would have been more easy to convert it to its hexadecimal form and
+It would have been easier to convert it to its hexadecimal form and
just translate %1010 into 0xA. After a while you get used to it. You will
-not need to do any calculations anymore but just know that 0xA means 10.
+not need to do any calculations anymore, but just know that 0xA means 10.
-To convert a decimal number into a hexadecimal one you could use the next
-method. It will take some time to be able to do the estimates but it will
-be more and more easy when you use the system more frequent. Another way
-is presented to you thereafter.
+To convert a decimal number into a hexadecimal you could use the next
+method. It will take some time to be able to do the estimates, but it
+will be easier when you use the system more frequently. We'll look at
+yet another way afterwards.
-First you will need to know how many positions will be used in the other
-system. To do so, you need to know the maximum numbers. Well, that's not
-so hard as it looks. In decimal, the maximum number that you can form
-with two digits is "99". The maximum for three: "999". The next number
-would need an extra position. Reverse this idea and you will see that
-the number can be found by taking 10^3 (10*10*10 is 1000) minus 1 or
-10^2 minus one.
+First you need to know how many positions will be used in the other
+system. To do so, you need to know the maximum numbers you'll be
+using. Well, that's not as hard as it looks. In decimal, the maximum
+number that you can form with two digits is "99". The maximum for
+three: "999". The next number would need an extra position. Reverse
+this idea and you will see that the number can be found by taking 10^3
+(10*10*10 is 1000) minus 1 or 10^2 minus one.
-This can be done for hexadecimal too:
+This can be done for hexadecimal as well:
16^4 = 0x10000 = 65536
16^3 = 0x1000 = 4096
16^2 = 0x100 = 256
16^1 = 0x10 = 16
-If a number is smaller than 65536 it will thus fit in four positions.
-If the number is bigger than 4095, you will need to use position 4.
-How many times can you take 4096 from the number without going below
+If a number is smaller than 65'536 it will fit in four positions.
+If the number is bigger than 4'095, you must use position 4.
+How many times you can subtract 4'096 from the number without going below
zero is the first digit you write down. This will always be a number
from 1 to 15 (0x1 to 0xF). Do the same for the other positions.
-Number is 41029. It is smaller than 16^4 but bigger than 16^3-1. This
+Let's try with 41'029. It is smaller than 16^4 but bigger than 16^3-1. This
means that we have to use four positions.
-We can subtract 16^3 from 41029 ten times without going below zero.
-The leftmost digit will be "A" so we have 0xA????.
-The number is reduced to 41029 - 10*4096 = 41029-40960 = 69.
+We can subtract 16^3 from 41'029 ten times without going below zero.
+The left-most digit will therefore be "A", so we have 0xA????.
+The number is reduced to 41'029 - 10*4'096 = 41'029-40'960 = 69.
69 is smaller than 16^3 but not bigger than 16^2-1. The second digit
-is therefore "0" and we know 0xA0??.
+is therefore "0" and we now have 0xA0??.
69 is smaller than 16^2 and bigger than 16^1-1. We can subtract 16^1
(which is just plain 16) four times and write down "4" to get 0xA04?.
-Take 64 from 69 (69 - 4*16) and the last digit is 5 --> 0xA045.
+Subtract 64 from 69 (69 - 4*16) and the last digit is 5 --> 0xA045.
-The other method builds the number from the right. Take again 41029.
-Divide by 16 and do not use fractions (only whole numbers).
+The other method builds ub the number from the right. Let's try 41'029
+again. Divide by 16 and do not use fractions (only whole numbers).
- 41029 / 16 is 2564 with a remainder of 5. Write down 5.
- 2564 / 16 is 160 with a remainder of 4. Write the 4 before the 5.
+ 41'029 / 16 is 2'564 with a remainder of 5. Write down 5.
+ 2'564 / 16 is 160 with a remainder of 4. Write the 4 before the 5.
160 / 16 is 10 with no remainder. Prepend 45 with 0.
10 / 16 is below one. End here and prepend 0xA. End up with 0xA045.
-Which method to use is up to you. Use whatever works for you. Personally
-I use them both without being able to tell what method I use in each
-case, it just depends on the number, I think. Fact is, some numbers
-will occur frequently while programming, if the number is close then
-I will use the first method (like 32770, translate into 32768 + 2 and
-just know that it is 0x8000 + 0x2 = 0x8002).
-
+Which method to use is up to you. Use whatever works for you. I use
+them both without being able to tell what method I use in each case,
+it just depends on the number, I think. Fact is, some numbers will
+occur frequently while programming. If the number is close to one I am
+familiar with, then I will use the first method (like 32'770 which is
+into 32'768 + 2 and I just know that it is 0x8000 + 0x2 = 0x8002).
For binary the same approach can be used. The base is 2 and not 16,
and the number of positions will grow rapidly. Using the second method
-has the advantage that you can see very simple if you should write down
+has the advantage that you can see very easily if you should write down
a zero or a one: if you divide by two the remainder will be zero if it
-was an even number and one if it was an odd number:
+is an even number and one if it is an odd number:
41029 / 2 = 20514 remainder 1
20514 / 2 = 10257 remainder 0
At first while adding numbers, you'll convert them to their decimal
form and then back into their original form after doing the addition.
If you use the other numbering system often, you will see that you'll
-be able to do arithmetics in the base that is used.
+be able to do arithmetics directly in the base that is used.
In any representation it is the same, add the numbers on the right,
-write down the rightmost digit from the result, remember the other
-digits and use them in the next round. Continue with the second digits
+write down the right-most digit from the result, remember the other
+digits and use them in the next round. Continue with the second digit
from the right and so on:
%1010 + %0111 --> 10 + 7 --> 17 --> %00010001
--------
%10001 is the result, I like to write it as %00010001
-For low values, try to do the calculations yourself, check them with
-a calculator. The more you do the calculations yourself, the more you
+For low values, try to do the calculations yourself, then check them with
+a calculator. The more you do the calculations yourself, the more you'll
find that you didn't make mistakes. In the end, you'll do calculi in
-other bases as easy as you do in decimal.
+other bases as easily as you do them in decimal.
When the numbers get bigger, you'll have to realize that a computer is
-not called a computer just to have a nice name. There are many different
-calculators available. Use them. For Unix you could use "bc" which is
-called so as it is short for Binary Calculator. It calculates not only
-in decimal, but in all bases you'll ever use (among them Binary).
+not called a computer just to have a nice name. There are many
+different calculators available, use them. For Unix you could use "bc"
+which is short for Binary Calculator. It calculates not only in
+decimal, but in all bases you'll ever want to use (among them Binary).
For people on Windows:
Start the calculator (start->programs->accessories->calculator)
I hope you enjoyed the examples and their descriptions. If you do, help
other people by pointing them to this document when they are asking
-basic questions. They will not only get their answer but at the same
+basic questions. They will not only get their answer, but at the same
time learn a whole lot more.
Alex van den Bogaerdt E<lt>alex@ergens.op.het.netE<gt>
they appear. These operators act on the two values on the stack
preceding them (to the left). Read these two values on the stack
from left to right inserting the operator in the middle. If the
-resulting statement is true, the replace the three values from the
+resulting statement is true, then replace the three values from the
stack with "1". If the statement if false, replace the three values
with "0".
-For example think about "2,1,GT". This RPN expression could be
+For example, think about "2,1,GT". This RPN expression could be
read as "is two greater than one?" The answer to that question is
"true". So the three values should be replaced with "1". Thus the
RPN expression 2,1,GT evaluates to 1.
-Now also consider "2,1,LE". This RPN expression could be read as "is
+Now consider "2,1,LE". This RPN expression could be read as "is
two less than or equal to one?". The natural response is "no"
and thus the RPN expression 2,1,LE evaluates to 0.
While compound expressions can look overly complex, they can be
considered elegantly simple. To quickly comprehend RPN expressions,
you must know the the algorithm for evaluating RPN expressions:
-iterate searches from the left to the right looking for an operator,
-when it's found, apply that operator by popping the operator and some
+iterate searches from the left to the right looking for an operator.
+When it's found, apply that operator by popping the operator and some
number of values (and by definition, not operators) off the stack.
For example, the stack "1,2,3,+,+" gets "2,3,+" evaluated (as "2+3")
-during the first iteration which is replaced by 5. This results in
+during the first iteration and is replaced by 5. This results in
the stack "1,5,+". Finally, "1,5,+" is evaluated resulting in the
-answer 6. For convenience sake, it's useful to write this set of
+answer 6. For convenience, it's useful to write this set of
operations as:
1) 1,2,3,+,+ eval is 2,3,+ = 5 result is 1,5,+
4) 0,7000,1024,IF result is 1024
-Now let's go back to the first example of multiple logic operators
+Now let's go back to the first example of multiple logic operators,
but replace the value 20 with the variable "input":
+=for comment
+XXX wo kommt das A ploetzlich her? Hier braucht es einen Satz, dass A als
+XXX placeholder zum Lesbarmachen verwendet wird (shortcut).
+
1) input,10,GT,10,input,IF eval is input,10,GT result is A
Read eval as "if input > 10 then true" and replace "input,10,GT"
-with "A:
+with "A":
2) A,10,input,IF eval is A,10,input,IF
-read "if A then 10 else input". Now replace A it's verbose
-description and--voila!--you have a easily readable description
+read "if A then 10 else input". Now replace A with it's verbose
+description againg and--voila!--you have a easily readable description
of the expression:
if input > 10 then 10 else input
-Lastly, let's to back the first most complex example and replace
+Finally, let's go back to the first most complex example and replace
the value 128 with "input":
1) input,8,*,7000,GT,7000,input,8,*,IF eval input,8,* result is A
input,56000,GT,56000,input,IF,8,*
-Use tradition notation to show these expressions are not the same.
-Write an expression that's equivalent to the first expression but
+Use traditional notation to show these expressions are not the same.
+Write an expression that's equivalent to the first expression, but
uses the LE and DIV operators.
Answer 2:
Exercise 4:
-Explain why it is desirable for the RRDtool developers to implement
+Explain why it was desirable for the RRDtool developers to implement
RPN notation instead of traditional mathematical notation.
Answer 4:
In the end it will printout a web page including the necessary CGI headers.
B<rrdcgi> parses the contents of the template in 3 steps. In each step it looks
-only for a subset of tags. This allows to nest tags.
+only for a subset of tags. This allows nesting of tags.
-The argument parser uses the same semantics as you are used from your c shell.
+The argument parser uses the same semantics as you are used from your C-shell.
=over 8
-
=item B<--filter>
-Assume that rrdcgi is being run as a filter and not as a cgi.
+Assume that rrdcgi is run as a filter and not as a cgi.
=back
Inserts the CGI variable of the given name but quotes it, ready for
use as an argument in another RRD:: tag. So even when there are spaces in the
-value of the CGI variable it will still be considered as one argument.
+value of the CGI variable it will still be considered to be one argument.
=item RRD::CV::PATH I<name>
Inserts the CGI variable of the given name, quotes it and makes sure
-the it starts neither with a '/' nor contains '..'. This is to make
+it starts neither with a '/' nor contains '..'. This is to make
sure that no problematic pathnames can be introduced through the
CGI interface.
<RRD::GETENV REMOTE_USER>
might give you the name of the remote user given you are using
-some sort of access control on the directory
+some sort of access control on the directory.
=item RRD::GOODFOR I<seconds>
Specify the number of seconds this page should remain valid. This will prompt
the rrdcgi to output a Last-Modified, an Expire and if the number of
-seconds is I<negative> a Refresh headers.
+seconds is I<negative> a Refresh header.
=item RRD::INCLUDE I<filename>
-Include the contents of the given file into the page returned from the cgi
+Include the contents of the specified file into the page returned from the cgi.
=item RRD::SETENV I<variable> I<value>
=item RRD::SETVAR I<variable> I<value>
-Analog to SETENV but for local variables
+Analog to SETENV but for local variables.
=item RRD::GETVAR I<variable>
-Analog to GETENV but for local variables
+Analog to GETENV but for local variables.
=item RRD::TIME::LAST I<rrd-file> I<strftime-format>
This gets replaced by the current time of day. The time is
I<strftime>-formatted with the string specified in the argument.
-Note that if you return : from your strftime format you may have to escape
-them using \ if the time is to be used as an argument to a GRAPH command.
+Note that if you return : (colons) from your strftime format you may
+have to escape them using \ if the time is to be used as an argument
+to a GRAPH command.
=item RRD::TIME::STRFTIME I<START|END> I<start-spec> I<end-spec> I<strftime-format>
to allow pretty titles on graphs with times that are easier for non RRDtool
folks to figure out than "-2weeks".
-Note that if you return : from your strftime format you may have to escape
-them using \ if the time is to be used as an argument to a GRAPH command.
+Note that again, if you return : (colon) from your strftime format,
+you may have to escape them using \ if the time is to be used as an
+argument to a GRAPH command.
=item RRD::GRAPH I<rrdgraph arguments>
-This tag creates the RRD graph defined in its argument and then gets
+=for comment
+XXX Shouldn't it be IMAGE-tag below? Fritz
+
+This tag creates the RRD graph defined by its argument and then is
replaced by an appropriate E<lt>IMGE<gt> tag referring to the graph.
The B<--lazy> option in RRD graph can be used to make sure that graphs
are only regenerated when they are out of date. The arguments
This script is slightly more elaborate, it allows you to run it from
a form which sets RRD_NAME. RRD_NAME is then used to select which RRD
-you want to use a source for your graph.
+you want to use as source for your graph.
#!/usr/local/bin/rrdcgi
<HTML>
=head1 DESCRIPTION
-The B<fetch> function is normally used internally by the graph function,
-to get data from B<RRD>s. B<fetch> will analyze the B<RRD> and
-will try to retrieve the data in the resolution requested.
+The B<fetch> function is normally used internally by the graph
+function to get data from B<RRD>s. B<fetch> will analyze the B<RRD>
+and try to retrieve the data in the resolution requested.
The data fetched is printed to stdout. I<*UNKNOWN*> data is often
represented by the string "NaN" depending on your OS's printf
function.
=item I<CF>
-which consolidation function should have been applied to the data you
-want to fetch? (AVERAGE,MIN,MAX,LAST)
+the consolidation function that is applied to the data you
+want to fetch (AVERAGE,MIN,MAX,LAST)
=item B<--resolution>|B<-r> I<resolution> (default is the highest resolution)
-what interval should the values have (seconds per value). B<rrdfetch> will try
-to match your request, but it will return data even if no absolute
-match is possible. B<NB.> See note below.
+the interval you want the values to have (seconds per
+value). B<rrdfetch> will try to match your request, but it will return
+data even if no absolute match is possible. B<NB.> See note below.
=item B<--start>|B<-s> I<start> (default end-1day)
-when should the data begin. A time in seconds since epoch (1970-01-01)
-is required. Negative numbers are relative to the current time. By default
+start of the time series. A time in seconds since epoch (1970-01-01)
+is required. Negative numbers are relative to the current time. By default,
one day worth of data will be fetched. See also AT-STYLE TIME SPECIFICATION
-section for a detailed explanation on ways to specify start time.
+section for a detailed explanation on ways to specify the start time.
=item B<--end>|B<-e> I<end> (default now)
-when should the data end. Time in seconds since epoch. See also
-AT-STYLE TIME SPECIFICATION section for a detailed explanation of how to specify
-end time.
+the end of the time series in seconds since epoch. See also AT-STYLE
+TIME SPECIFICATION section for a detailed explanation of how to
+specify the end time.
=back
In order to get RRDtool to fetch anything other than the finest resolution RRA
B<both> the start and end time must be specified on boundaries that are
-multiples of the wanted resolution. Consider the following example:
+multiples of the desired resolution. Consider the following example:
rrdtool create subdata.rrd -s 10 DS:ds0:GAUGE:300:0:U \
RRA:AVERAGE:0.5:30:3600 \
RRA:AVERAGE:0.5:8640:600 \
RRA:MAX:0.5:8640:600
-This RRD collects data every 10 seconds and stores its averages over 5 minutes,
-15 minutes, 1 hour and 1 day as well as the maxima for 1 hour and 1 day.
+This RRD collects data every 10 seconds and stores its averages over 5
+minutes, 15 minutes, 1 hour, and 1 day, as well as the maxima for 1 hour
+and 1 day.
-Consider now that you want too fetch the 15 minute average data for last hour.
-So you might try
+Consider now that you want to fetch the 15 minute average data for the
+last hour. You might try
rrdtool fetch subdata.rrd AVERAGE -r 900 -s -1h
-However, this will almost always result in a time series that is B<NOT> in the 15
-minute RRA. Therefore the highest resolution RRA, i.e. 5 minute averages, will
-be chosen which, in this case, is not what you want.
+However, this will almost always result in a time series that is
+B<NOT> in the 15 minute RRA. Therefore, the highest resolution RRA,
+i.e. 5 minute averages, will be chosen which in this case is not
+what you want.
Hence, make sure that
=item 2.
-both start and end time are within the wanted RRA
+both start and end time are within the desired RRA
=back
-So, if time now is called "t",
+So, if time now is called "t", do
- do end time == int(t/900)*900,
- start time == end time -1hour, resolution == 900.
+ end time == int(t/900)*900,
+ start time == end time - 1hour,
+ resolution == 900.
-In e.g. bash this could look as:
+Using the bash shell, this could look be:
TIME=$(date +%s)
RRDRES=900
=head2 AT-STYLE TIME SPECIFICATION
Apart from the traditional I<Seconds since epoch>, RRDtool does also
-understand at-style time specification. The specification is called
-"at-style" after Unix command at(1) that has moderately complex ways
-to specify time to run your job at. The at-style specification
-consists of two parts: B<TIME REFERENCE> specification and B<TIME
-OFFSET> specification.
+understand at-style time specification. The specification is called
+"at-style" after the Unix command at(1) that has moderately complex
+ways to specify time to run your job at a certain date and time. The
+at-style specification consists of two parts: the B<TIME REFERENCE>
+specification and the B<TIME OFFSET> specification.
=head2 TIME REFERENCE SPECIFICATION
-Time reference specification is used, well,... to establish a reference
-moment in time (for time offset to be applied to). When present,
+The time reference specification is used, well, to establish a reference
+moment in time (to which the time offset is then applied to). When present,
it should come first, when omitted, it defaults to B<now>. On its own part,
-time reference consists of I<time-of-day> reference (which should come
-first, if present) and I<day> reference.
+time reference consists of a I<time-of-day> reference (which should come
+first, if present) and a I<day> reference.
-I<Time-of-day> can be specified as B<HH:MM>, B<HH.MM>,
-or just B<HH>
, you can suffix it with B<am> or B<pm> or use
-24-hours clock. The few special times of day are understood as well,
-these include B<midnight> (00:00), B<noon> (12:00) and British
+The I<time-of-day> can be specified as B<HH:MM>, B<HH.MM>,
+or just B<HH>
. You can suffix it with B<am> or B<pm> or use
+24-hours clock. Some special times of day are understood as well,
+including B<midnight> (00:00), B<noon> (12:00) and British
B<teatime> (16:00).
+=for comment
+XXX Wouldn't it be nice to have z'N\"uni and z'Vieri for Switzerland?
+
The I<day> can be specified as I<month-name> I<day-of-the-month>
-and optional 2- or 4-digit I<year> number (e.g. March 8 1999).
+and optional a 2- or 4-digit I<year> number (e.g. March 8 1999).
Alternatively, you can use I<day-of-week-name> (e.g. Monday),
or one of the words: B<yesterday>, B<today>, B<tomorrow>.
-You can also specify I<day> as a full date in several numerical formats;
-these include: B<MM/DD/[YY]YY>, B<DD.MM.[YY]YY>, B<YYYYMMDD>.
+You can also specify the I<day> as a full date in several numerical formats, including B<MM/DD/[YY]YY>, B<DD.MM.[YY]YY>, or B<YYYYMMDD>.
-I<NOTE1>: this is different from the original at(1) behavior,
-which interprets a single-number date as MMDD[YY]YY.
+I<NOTE1>: this is different from the original at(1) behavior, where a
+single-number date is interpreted as MMDD[YY]YY.
-I<NOTE2>: if you specify I<day> this way, the I<time-of-day> is REQUIRED
-to be present.
+I<NOTE2>: if you specify the I<day> in this way, the I<time-of-day> is
+REQUIRED as well.
-Finally, you can use words B<now>, B<start>, or B<end> as your time
-reference. B<Now> refers to the current moment (and is also a default
-time reference). B<Start> (B<end>) can be used to specify time
+Finally, you can use the words B<now>, B<start>, or B<end> as your time
+reference. B<Now> refers to the current moment (and is also the default
+time reference). B<Start> (B<end>) can be used to specify a time
relative to the start (end) time for those tools that use these
categories (B<rrdfetch>, L<rrdgraph>).
-Month and weekday names can be used in their naturally abbreviated form
-(e.g., Dec for December, Sun for Sunday, etc.). The words B<now>,
-B<start>, B<end> can be abbreviated to B<n>, B<s>, B<e>.
+Month and day of the week names can be used in their naturally
+abbreviated form (e.g., Dec for December, Sun for Sunday, etc.). The
+words B<now>, B<start>, B<end> can be abbreviated as B<n>, B<s>, B<e>.
=head2 TIME OFFSET SPECIFICATION
-Time offset specification is used to add (or subtract) certain time
-interval to (from) the time reference moment. It consists of I<sign>
-(S<B<+> or B<->>) and I<amount>. The following time units can be used
-to specify the I<amount>: B<years>, B<months>, B<weeks>, B<days>,
-B<hours>, B<minutes>, B<seconds>, these can be used in singular
-or plural form, and abbreviated naturally or to a single letter
-(e.g. +3days, -1wk, -3y). Several time units can be combined
-together (e.g., -5mon1w2d), as well as several time offsets can be
-concatenated (e.g., -5h45min = -5h-45min = -6h+15min = -7h+1h30m-15min, etc.)
+The time offset specification is used to add/subtract certain time
+intervals to/from the time reference moment. It consists of a I<sign>
+(S<B<+> or B<->>) and an I<amount>. The following time units can be
+
used to specify the I<amount>: B<years>, B<months>, B<weeks>, B<days>,
+B<hours>, B<minutes>, or B<seconds>. These units can be used in
+singular or plural form, and abbreviated naturally or to a single
+letter (e.g. +3days, -1wk, -3y). Several time units can be combined
+(e.g., -5mon1w2d) or concatenated (e.g., -5h45min = -5h-45min =
+-6h+15min = -7h+1h30m-15min, etc.)
I<NOTE3>: If you specify time offset in days, weeks, months, or years,
-you will end with the time offset that may vary depending on you time
+you will end with the time offset that may vary depending on your time
reference, because all those time units have no single well defined
time interval value (S<1 year> contains either 365 or 366 days, S<1 month>
is 28 to 31 days long, and even S<1 day> may be not equal to 24 hours
twice a year, when DST-related clock adjustments take place).
To cope with this, when you use days, weeks, months, or years
as your time offset units your time reference date is adjusted
-accordingly without taking too much further effort to ensure anything
+accordingly without too much further effort to ensure anything
about it (in the hope that mktime(3) will take care of this later).
This may lead to some surprising (or even invalid!) results,
e.g. S<'May 31 -1month'> = S<'Apr 31'> (meaningless) = S<'May 1'>
(after mktime(3) normalization); in the EET timezone
'3:30am Mar 29 1999 -1 day' yields '3:30am Mar 28 1999' (Sunday)
-which is invalid time/date combination (because of 3am -> 4am DST
+which is an invalid time/date combination (because of 3am -> 4am DST
forward clock adjustment, see the below example).
-On the other hand, hours, minutes, and seconds are well defined time
+
+In contrast, hours, minutes, and seconds are well defined time
intervals, and these are guaranteed to always produce time offsets
-exactly as specified (e.g. for EET timezone, S<'8:00 Mar 27 1999 +2 days'> =
-S<'8:00 Mar 29 1999'>, but since there is 1-hour DST forward clock adjustment
-takes place around S<3:00 Mar 28 1999>, the actual time interval between
-S<8:00 Mar 27 1999> and S<8:00 Mar 29 1999> equals 47 hours; on the other hand,
-S<'8:00 Mar 27 1999 +48 hours'> = S<'9:00 Mar 29 1999'>, as expected)
+exactly as specified (e.g. for EET timezone, S<'8:00 Mar 27 1999 +2
+days'> = S<'8:00 Mar 29 1999'>, but since there is 1-hour DST forward
+clock adjustment that occurs around S<3:00 Mar 28 1999>, the actual
+time interval between S<8:00 Mar 27 1999> and S<8:00 Mar 29 1999>
+equals 47 hours; on the other hand, S<'8:00 Mar 27 1999 +48 hours'> =
+S<'9:00 Mar 29 1999'>, as expected)
I<NOTE4>: The single-letter abbreviation for both B<months> and B<minutes>
-is B<m>. To disambiguate, the parser tries to read your S<mind :)>
+is B<m>. To disambiguate them, the parser tries to read your S<mind :)>
by applying the following two heuristics:
=over 3
If B<m> is used in context of (i.e. right after the) years,
months, weeks, or days it is assumed to mean B<months>, while
in the context of hours, minutes, and seconds it means minutes.
-(e.g., in -1y6m or +3w1m B<m> means B<months>, while in
--3h20m or +5s2m B<m> means B<minutes>)
+(e.g., in -1y6m or +3w1m B<m> is interpreted as B<months>, while in
+-3h20m or +5s2m B<m> the parser decides for B<minutes>).
=item 2
Out of context (i.e. right after the B<+> or B<-> sign) the
meaning of B<m> is guessed from the number it directly follows.
-Currently, if the number absolute value is below 25 it is assumed
+Currently, if the number's absolute value is below 25 it is assumed
that B<m> means B<months>, otherwise it is treated as B<minutes>.
(e.g., -25m == -25 minutes, while +24m == +24 months)
=back
I<Final NOTES>: Time specification is case-insensitive.
-Whitespace can be inserted freely or omitted altogether,
-there are, however, cases when whitespace is required
+Whitespace can be inserted freely or omitted altogether.
+There are, however, cases when whitespace is required
(e.g., S<'midnight Thu'>). In this case you should either quote the
whole phrase to prevent it from being taken apart by your shell or use
'_' (underscore) or ',' (comma) which also count as whitespace
-(e.g., midnight_Thu or midnight,Thu)
+(e.g., midnight_Thu or midnight,Thu).
=head2 TIME SPECIFICATION EXAMPLES
I<Oct 12> -- October 12 this year
I<-1month> or I<-1m> -- current time of day, only a month before
-(may yield surprises, see the NOTE3 above)
+(may yield surprises, see NOTE3 above).
-I<noon yesterday -3hours> -- yesterday morning; can be put also as I<9am-1day>
+I<noon yesterday -3hours> -- yesterday morning; can also be specified
+as I<9am-1day>.
-I<23:59 31.12.1999> -- 1 minute to the year 2000
+I<23:59 31.12.1999> -- 1 minute to the year 2000.
-I<12/31/99 11:59pm> -- 1 minute to the year 2000 for imperialists
+I<12/31/99 11:59pm> -- 1 minute to the year 2000 for imperialists.
I<12am 01/01/01> -- start of the new millennium
I<end-3weeks> or I<e-3w> -- 3 weeks before end time
-(may be used as start time specification)
+(may be used as start time specification).
I<start+6hours> or I<s+6h> -- 6 hours after start time
-(may be used as end time specification)
+(may be used as end time specification).
I<931225537> -- 18:45 July 5th, 1999
-(yes, seconds since 1970 are valid as well)
+(yes, seconds since 1970 are valid as well).
I<19970703 12:45> -- 12:45 July 3th, 1997
-(my favorite, and its even got an ISO number (8601))
+(my favorite, and its even got an ISO number (8601)).
=head1 AUTHOR
=head1 NAME
-rrdgraph_data - Preparing data for graphing
+rrdgraph_data - preparing data for graphing in rrdtool graph
=head1 SYNOPSIS
=head1 DESCRIPTION
-These three instructions collect the data out of the B<RRD> files,
-optionally altering it (think of a bytes to bits conversion) and
-if desired you can define variables containing useful information
-such as maximum, minimum etcetera. Two of the instructions use
-a language called B<RPN> which is described in its own manual page.
+These three instructions extract data values out of the B<RRD> files,
+optionally altering them (think, for example, of a bytes to bits
+conversion). If so desired, you can also define variables containing
+useful information such as maximum, minimum etcetera. Two of the
+instructions use a language called B<RPN> which is described in its
+own manual page.
=head1 DEF
you can override this by specifying B<start and end>. Remember to
escape colons in the time specification!
-If the resolution of the data is higher than the resolution of off
-graph, the data will be further consolidated. This may result in
+If the resolution of the data is higher than the resolution of the
+graph, the data will be further consolidated. This may result in
a graph that spans slightly more time than requested.
Ideally each point in the graph should correspond with one B<CDP>
from an B<RRA>. For instance, if your B<RRD> has an B<RRA> with
a resolution of 1800 seconds per B<CDP>, you should create an
image with width 400 and time span 400*1800 seconds (use appropriate
start and end times, such as C<--start end-8days8hours>).
+=for comment
+XXX is the above start/end syntax correct? Fritz
If consolidation needs to be done, the B<CF> of the B<RRA> specified in the
-B<DEF> itself will be used to reduce the data density. This behaviour can
+B<DEF> itself will be used to reduce the data density. This behaviour can
be changed using C<:reduce=I<E<lt>B<CF>E<gt>>>. This optional parameter
specifies the B<CF> to use during the data reduction phase.
=head1 SEE ALSO
L<rrdgraph> gives an overview of how B<rrdtool graph> works.
-L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail,
-L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements,
+L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail.
+L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements.
L<rrdgraph_graph> page describes all of the graph and print functions.
Make sure to read L<rrdgraph_examples> for tipsE<amp>tricks.
COMMENT:" "
+=for comment
+XXX I don't understand the following; Fritz
+
Note: three times size == 11 chars, "###.## xBps"
COMMENT:"Maximum "
COMMENT:"Average "
COMMENT:"Minimum "
-Note: last line contains new-line character
+Note: some lines contains the new-line character "\n"
COMMENT:"95th percentile\n"
AREA:ds0bits#00C000:"Inbound "
DEF:mydata=my.rrd:ds:AVERAGE
-Note: this will also influence anything that uses "data"
+Note: this will also influence any other command that uses "data"
CDEF:data=mydata,100,+
LINE1:data#FF0000:"Data with offset"
=head2 Time ranges
Last four weeks: --start end-4w --end 00:00
- Januari 2001: --start 200101010000 --end start+31d
- Januari 2001: --start 200101010000 --end 200102010000
+ January 2001: --start 200101010000 --end start+31d
+ January 2001: --start 200101010000 --end 200102010000
Last hour: --start end-1h
Last 24 hours: <nothing at all>
Yesterday: --end 00:00
-=head2 Viewing This week and last week together
+=head2 Viewing the current and previous week together
--end now --start end-1w
DEF:thisweek=router.rrd:ds0:AVERAGE
DEF:lastweek=router.rrd:ds0:AVERAGE:end=now-1w:start=end-1w
-shift the data forward by one week (604800 seconds)
+Shift the data forward by one week (604800 seconds)
SHIFT:lastweek:604800
[ more of the usual VDEF and CDEF stuff if you like ]
=head1 SEE ALSO
L<rrdgraph> gives an overview of how B<rrdtool graph> works.
-L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail,
-L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements,
-L<rrdgraph_graph> page describes all of the graph and print functions.
+L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail.
+L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements.
+L<rrdgraph_graph> page describes all the graph and print functions.
Make sure to read L<rrdgraph_examples> for tipsE<amp>tricks.
=head1 NAME
-rrdgraph_graph - Command reference
+rrdgraph_graph - rrdtool graph command reference
=head1 SYNOPSIS
These instructions allow you to generate your image or report.
If you don't use any graph elements, no graph is generated.
-Similarly no report is generated if you don't use print options.
+Similarly, no report is generated if you don't use print options.
=head1 PRINT
=item *
-B<%#.#le> prints like 1.2346e+04. Optional numbers # are field width and
-decimal precision
+B<%#.#le> prints numbers like 1.2346e+04. The optional integers # denote field
+width and decimal precision.
=item *
-B<%#.#lf> prints like 12345.6789, with optional field width and precision
+B<%#.#lf> prints numbers like 12345.6789, with optional field width
+and precision.
=item *
B<%s> place this after B<%le>, B<%lf> or B<%lg>. This will be replaced by the
appropriate SI magnitude unit and the value will be scaled
-accordingly (123456 -> 123.456 k)
+accordingly (123456 -> 123.456 k).
=item *
-B<%S> is similar to B<%s>. It does however use a previously defined
+B<%S> is similar to B<%s>. It does, however, use a previously defined
magnitude unit. If there is no such unit yet, it tries to define
-one (just like B<%s>). However, if the value is zero, the magnitude
+one (just like B<%s>) unless the value is zero, in which case the magnitude
unit stays undefined. Thus, formatter strings using B<%S> and no B<%s>
will all use the same magnitude unit except for zero values.
=item *
-B<%a, %A> prints abbreviated, full weekday name
+B<%a, %A> print the abbreviated or full name of the day of the week.
=item *
-B<%b, %B> prints abbreviated, full month name
+B<%b, %B> print the abbreviated or full name of the month.
=item *
-B<%d, %m, %y, %H, %M, %S> day,month,year,hour,minute,second all in two-digit format
+B<%d, %m, %y, %H, %M, %S> print day, month, year, hour, minute, and
+second in two-digit format.
=item *
-B<%Y> year in 4-digit format
+B<%Y> prints the year in 4-digit format.
=item *
-B<%I, %p> hour (01..12), 'am' or 'pm'
+B<%I, %p> print the hour (01..12), 'am' or 'pm'.
=item *
-B<%j, %w> day of the week (0..6), day of the year (1..366)
+B<%j, %w> print day of the week (0..6), day of the year (1..366)
=item *
-B<%c, %x, %X> date+time, date, time
+B<%c, %x, %X> print date+time, date only, time only.
=item *
-B<%U, %W> week number of the current year with either the first Sunday or
-the first Monday determining the first week
+B<%U, %W> number of the week of the current year, with either the
+first Sunday (%U) or the first Monday (%W) determining the first week.
=item *
-B<%Z> time zone
+B<%Z> prints the time zone.
=back
=item B<GPRINT>B<:>I<vname>B<:>I<CF>B<:>I<format>
I<Deprecated. Use the new form of this command in new scripts.>
-This is the same as C<PRINT> but now it is printed inside the graph.
+This is the same as C<PRINT>, but printed inside the graph.
=item B<GPRINT>B<:>I<vname>B<:>I<format>
-This is the same as C<PRINT> but now it is printed inside the graph.
+This is the same as C<PRINT>, but printed inside the graph.
=item B<COMMENT>B<:>I<text>
-Text is printed literally in the legend section of the graph
+Text is printed literally in the legend section of the graph.
=item B<HRULE>B<:>I<value>B<#>I<color> [ :I<legend> ]
=item B<VRULE>B<:>I<vname>B<#>I<color> [B<:>I<legend> ]
Draw a vertical line at I<time>. Its color is composed from three
-hexadecimal numbers specifying the color components (00 is off, FF is
-maximum) red, green and blue. Optionally a legend box and string is
+hexadecimal numbers specifying the rgb color components (00 is off, FF is
+maximum) red, green and blue. Optionally, a legend box and string is
printed in the legend section. I<time> may be a number or a variable
from a B<VDEF>. It is an error to use I<vname>s from B<DEF> or B<CDEF> here.
=item B<LINE>I<width>B<:>I<{vname or number}>B<#>I<color>[B<:>I<legend>]
[ C<:STACK> ]
-Draw a line of the specified width into the graph. If the color
-is not specified, the drawing is done 'blind'. This is useful when
+Draw a line of the specified width onto the graph. If the color
+is not specified, the drawing is done 'invisibly'. This is useful when
stacking something else on top of this line. Also optional is the
legend box and string which will be printed in the legend section
-if specified. The B<vname> can be generated by B<DEF>, B<VDEF> and
+if specified. The B<vname> can be generated by B<DEF>, B<VDEF>, and
B<CDEF>. If the optional B<STACK> modifier is used, this line is
stacked on top of the previous element which can be a B<LINEx> or
an B<AREA>
=item B<AREA>B<:>I<vname>B<#>I<rrggbb>[I<aa>][B<:>I<legend>][B<:STACK>]
See B<LINE>, however the area between the x-axis and the line will
-also be filled.
+be filled.
=item B<TICK>B<:>I<vname>B<#>I<rrggbb>[I<aa>][B<:>I<fraction>[B<:>I<legend>]]
Using this command B<RRDtool> will graph the following elements
with the specified offset. For instance, you can specify an
-offset of S<( 7*24*60*60 = ) 604800 seconds> to "look back" one
-week. Make sure to notify the viewer you did so...
+offset of S<( 7*24*60*60 = ) 604'800 seconds> to "look back" one
+week. Make sure to tell the viewer of your graph you did this ...
As with the other graphing elements, you can specify a number or
a variable here.
=item B<PART>B<:>I<vname>B<#>I<rrggbb>[I<aa>][B<:>I<legend>]
B<RRDtool> has now support for B<pie charts>. If you include the
-B<PART> command, the canvas is extended to make room for a chart
+B<PART> command, the canvas is extended to make room for a chart.
The size of the canvas is determined by the lesser of
L<width and height|rrdgraph/item_Size>.
function. It should return a number between 0 and 100, being a
percentage. Providing wrong input will produce undefined results.
+=for comment
+XXX Above: shouldn't this be caught and and error be generated? Fritz
+
=pod
=item B<STACK>B<:>I<vname>B<#>I<color>[B<:>I<legend>]
on top of the previous element. There must be something to stack
upon.
-An B<invisible> LINEx or AREA B<is> present and can be stacked upon.
+You can use an B<invisible> LINEx or AREA to stacked upon.
An B<unknown> value makes the entire stack unknown from that moment on.
You don't know where to begin (the unknown value) and therefore do
=head2 Escaping the colon
-In a ':' in a I<legend> argument will mark the end of the legend. To
-enter a ':' into a legend, the colon must be escaped with a backslash '\:'.
-Beware, that many environments look for backslashes themselves, so it may
-be necessary to write two backslashes so that one is passed onto rrd_graph.
+A colon ':' in a I<legend> argument will mark the end of the
+legend. To enter a ':' as part of a legend, the colon must be escaped
+with a backslash '\:'. Beware that many environments process
+backslashes themselves, so it may be necessary to write two
+backslashes in order to one being passed onto rrd_graph.
=head2 String Formatting
-The text printed below the actual graph can be formated by appending special
-escaped characters at the end of a text. When ever such a character occurs,
+The text printed below the actual graph can be formatted by appending special
+escape characters at the end of a text. When ever such a character occurs,
all pending text is pushed onto the graph according to the character
specified.
Valid markers are: B<\j> for justified, B<\l> for left aligned, B<\r> for
-right aligned and B<\c> for centered. In the next section there is an
-example showing how to use centered formating.
+right aligned, and B<\c> for centered. In the next section there is an
+example showing how to use centered formatting.
Normally there are two space characters inserted between every two items
printed into the graph. The space following a string can be suppressed by
GPRINT:a:MAX:%lf%s\g
-A special case is COMMENT:B<\s> this inserts some additional vertical space
+A special case is COMMENT:B<\s> which inserts some additional vertical space
before placing the next row of legends.
-If you are using the proportional font in your graph, you can use tab characters
-or the sequence B<\t> to lin-up legend elements. Note that the tabs inserted are
-relative to the start of the current legend element!
+If you are using the proportional font in your graph, you can use tab
+characters or the sequence B<\t> to line-up legend elements. Note that
+the tabs inserted are relative to the start of the current legend
+element!
=head1 SEE ALSO
L<rrdgraph> gives an overview of how B<rrdtool graph> works.
-L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail,
-L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements,
+L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail.
+L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements.
L<rrdgraph_graph> page describes all of the graph and print functions.
Make sure to read L<rrdgraph_examples> for tipsE<amp>tricks.
B<RPN>. The idea behind B<RPN> is that you have a stack and push
your data onto this stack. Whenever you execute an operation, it
takes as many elements from the stack as needed. Pushing is done
-implicit so whenever you specify a number or a variable, it gets
-pushed automatically.
+implicitly, so whenever you specify a number or a variable, it gets
+pushed onto the stack automatically.
-At the end of the calculation there should be one and exactly one
+At the end of the calculation there should be one and only one
value left on the stack. This is the outcome of the function and
this is what is put into the I<vname>. For B<CDEF> instructions,
the stack is processed for each data point on the graph. B<VDEF>
For expressions like C<a = b + 3 * 5> you need to multiply 3 with
5 first before you add I<b> to get I<a>. However, with parentheses
you could change this order: C<a = (b + 3) * 5>. In B<RPN>, you
-would do C<a = b, 3, +, 5, *> and need no parentheses.
+would do C<a = b, 3, +, 5, *> without the need for parentheses.
=head1 OPERATORS
B<IF>
-Pops three elements from the stack. If the last element is 0 (false),
-the first value is pushed back onto the stack, otherwise the second
-popped value is pushed back. This does, indeed, mean that any value
-other than 0 is considered to be true.
+Pops three elements from the stack. If the element popped last is 0
+(false), the value popped first is pushed back onto the stack,
+otherwise the value popped second is pushed back. This does, indeed,
+mean that any value other than 0 is considered to be true.
Example: C<A,B,C,IF> should be read as C<if (A) then (B) else (C)>
B<MIN, MAX>
-Pops two elements from the stack and returns the lesser or larger.
-The two numbers shouldn't be I<infinite> or I<unknown>, if they are
-that value is pushed back onto the stack as the result.
+Pops two elements from the stack and returns the smaller or larger,
+respectively. The two numbers shouldn't be I<infinite> or I<unknown>,
+if they are that value is pushed back onto the stack as the result.
+
+= for comment
+XXX What happens above if both a infinite and undefined value are on the
+XXX stack? Fritz
B<LIMIT>
B<SIN, COS, LOG, EXP, SQRT>
-Sine, cosine (input in radians), log, exp (natural logarithm), square root
+Sine and cosine (input in radians), log and exp (natural logarithm),
+square root.
B<ATAN>
-Arctangent. Output in radians.
+Arctangent (output in radians).
B<FLOOR, CEIL>
-Round down,up to the nearest integer
+Round down or up to the nearest integer.
Z<>
(or reversed) in place on the stack.
Example: C<CDEF:x=v1,v2,v3,v4,v5,v6,6,SORT,POP,5,REV,POP,+,+,+,4,/> will
-compute the average of the values v1..v6 after removing the smallest and
+compute the average of the values v1 to v6 after removing the smallest and
largest.
B<TREND>
<--------------->
- Value at sample (t0) will be the average between (t0-delay) and (t0)
- Value at sample (t1) will be the average between (t1-delay) and (t1)
- Value at sample (t2) will be the average between (t2-delay) and (t2)
+ Value at sample (t0) will be the average between (t0-delay) and (t0)
+ Value at sample (t1) will be the average between (t1-delay) and (t1)
+ Value at sample (t2) will be the average between (t2-delay) and (t2)
=item Special values
B<PREV(vname)>
Pushes an I<unknown> value if this is the first value of a data
-set or otherwise the result of vname variable at the previous time
-step. This allows you to do calculations across the data. This
+set or otherwise the result of the vname variable at the previous time
+step. This allows you to do calculations across the data. This
function cannot be used in B<VDEF> instructions.
B<COUNT>
Pushes the number 1 if this is the first value of the data set, the
-number 2 if it is the second, and so on. This special value, allows
+number 2 if it is the second, and so on. This special value allows
you to make calculations based on the position of the value within
the data set. This function cannot be used in B<VDEF> instructions.
=item Time
-Time inside RRDtool is measured in seconds since the epoch. This
+Time inside RRDtool is measured in seconds since the epoch. The
epoch is defined to be S<C<Thu Jan 1 00:00:00 UTC 1970>>.
B<NOW>
B<TIME>
-Pushes the time the currently processed value was taken onto the stack.
+Pushes the time the currently processed value was taken at onto the stack.
B<LTIME>
Takes the time as defined by B<TIME>, applies the time zone offset
valid at that time including daylight saving time if your OS supports
it, and pushes the result on the stack. There is an elaborate example
-in the examples section on how to use this.
+in the examples section below on how to use this.
=item Processing the stack directly
=item LAST, FIRST
-Return the last,first value including its time. The time for
-FIRST is actually the start of the corresponding interval, where
-the LAST time component returns the end of the corresponding interval.
+Return the last/first value including its time. The time for
+FIRST is actually the start of the corresponding interval, whereas
+LAST returns the end of the corresponding interval.
Example: C<VDEF:first=mydata,FIRST>
=item TOTAL
Returns the rate from each defined time slot multiplied with the
-step size. This can for instance return total bytes transfered
+step size. This can, for instance, return total bytes transfered
when you have logged bytes per second. The time component returns
-the amount of seconds
+the number of seconds.
Example: C<VDEF:total=mydata,TOTAL>
=item PERCENT
-Should follow a B<DEF> or B<CDEF> I<vname>. This I<vname> is popped,
+This should follow a B<DEF> or B<CDEF> I<vname>. The I<vname> is popped,
another number is popped which is a certain percentage (0..100). The
data set is then sorted and the value returned is chosen such that
I<percentage> percent of the values is lower or equal than the result.
=head1 SEE ALSO
L<rrdgraph> gives an overview of how B<rrdtool graph> works.
-L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail,
-L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements,
+L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail.
+L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements.
L<rrdgraph_graph> page describes all of the graph and print functions.
Make sure to read L<rrdgraph_examples> for tipsE<amp>tricks.
It is pretty easy to gather status information from all sorts of
things, ranging from the temperature in your office to the number of
octets which have passed through the FDDI interface of your
-router. But it is not so trivial to store this data in a efficient and
-systematic manner. This is where B<RRDtool> kicks in. It lets you
+router. But it is not so trivial to store this data in an efficient and
+systematic manner. This is where B<RRDtool> comes in handy. It lets you
I<log and analyze> the data you gather from all kinds of data-sources
(B<DS>). The data analysis part of RRDtool is based on the ability to
quickly generate graphical representations of the data values
In this man page you will find general information on the design and
functionality of the Round Robin Database Tool (RRDtool). For a more
-detailed description of how to use the individual functions of the
+detailed description of how to use the individual functions of
B<RRDtool> check the corresponding man page.
-For an introduction to the usage of RRDtool make sure you check L<rrdtutorial>.
+For an introduction to the usage of RRDtool make sure you consult the
+L<rrdtutorial>.
=head2 FUNCTIONS
While the man pages talk of command line switches you have to set in
-order to make B<RRDtool> work it is important to note that the
+order to make B<RRDtool> work it is important to note that
B<RRDtool> can be remotely controlled through a set of pipes. This
saves a considerable amount of startup time when you plan to make
B<RRDtool> do a lot of things quickly. Check the section on L<"Remote
Control"> further down. There is also a number of language bindings
for RRDtool which allow you to use it directly from perl, python, tcl,
-php, ...
+php, etc.
=over 8
=item B<updatev>
-Operation equivalent to B<update> except for output. Check L<rrdupdate>.
+Operationally equivalent to B<update> except for output. Check L<rrdupdate>.
=item B<graph>
-Create a graph from data stored in one or several RRD. Apart from
+Create a graph from data stored in one or several RRDs. Apart from
generating graphs, data can also be extracted to stdout. Check L<rrdgraph>.
=item B<dump>
-Dump the contents of an RRD in plain ASCII. In connection with
-restore you can use it to transport an RRD from one architecture to another.
-Check L<rrddump>.
+Dump the contents of an RRD in plain ASCII. In connection with restore
+you can use this to move an RRD from one computer architecture to
+another. Check L<rrddump>.
=item B<restore>
-Restore an RRD in XML format to a binary RRD ... Check L<rrdrestore>
+Restore an RRD in XML format to a binary RRD. Check L<rrdrestore>
=item B<fetch>
=item B<last>
-Find last update time of an RRD. Check L<rrdlast>.
+Find the last update time of an RRD. Check L<rrdlast>.
=item B<info>
=item B<rrdresize>
-Change the size of individual RRAs ... Dangerous! Check L<rrdresize>.
+Change the size of individual RRAs. This is dangerous! Check L<rrdresize>.
=item B<xport>
-Export data retrieved from one or several RRD. Check L<rrdxport>
+Export data retrieved from one or several RRDs. Check L<rrdxport>
=item B<rrdcgi>
=over 8
-=item Data acquisition
+=item Data Acquisition
When monitoring the state of a system, it is convenient to have the
-data available at a constant interval. Unfortunately you may not
+data available at a constant time interval. Unfortunately, you may not
always be able to fetch data at exactly the time you want
to. Therefore B<RRDtool> lets you update the logfile at any time you
want. It will automatically interpolate the value of the data-source
-(B<DS>) at the latest official time-slot and write this value to the
-log. The value you have supplied is stored as well and is also taken
-into account when interpolating the next log entry.
+(B<DS>) at the latest official time-slot (intervall) and write this
+interpolated value to the log. The original value you have supplied is
+stored as well and is also taken into account when interpolating the
+next log entry.
=item Consolidation
-You may log data at a 1 minute interval, but you are also be
+You may log data at a 1 minute interval, but you might also be
interested to know the development of the data over the last year. You
-could do this by simply storing the data in 1 minute interval, for one
-year. While this would take considerable disk space it would also take
-a lot of time to analyze the data when you wanted to create a graph
-covering the whole year. B<RRDtool> offers a solution to this of this
-problem through its data consolidation feature. When setting up
-an Round Robin Database (B<RRD>), you can define at which interval
-this consolidation should occur, and what consolidation function
-(B<CF>) (average, minimum, maximum, total, last) should be used to
-build the consolidated values (see rrdcreate). You can define any
-number of different consolidation setups within one B<RRD>. They will
-all be maintained on the fly when new data is loaded into the B<RRD>.
+could do this by simply storing the data in 1 minute intervals for the
+whole year. While this would take considerable disk space it would
+also take a lot of time to analyze the data when you wanted to create
+a graph covering the whole year. B<RRDtool> offers a solution to this
+problem through its data consolidation feature. When setting up an
+Round Robin Database (B<RRD>), you can define at which interval this
+consolidation should occur, and what consolidation function (B<CF>)
+(average, minimum, maximum, total, last) should be used to build the
+consolidated values (see rrdcreate). You can define any number of
+different consolidation setups within one B<RRD>. They will all be
+maintained on the fly when new data is loaded into the B<RRD>.
=item Round Robin Archives
Data values of the same consolidation setup are stored into Round
Robin Archives (B<RRA>). This is a very efficient manner to store data
-for a certain amount of time, while using a known amount of storage
-space.
-
-It works like this: If you want to store 1000 values in 5 minute
-interval, B<RRDtool> will allocate space for 1000 data values and a
-header area. In the header it will store a pointer telling
-which one of the values in the storage area was last written to. New
-values are written to the Round Robin Archive in a ... you guess it
-... round robin manner. This automatically limits the history to the last
-1000 values. Because you can define several B<RRA>s within a single B<RRD>,
-you can setup another one, storing 750 data values at a 2 hour interval
-and thus keeping a log for the last two months although at a lower
-resolution.
+for a certain amount of time, while using a known and constant amount
+of storage space.
+
+It works like this: If you want to store 1'000 values in 5 minute
+interval, B<RRDtool> will allocate space for 1'000 data values and a
+header area. In the header it will store a pointer telling which slots
+(value) in the storage area was last written to. New values are
+written to the Round Robin Archive in, you guessed it, a round robin
+manner. This automatically limits the history to the last 1'000 values
+(in our example). Because you can define several B<RRA>s within a
+single B<RRD>, you can setup another one, for storing 750 data values
+at a 2 hour interval, for example, and thus keep a log for the last
+two months at a lower resolution.
The use of B<RRA>s guarantees that the B<RRD> does not grow over
time and that old data is automatically eliminated. By using the
consolidation feature, you can still keep data for a very long time,
while gradually reducing the resolution of the data along the time
-axis. Using different consolidation functions (B<CF>) allows you to
-store exactly the type of information that actually interests
-you. (Maximum one minute traffic on the LAN, minimum temperature of
-the wine cellar, total minutes down time ...)
+axis.
+
+Using different consolidation functions (B<CF>) allows you to store
+exactly the type of information that actually interests you: the maximum
+one minute traffic on the LAN, the minimum temperature of your wine cellar,
+the total minutes of down time, etc.
=item Unknown Data
As mentioned earlier, the B<RRD> stores data at a constant
-interval. Now it may happen that no new data is available when a
+interval. Sometimes it may happen that no new data is available when a
value has to be written to the B<RRD>. Data acquisition may not be
-possible for one reason or an other. The B<RRDtool> handles these
+possible for one reason or other. With B<RRDtool> you can handle these
situations by storing an I<*UNKNOWN*> value into the database. The
value 'I<*UNKNOWN*>' is supported through all the functions of the
-database. When consolidating the amount of I<*UNKNOWN*> data is
-accumulated and when a new consolidated value is ready to be written
-to its Round Robin Archive (B<RRA>) a validity check is performed to
-make sure that the percentage of unknown data in the new value is
-below a configurable level. If so, an I<*UNKNOWN*> value will be
-written to the B<RRA>.
+tool. When consolidating a data set, the amount of I<*UNKNOWN*> data
+values is accounted for and when a new consolidated value is ready to
+be written to its Round Robin Archive (B<RRA>), a validity check is
+performed to make sure that the percentage of unknown values in the
+data point is above a configurable level. If not, an I<*UNKNOWN*> value
+will be written to the B<RRA>.
=item Graphing
-The B<RRDtool> also allows one to generate reports in numerical and
+B<RRDtool> allows you to generate reports in numerical and
graphical form based on the data stored in one or several
B<RRD>s. The graphing feature is fully configurable. Size, color and
contents of the graph can be defined freely. Check L<rrdgraph>
by Jake Brutlag E<lt>jakeb@corp.webtv.netE<gt>
-The B<RRDtool> also provides the building blocks for near real-time
-aberrant behavior detection. These components include:
+B<RRDtool> provides the building blocks for near real-time aberrant
+behavior detection. These components include:
=over 12
=item *
-An algorithm for predicting the values time series one time step into the future.
+An algorithm for predicting the value of a time series one time step
+into the future.
=item *
-A measure of deviation between the predicted values and the observed values.
+A measure of deviation between predicted and observed values.
=item *
-A mechanism to decide if and when an observed value
-or sequence of observed values is I<too deviant> from the predicted value(s).
+A mechanism to decide if and when an observed value or sequence of
+observed values is I<too deviant> from the predicted value(s).
=back
-Each of these components is briefly described:
-
-Holt-Winters Time Series forecasting algorithm is an on-line, or incremental,
-algorithm that adaptively predicts future observations in a time series. It's
-forecast is the sum of three components: a baseline (or intercept), a linear
-trend over time (or slope), and a seasonal coefficient (a periodic effect,
-such as a daily cycle). There is one seasonal coefficient for each time point
-in the period (cycle). After a value is observed, each of these components is
-updated via exponential smoothing. So the algorithm learns from past values
-and uses them to predict the future. The rate of adaptation is governed by
-3 parameters, alpha (intercept), beta (slope), and gamma (seasonal). The prediction
-can also be viewed as a smoothed value for the time series.
-
-The measure of deviation is a seasonal weighted absolute deviation. The term
-I<seasonal> means deviation is measured separately for each time point in the
-seasonal cycle. As with Holt-Winters forecasting, deviation is predicted using
-the measure computed from past values (but only at that point in the seasonal cycle).
-After the value is observed, the algorithm learns from the observed value via
-exponential smoothing. Confidence bands for the observed time series are generated
-by scaling the sequence of predicted deviation values (we usually think of the sequence
-as a continuous line rather than a set of discrete points).
-
-Aberrant behavior (a potential failure) is reported whenever the number of
-times the observed value violates the confidence bands meets or exceeds a
-specified threshold within a specified temporal window (i.e. 5 violations
-during the past 45 minutes with a value observed every 5 minutes).
-
-This functionality is embedded in a set of related B<RRAs>. In particular, a FAILURES
-B<RRA> logs potential failures. Presumably a front-end application to B<RRDtool> can
-utilize this B<RRA> to initiate real-time alerts if that is desired.
-
-You can find a detailed description of how to set this up in L<rrdcreate>.
+Here is a brief explanation of these components:
+
+The Holt-Winters time series forecasting algorithm is an on-line (or
+incremental) algorithm that adaptively predicts future observations in
+a time series. Its forecast is the sum of three components: a baseline
+(or intercept), a linear trend over time (or slope), and a seasonal
+coefficient (a periodic effect, such as a daily cycle). There is one
+seasonal coefficient for each time point in the period (cycle). After
+a value is observed, each of these components is updated via
+exponential smoothing. This means that the algorithm "learns" from
+past values and uses them to predict the future. The rate of
+adaptation is governed by 3 parameters, alpha (intercept), beta
+(slope), and gamma (seasonal). The prediction can also be viewed as a
+smoothed value for the time series.
+
+The measure of deviation is a seasonal weighted absolute
+deviation. The term I<seasonal> means deviation is measured separately
+for each time point in the seasonal cycle. As with Holt-Winters
+forecasting, deviation is predicted using the measure computed from
+past values (but only at that point in the seasonal cycle). After the
+value is observed, the algorithm learns from the observed value via
+exponential smoothing. Confidence bands for the observed time series
+are generated by scaling the sequence of predicted deviation values
+(we usually think of the sequence as a continuous line rather than a
+set of discrete points).
+
+Aberrant behavior (a potential failure) is reported whenever the
+number of times the observed value violates the confidence bands meets
+or exceeds a specified threshold within a specified temporal window
+(e.g. 5 violations during the past 45 minutes with a value observed
+every 5 minutes).
+
+This functionality is embedded in a set of related B<RRAs>. In
+particular, a FAILURES B<RRA> logs potential failures. With these data
+you could, for example, use a front-end application to B<RRDtool> to
+initiate real-time alerts.
+
+For a detailed description on how to set this up, see L<rrdcreate>.
=back
=head2 REMOTE CONTROL
-When you start B<RRDtool> with the command line option 'B<->', it waits
-for input via standard in. With this feature you can improve
-performance by attaching B<RRDtool> to another process (MRTG is one
-example) through a set of pipes. Over the pipes B<RRDtool> accepts the
-same arguments as on the command line and some special commands like
-B<quit, cd, mkdir> and B<ls>. For detail helps about the server commands
-type :
+When you start B<RRDtool> with the command line option 'B<->' it waits
+for input via standard input (STDIN). With this feature you can
+improve performance by attaching B<RRDtool> to another process (MRTG
+is one example) through a set of pipes. Over these pipes B<RRDtool>
+accepts the same arguments as on the command line and some special
+commands like B<quit, cd, mkdir> and B<ls>. For detailed help on the
+server commands type:
rrdtool help cd|mkdir|ls|quit
When a command is completed, RRDtool will print the string 'C<OK>',
followed by timing information of the form B<u:>I<usertime>
-B<s:>I<systemtime> both values are running totals of seconds
+B<s:>I<systemtime>. Both values are the running totals of seconds
since RRDtool was started. If an error occurs, a line of the
form 'C<ERROR:> I<Description of error>' will be printed. B<RRDtool>
-will not abort if possible, but follow the ERROR line with an OK line.
+will not abort, if possible, but follow the ERROR line with an OK line.
If a B<workdir> is specified and the UID is 0, RRDtool will do a
-chroot to the workdir. If the UID is not 0, RRDtool only changes the
+chroot to that workdir. If the UID is not 0, RRDtool only changes the
current directory to B<workdir>.
=head2 RRD Server
rrdsrv 13900/tcp # RRD server
-Attention: the TCP port 13900 isn't official registered for rrdsrv. You
-can use any unused port in your services, but the server an the client
-system must use the same port of curse.
-After this you can add the RRDtool as meta-server to I</etc/inetd.conf>
-for example:
+Attention: the TCP port 13900 isn't officially registered for
+rrdsrv. You can use any unused port in your services file, but the
+server and the client system must use the same port, of course.
+
+With this configuration you can add RRDtool as meta-server to
+I</etc/inetd.conf>. For example:
rrdsrv stream tcp nowait root /opt/rrd/bin/rrdtool rrdtool - /var/rrd
-Don't forget to create the database directory /var/rrd and reinitialize
-your inetd.
-If all was correct, you can access the server with perl sockets, tools
-like netcat or a quick test 'telnet localhost rrdsrv'.
+Don't forget to create the database directory /var/rrd and
+reinitialize your inetd.
+If all was setup correctly, you can access the server with perl
+sockets, tools like netcat, or in a quick interactive test by using
+'telnet localhost rrdsrv'.
=head1 SEE ALSO
=head1 BUGS
-Bugs ? Features !
+Bugs? Features!
=head1 AUTHOR
=item S<B<--heartbeat>|B<-h> I<ds-name>:I<heartbeat>>
modify the I<heartbeat> of a data source. By setting this to a high
-value the RRD will accept things like one value per day ...
+value the RRD will accept things like one value per day.
=item S<B<--minimum>|B<-i> I<ds-name>:I<min>>
=item S<B<--data-source-rename>|B<-r> I<old-name>:I<new-name>>
-rename a data source
+rename a data source.
=item S<B<--deltapos> I<scale-value>>
-Alter the deviation scaling factor for the upper bound of the confidence band
-used internally to calculate violations for the FAILURES B<RRA>. The default
-value is 2. Note that this parameter is not related to graphing confidence
-bounds, that scale factor must be specified as a CDEF argument to generate
-a graph with confidence bounds. The graph scale factor need not agree with the
-value used internally by the FAILURES B<RRA>.
+Alter the deviation scaling factor for the upper bound of the
+confidence band used internally to calculate violations for the
+FAILURES B<RRA>. The default value is 2. Note that this parameter is
+not related to graphing confidence bounds which must be specified as a
+CDEF argument to generate a graph with confidence bounds. The graph
+scale factor need not to agree with the value used internally by the
+FAILURES B<RRA>.
=item S<B<--deltaneg> I<scale-value>>
=item S<B<--window-length> I<window-length>>
-Alter the number of time points in the temporal window for determining failures.
-This must be an integer greater than or equal to the window length of the
-FAILURES B<RRA> and less than or equal to 28. Setting this option will reset the
-count of violations to 0.
+Alter the number of time points in the temporal window for determining
+failures. This must be an integer greater than or equal to the window
+length of the FAILURES B<RRA> and less than or equal to 28. Setting
+this option will reset the count of violations to 0.
=item S<B<--alpha> I<adaption-parameter>>
-Alter the intercept adaptation parameter for the Holt-Winters forecasting algorithm.
-Must be between 0 and 1.
+Alter the intercept adaptation parameter for the Holt-Winters
+forecasting algorithm. This parameter must be between 0 and 1.
=item S<B<--beta> I<adaption-parameter>>
-Alter the slope adaptation parameter for the Holt-Winters forecasting algorithm.
-Must be between 0 and 1.
+Alter the slope adaptation parameter for the Holt-Winters forecasting
+algorithm. This parameter must be between 0 and 1.
=item S<B<--gamma> I<adaption-parameter>>
Alter the seasonal coefficient adaptation parameter for the SEASONAL
-B<RRA>. Must be between 0 and 1.
+B<RRA>. This parameter must be between 0 and 1.
=item S<B<--gamma-deviation> I<adaption-parameter>>
Alter the seasonal deviation adaptation parameter for the DEVSEASONAL
-B<RRA>. Must be between 0 and 1.
+B<RRA>. This parameter must be between 0 and 1.
=item S<B<--aberrant-reset> I<ds-name>>
This option causes the aberrant behavior detection algorithm to reset
-for the specified data source; that is, forget all it is has learn.
+for the specified data source; that is, forget all it is has learnt so far.
Specifically, for the HWPREDICT B<RRA>, it sets the intercept and slope
coefficients to unknown. For the SEASONAL B<RRA>, it sets all seasonal
coefficients to unknown. For the DEVSEASONAL B<RRA>, it sets all seasonal
C<rrdtool tune data.rrd -h in:100000 -h out:100000 -h through:100000>
Set the minimum required heartbeat for data sources 'in', 'out'
-and 'through' to 10000 seconds which is a little over one day in data.rrd.
+and 'through' to 10'000 seconds which is a little over one day in data.rrd.
This would allow to feed old data from MRTG-2.0 right into
RRDtool without generating *UNKNOWN* entries.
C<rrdtool tune monitor.rrd --window-length 5 --failure-threshold 3>
-If the FAILURES B<RRA> is implicitly created, the default window-length is 9 and
-the default failure-threshold is 7. This command now defines a failure as 3 or more
-violations in a temporal window of 5 time points.
+If the FAILURES B<RRA> is implicitly created, the default
+window-length is 9 and the default failure-threshold is 7. This
+command now defines a failure as 3 or more violations in a temporal
+window of 5 time points.
=head1 AUTHOR
get used to that right away. Assume a byte is eight bits and start to
think in bits not bytes. The counter, however, still counts bytes!
In the SNMP world most of the counters are 32 bits. That means they are
-counting from 0 to 4294967295. We will use these values in the examples.
+counting from 0 to 4'294'967'295. We will use these values in the examples.
The device, when asked, returns the current value of the counter. We
know the time that has passes since we last asked so we now know how
many bytes have been transfered ***on average*** per second. This is
I will use the following abbreviations:
M: meter
- KM: kilometer (= 1000 meters).
+ KM: kilometer (= 1'000 meters).
H: hour
S: second
KM/H: kilometers per hour
M/S: meters per second
You are driving a car. At 12:05 you read the counter in the dashboard
-and it tells you that the car has moved 12345 KM until that moment.
-At 12:10 you look again, it reads 12357 KM. This means you have
+and it tells you that the car has moved 12'345 KM until that moment.
+At 12:10 you look again, it reads 12'357 KM. This means you have
traveled 12 KM in five minutes. A scientist would translate that
into meters per second and this makes a nice comparison toward the
problem of (bytes per five minutes) versus (bits per second).
-We traveled 12 kilometers which is 12000 meters. We did that in five
-minutes or 300 seconds. Our speed is 12000M / 300S or 40 M/S.
+We traveled 12 kilometers which is 12'000 meters. We did that in five
+minutes or 300 seconds. Our speed is 12'000M / 300S or 40 M/S.
We could also calculate the speed in KM/H: 12 times 5 minutes
is an hour, so we have to multiply 12 KM by 12 to get 144 KM/H.
I hope you understand that there is no difference in calculating M/S or
bps; only the way we collect the data is different. Even the K from kilo
-is the same as in networking terms k also means 1000.
+is the same as in networking terms k also means 1'000.
We will now create a database where we can keep all these interesting
numbers. The method used to start the program may differ slightly from
We created the round robin database called test (test.rrd) which
starts at noon the day I started writing this document, 7th of March,
-1999 (this date translates to 920804400 seconds as explained
+1999 (this date translates to 920'804'400 seconds as explained
below). Our database holds one data source (DS) named "speed" that
represents a counter. This counter is read every five minutes
(default). In the same database two round robin archives (RRAs) are
The vertical axis displays the range we entered. We provided
kilometers and when divided by 300 seconds, we get very small
-numbers. To be exact, the first value was 12 (12357-12345) and divided
+numbers. To be exact, the first value was 12 (12'357-12'345) and divided
by 300 this makes 0.04, which is displayed by RRDtool as "40 m"
-meaning "40/1000". The "m" (milli) has nothing to do with meters,
+meaning "40/1'000". The "m" (milli) has nothing to do with meters,
kilometers or millimeters! RRDtool doesn't know about the physical
units of our data, it just works with dimensionless numbers.
If we had measured our distances in meters, this would have been
-(12357000-12345000)/300 = 12000/300 = 40.
+(12'357'000-12'345'000)/300 = 12'000/300 = 40.
As most people have a better feel for numbers in this range, we'll
correct that. We could recreate our database and store the correct
more detail. Also, you may want to read my tutorial on CDEFs and Steve
Rader's tutorial on RPN. But first finish this tutorial.
-Hang on! If we can multiply values with 1000, it should also be possible
+Hang on! If we can multiply values with 1'000, it should also be possible
to display kilometers per hour from the same data!
=for comment
XXX strange format below: -*- ; Fritz
To change a value that is measured in meters per second:
- -*- Calculate meters per hour: value * 3600
- -*- Calculate kilometers per hour: value / 1000
- -*- Together this makes: value * (3600/1000) or value * 3.6
+ -*- Calculate meters per hour: value * 3'600
+ -*- Calculate kilometers per hour: value / 1'000
+ -*- Together this makes: value * (3'600/1'000) or value * 3.6
In our example database we made a mistake and we need to compensate for
-this by multiplying with 1000. Applying that correction:
- -*- value * 3.6 *1000 == value * 3600
+this by multiplying with 1'000. Applying that correction:
+ -*- value * 3.6 * 1'000 == value * 3'600
Now let's create this PNG, and add some more magic ...
LINE1:outoctets#0000FF:"Out traffic"
This should produce a picture with one day worth of traffic.
-One day is 24 hours of 60 minutes of 60 seconds: 24*60*60=86400, we
-start at now minus 86400 seconds. We define (with DEFs) inoctets and
+One day is 24 hours of 60 minutes of 60 seconds: 24*60*60=86'400, we
+start at now minus 86'400 seconds. We define (with DEFs) inoctets and
outoctets as the average values from the database myrouter.rrd and draw
an area for the "in" traffic and a line for the "out" traffic.
counter with one difference: RRDtool assumes the counter is reset when
it's read. That is: its delta is known without calculation by RRDtool
whereas RRDtool needs to calculate it for the counter type.
-Example: our first example (12345, 12357, 12363, 12363) would read:
+Example: our first example (12'345, 12'357, 12'363, 12'363) would read:
unknown, 12, 6, 0. The rest of the calculations stay the same.
The other one, derive, is like counter. Unlike counter, it can also
decrease so it can have a negative delta. Again, the rest of the
=item *
Line C is of type DERIVE. It should be a counter that can decrease. It does
-so between 2400 and 0, with 1800 in-between.
+so between 2'400 and 0, with 1'800 in-between.
=item *
=head1 DESCRIPTION
-The B<update> function feeds new data values into an B<RRD>. The
-data gets time aligned according to the properties of the B<RRD> to
-which the data is written.
+The B<update> function feeds new data values into an B<RRD>. The data
+is time aligned (interpolated) according to the properties of the
+B<RRD> to which the data is written.
=over 8
=item B<--template>|B<-t> I<ds-name>[B<:>I<ds-name>]...
-by default, the B<update> function expects the data input in the order
-the data sources are defined in the RRD, excluding any COMPUTE data sources
-(i.e. if the third data source B<DST> is COMPUTE, the third input value
-will be mapped to the fourth data source in the B<RRD>). This is not very
-error resistant, as you might be sending the wrong data into a RRD.
+By default, the B<update> function expects its data input in the order
+the data sources are defined in the RRD, excluding any COMPUTE data
+sources (i.e. if the third data source B<DST> is COMPUTE, the third
+input value will be mapped to the fourth data source in the B<RRD> and
+so on). This is not very error resistant, as you might be sending the
+wrong data into an RRD.
The template switch allows you to specify which data sources you are
going to update and in which order. If the data sources specified in
asynchronously, B<RRDtool> implicitly assigns non-COMPUTE data sources missing
from the template the I<*UNKNOWN*> value.
-Do not specify a value for a COMPUTE B<DST> in the B<update> function. If
-this is done accidentally (and this can only be done using the template switch),
-B<RRDtool> will ignore the value specified for the COMPUTE B<DST>.
+Do not specify a value for a COMPUTE B<DST> in the B<update>
+function. If this is done accidentally (and this can only be done
+using the template switch), B<RRDtool> will ignore the value specified
+for the COMPUTE B<DST>.
=item B<N>|I<timestamp>B<:>I<value>[B<:>I<value>...]
-The data used for updating the RRD was acquired at a certain time. This
-time can either be defined in seconds since 1970-01-01. Or by using the
-letter 'N' the update time is set to be the current time. Negative time
-values are subtracted from the current time.
-An AT_STYLE TIME SPECIFICATION (see the I<rrdfetch> documentation) may
-also be used by delimiting the end of the time specification with the '@' character
-instead of a ':'.
-Getting the timing right to the second is especially
-important when you are working with data-sources of type B<COUNTER>,
-B<DERIVE> or B<ABSOLUTE>.
-
-The remaining elements of the argument are DS updates. The order of this list is
-the same as the order the data sources were defined in the RRA.
-If there is no data for a certain data-source, the letter
-B<U> (e.g., N:0.1:U:1) can be defined.
-
-The format of the value acquired from the data source is dependent of the
-data source type chosen. Normally it will be numeric, but the data acquisition
-modules may impose their very own parsing of this parameter as long as the colon
-(B<:>) remains the data source value separator.
+The data used for updating the RRD was acquired at a certain
+time. This time can either be defined in seconds since 1970-01-01 or
+by using the letter 'N', in which case the update time is set to be
+the current time. Negative time values are subtracted from the current
+time. An AT_STYLE TIME SPECIFICATION (see the I<rrdfetch>
+documentation) may also be used by delimiting the end of the time
+specification with the '@' character instead of a ':'. Getting the
+timing right to the second is especially important when you are
+working with data-sources of type B<COUNTER>, B<DERIVE> or
+B<ABSOLUTE>.
+
+The remaining elements of the argument are DS updates. The order of
+this list is the same as the order the data sources were defined in
+the RRA. If there is no data for a certain data-source, the letter
+B<U> (e.g., N:0.1:U:1) can be specified.
+
+The format of the value acquired from the data source is dependent on
+the data source type chosen. Normally it will be numeric, but the data
+acquisition modules may impose their very own parsing of this
+parameter as long as the colon (B<:>) remains the data source value
+separator.
=back
Update the database file demo2.rrd which expects data from a single
data-source, three times. First with an I<*UNKNOWN*> value then with two
-normal readings. The update interval seems to be around 300 seconds.
+regular readings. The update interval seems to be around 300 seconds.
=head1 AUTHOR
=head1 DESCRIPTION
-The B<xport> functions main purpose is to write XML formatted
+The B<xport> function's main purpose is to write an XML formatted
representation of the data stored in one or several B<RRD>s. It
can also extract numerical reports.
=head1 Output format
-The output is enclosed in a B<xport> element and contains two
+The output is enclosed in an B<xport> element and contains two
blocks. The first block is enclosed by a B<meta> element and
contains some meta data. The second block is enclosed by a
B<data> element and contains the data rows.
XPORT:xx:"out bytes" \
XPORT:aa:"in and out bits"
-The resulting meta data section (the values will depend on the
+The resulting meta data section is (the values will depend on the
RRD characteristics):
<meta>
</legend>
</meta>
-The resulting data section:
+The resulting data section is:
<data>
<row><t>1020611700</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
projects / rrdtool.git / commitdiff