From: Peter Valdemar Mørch Date: Thu, 3 Jan 2019 20:35:38 +0000 (+0100) Subject: Added some documentation for the rrdxport output format X-Git-Tag: v1.7.1~28 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=013bc858e6d2a02bda35d339e84e6c79627af0d5;p=thirdparty%2Frrdtool-1.x.git 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 ff769474..6fed7c7a 100644 --- 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 360515ce..71ee3d85 100644 --- a/doc/rrdgraph.pod +++ b/doc/rrdgraph.pod @@ -82,6 +82,9 @@ If you want B to get data at a one-hour resolution from the B, set B to 3'600. Note: a step smaller than one pixel will silently be ignored. +For non-image B<--imgformat>s see L for details on how +this affects the output. + =head2 Labels [B<-t>|B<--title> I] @@ -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 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 86bf0ada..cc7dde56 100644 --- 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 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 (default now) The time when the exported range should end. Time in seconds since epoch. See also L 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 (default 400 rows) This works like the B<-w>|B<--width> parameter of I. @@ -90,7 +94,7 @@ referenced by I are printed. Optionally add a legend. =back -=head1 Output format +=head1 OUTPUT FORMAT The output is enclosed in an B element and contains two blocks. The first block is enclosed by a B element and @@ -141,6 +145,33 @@ The resulting data section is: 1020615600NaNNaN +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. + +So the time range for a sample with a timestamp is actually +C<< [ timestamp - step ; timestamp [ >>. + +The first line of the sample output: + + 10206117003.4000000000e+005.4400000000e+01 + +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