Added some documentation for the rrdxport output format

See https://github.com/oetiker/rrdtool-1.x/issues/913 for a discussion

diff --git a/doc/Makefile.in b/doc/Makefile.in
index ff7694740673c61e59b2b4bb2b43efcb776343da..6fed7c7af51d82c135de632a4d4d3c148d3663db 100644 (file)
--- a/doc/Makefile.in
+++ b/doc/Makefile.in
@@ -376,6 +376,7 @@ POD = bin_dec_hex.pod rrddump.pod rrdgraph_examples.pod rrdrestore.pod \
        rrdinfo.pod rrdtune.pod rrdbuild.pod rrdflushcached.pod \
        rrdcgi.pod rrdgraph.pod rrdlast.pod rrdlastupdate.pod \
        rrdcreate.pod rrdgraph_data.pod rrdresize.pod rrdtutorial.pod \
+       PDP_calculation_explanation.pod \
        rrdlist.pod $(am__append_1) $(am__append_2) $(am__append_3)
 POD3 = librrd.pod
 PMP = RRDs.pod RRDp.pod

diff --git a/doc/rrdgraph.pod b/doc/rrdgraph.pod
index 360515cee42269c2ae8bd4cba0295a9d83c36af3..71ee3d851953a6acfbabd1f9f84042047911c1bd 100644 (file)
--- a/doc/rrdgraph.pod
+++ b/doc/rrdgraph.pod
@@ -82,6 +82,9 @@ If you want B<rrdtool graph> to get data at a one-hour resolution
 from the B<RRD>, set B<step> to 3'600. Note: a step smaller than
 one pixel will silently be ignored.
 
+For non-image B<--imgformat>s see L<rrdxport/"OUTPUT FORMAT"> for details on how
+this affects the output.
+
 =head2 Labels
 
 [B<-t>|B<--title> I<string>]
@@ -529,6 +532,9 @@ JSON, JSONTIME (adds a timestamp to each data row),
 CSV (=comma separated values), TSV (=tab separated values), SSV (=semicolon separated values),
 (for comma/tab/semicolon separated values the time format by default is in the form of unix time. to change it to something else use: --x-grid MINUTE:10:HOUR:1:HOUR:4:0:"%Y-%m-%d %H:%M:%S")
 
+For non-image B<--imgformat>s see L<rrdxport/"OUTPUT FORMAT"> for details on
+the output.
+
 [B<-i>|B<--interlaced>]
 
 (this gets ignored in 1.3 for now!)

diff --git a/doc/rrdxport.pod b/doc/rrdxport.pod
index 86bf0ada0ddd54bb71db0c863daaca092f863853..cc7dde5606630d35fd88090b3fdd0b46aabe0349 100644 (file)
--- a/doc/rrdxport.pod
+++ b/doc/rrdxport.pod
@@ -35,12 +35,16 @@ current time. By default one day worth of data will be printed.
 See also L<rrdfetch/"AT-STYLE TIME SPECIFICATION"> for a detailed explanation
 on how to specify time.
 
+See L<"OUTPUT FORMAT"> below for details on how this affects the output.
+
 =item B<-e>|B<--end> I<seconds> (default now)
 
 The time when the exported range should end. Time in seconds since epoch.
 See also L<rrdfetch/"AT-STYLE TIME SPECIFICATION"> for a detailed explanation
 on how to specify time.
 
+See L<"OUTPUT FORMAT"> below for details on how this affects the output.
+
 =item B<-m>|B<--maxrows> I<rows> (default 400 rows)
 
 This works like the B<-w>|B<--width> parameter of I<rrdgraph>.
@@ -90,7 +94,7 @@ referenced by I<vname> are printed. Optionally add a legend.
 
 =back
 
-=head1 Output format
+=head1 OUTPUT FORMAT
 
 The output is enclosed in an B<xport> element and contains two
 blocks. The first block is enclosed by a B<meta> element and
@@ -141,6 +145,33 @@ The resulting data section is:
     <row><t>1020615600</t><v>NaN</v><v>NaN</v></row>
   </data>
 
+All the statistics in the output will use the same step. The first sample will
+be the first sample starting at or immediately after B<--start>. The last
+sample will be the one ending at or immediately after B<--end>.
+
+Each sample has a timestamp and one or more values. The timestamps associated
+with a value in rrdtool ALWAYS represent the time the sample was taken. Since
+any value you sample will represent some sort of past state your sampling
+apparatus has gathered, the timestamp will always be at the end of the sampling
+period.
+
+Rrdtool does not store the actual samples, but does internal resampling of the
+values presented to it. Nevertheless when a data value is presented with a
+single timestamp the timestamp is at the end of the period the value
+represents. Note that the timestamp itself is outside the period the sample is
+valid for. For more details about this, see L<PDP calculation
+explanation|PDP_calculation_explanation>.
+
+So the time range for a sample with a timestamp is actually
+C<< [ timestamp - step ; timestamp [ >>.
+
+The first line of the sample output:
+
+    <row><t>1020611700</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
+
+therefore means that the values for the interval 1020611700 to 1020611999 were
+3.4 and 54.4 for "out bytes" and "in and out bits" respectively, as if the
+value was taken at 1020612000.
 
 =head1 EXAMPLE 1