X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=doc%2Frrdgraph.txt;h=8c7717da9689d68f1e8177b692c585770454eb9c;hb=f714466e230f02e941349e0a91164d853a8006f4;hp=dcecb50f3cc5fa2d07f8b449c7800fd2d1335889;hpb=51c3d3fb997c22e1ee828470413f1e84989e1f6c;p=pkg-rrdtool.git diff --git a/doc/rrdgraph.txt b/doc/rrdgraph.txt index dcecb50..8c7717d 100644 --- a/doc/rrdgraph.txt +++ b/doc/rrdgraph.txt @@ -40,14 +40,11 @@ OOVVEERRVVIIEEWW When you are done fetching and processing the data, it is time to graph it (or print it). This ends the rrrrddttooooll ggrraapphh sequence. -OOPPTTIIOONNSS - ggrraapphhvv - This alternate version of ggrraapphh takes the same arguments and performs - the same function. The _v stands for _v_e_r_b_o_s_e, which describes the output - returned. ggrraapphhvv will return a lot of information about the graph using - the same format as rrdtool info (key = value). See the bottom of the - document for more information. + Use ggrraapphhvv instead of ggrraapphh to get detailed information about the graph + geometry and data once it is drawn. See the bottom of the document for + more information. +OOPPTTIIOONNSS _f_i_l_e_n_a_m_e The name and path of the graph to generate. It is recommended to end this in ".png", ".svg" or ".eps", but RRRRDDttooooll does not enforce this. @@ -75,19 +72,6 @@ OOPPTTIIOONNSS A horizontal string at the top of the graph and/or a vertically placed string at the left hand side of the graph. - RRiigghhtt AAxxiiss - [----rriigghhtt--aaxxiiss _s_c_a_l_e::_s_h_i_f_t] [----rriigghhtt--aaxxiiss--llaabbeell _l_a_b_e_l] - - A second axis will be drawn to the right of the graph. It is tied to - the left axis via the scale and shift parameters. You can also define a - label for the right axis. - - [----rriigghhtt--aaxxiiss--ffoorrmmaatt _f_o_r_m_a_t_-_s_t_r_i_n_g] - - By default the format of the axis lables gets determined automatically. - If you want todo this your self, use this option with the same %lf - arguments you know from the PRING and GPRINT commands. - SSiizzee [--ww|----wwiiddtthh _p_i_x_e_l_s] [--hh|----hheeiigghhtt _p_i_x_e_l_s] [--jj|----oonnllyy--ggrraapphh] [--DD|----ffuullll--ssiizzee--mmooddee] @@ -150,100 +134,131 @@ OOPPTTIIOONNSS Gridfitting is turned off for PDF, EPS, SVG output by default. - GGrriidd - X-Axis - [--xx|----xx--ggrriidd _G_T_M::_G_S_T::_M_T_M::_M_S_T::_L_T_M::_L_S_T::_L_P_R::_L_F_M] + XX--AAxxiiss + [--xx|----xx--ggrriidd _G_T_M::_G_S_T::_M_T_M::_M_S_T::_L_T_M::_L_S_T::_L_P_R::_L_F_M] - [--xx|----xx--ggrriidd nnoonnee] + [--xx|----xx--ggrriidd nnoonnee] - The x-axis label is quite complex to configure. If you don't have - very special needs it is probably best to rely on the - autoconfiguration to get this right. You can specify the string - "none" to suppress the grid and labels altogether. + The x-axis label is quite complex to configure. If you don't have very + special needs it is probably best to rely on the autoconfiguration to + get this right. You can specify the string "none" to suppress the grid + and labels altogether. - The grid is defined by specifying a certain amount of time in the - _?_T_M positions. You can choose from "SECOND", "MINUTE", "HOUR", - "DAY", "WEEK", "MONTH" or "YEAR". Then you define how many of these - should pass between each line or label. This pair (_?_T_M_:_?_S_T) needs - to be specified for the base grid (_G_?_?), the major grid (_M_?_?) and - the labels (_L_?_?). For the labels you also must define a precision - in _L_P_R and a _s_t_r_f_t_i_m_e format string in _L_F_M. _L_P_R defines where each - label will be placed. If it is zero, the label will be placed right - under the corresponding line (useful for hours, dates etcetera). - If you specify a number of seconds here the label is centered on - this interval (useful for Monday, January etcetera). + The grid is defined by specifying a certain amount of time in the _?_T_M + positions. You can choose from "SECOND", "MINUTE", "HOUR", "DAY", + "WEEK", "MONTH" or "YEAR". Then you define how many of these should + pass between each line or label. This pair (_?_T_M_:_?_S_T) needs to be + specified for the base grid (_G_?_?), the major grid (_M_?_?) and the labels + (_L_?_?). For the labels you also must define a precision in _L_P_R and a + _s_t_r_f_t_i_m_e format string in _L_F_M. _L_P_R defines where each label will be + placed. If it is zero, the label will be placed right under the + corresponding line (useful for hours, dates etcetera). If you specify + a number of seconds here the label is centered on this interval (useful + for Monday, January etcetera). - --x-grid MINUTE:10:HOUR:1:HOUR:4:0:%X + --x-grid MINUTE:10:HOUR:1:HOUR:4:0:%X - This places grid lines every 10 minutes, major grid lines every - hour, and labels every 4 hours. The labels are placed under the - major grid lines as they specify exactly that time. + This places grid lines every 10 minutes, major grid lines every hour, + and labels every 4 hours. The labels are placed under the major grid + lines as they specify exactly that time. - --x-grid HOUR:8:DAY:1:DAY:1:86400:%A + --x-grid HOUR:8:DAY:1:DAY:1:86400:%A - This places grid lines every 8 hours, major grid lines and labels - each day. The labels are placed exactly between two major grid - lines as they specify the complete day and not just midnight. + This places grid lines every 8 hours, major grid lines and labels each + day. The labels are placed exactly between two major grid lines as they + specify the complete day and not just midnight. - Y-Axis - [--yy|----yy--ggrriidd _g_r_i_d _s_t_e_p::_l_a_b_e_l _f_a_c_t_o_r] + YY--AAxxiiss + [--yy|----yy--ggrriidd _g_r_i_d _s_t_e_p::_l_a_b_e_l _f_a_c_t_o_r] - [--yy|----yy--ggrriidd nnoonnee] + [--yy|----yy--ggrriidd nnoonnee] - Y-axis grid lines appear at each _g_r_i_d _s_t_e_p interval. Labels are - placed every _l_a_b_e_l _f_a_c_t_o_r lines. You can specify "-y none" to - suppress the grid and labels altogether. The default for this - option is to automatically select sensible values. + Y-axis grid lines appear at each _g_r_i_d _s_t_e_p interval. Labels are placed + every _l_a_b_e_l _f_a_c_t_o_r lines. You can specify "-y none" to suppress the + grid and labels altogether. The default for this option is to + automatically select sensible values. - If you have set --y-grid to 'none' not only the labels get - suppressed, also the space reserved for the labels is removed. You - can still add space manually if you use the --units-length command - to explicitly reserve space. + If you have set --y-grid to 'none' not only the labels get suppressed, + also the space reserved for the labels is removed. You can still add + space manually if you use the --units-length command to explicitly + reserve space. - [--YY|----aalltt--yy--ggrriidd] + [--YY|----aalltt--yy--ggrriidd] - Place the Y grid dynamically based on the graph's Y range. The - algorithm ensures that you always have a grid, that there are - enough but not too many grid lines, and that the grid is metric. - That is the grid lines are placed every 1, 2, 5 or 10 units. This - parameter will also ensure that you get enough decimals displayed - even if your graph goes from 69.998 to 70.001. (contributed by - Sasha Mikheev). + Place the Y grid dynamically based on the graph's Y range. The + algorithm ensures that you always have a grid, that there are enough + but not too many grid lines, and that the grid is metric. That is the + grid lines are placed every 1, 2, 5 or 10 units. This parameter will + also ensure that you get enough decimals displayed even if your graph + goes from 69.998 to 70.001. (contributed by Sasha Mikheev). - [--oo|----llooggaarriitthhmmiicc] + [--oo|----llooggaarriitthhmmiicc] - Logarithmic y-axis scaling. + Logarithmic y-axis scaling. - [--XX|----uunniittss--eexxppoonneenntt _v_a_l_u_e] + [--XX|----uunniittss--eexxppoonneenntt _v_a_l_u_e] - This sets the 10**exponent scaling of the y-axis values. Normally, - values will be scaled to the appropriate units (k, M, etc.). - However, you may wish to display units always in k (Kilo, 10e3) - even if the data is in the M (Mega, 10e6) range, for instance. - Value should be an integer which is a multiple of 3 between -18 and - 18 inclusively. It is the exponent on the units you wish to use. - For example, use 3 to display the y-axis values in k (Kilo, 10e3, - thousands), use -6 to display the y-axis values in u (Micro, 10e-6, - millionths). Use a value of 0 to prevent any scaling of the y-axis - values. + This sets the 10**exponent scaling of the y-axis values. Normally, + values will be scaled to the appropriate units (k, M, etc.). However, + you may wish to display units always in k (Kilo, 10e3) even if the data + is in the M (Mega, 10e6) range, for instance. Value should be an + integer which is a multiple of 3 between -18 and 18 inclusively. It is + the exponent on the units you wish to use. For example, use 3 to + display the y-axis values in k (Kilo, 10e3, thousands), use -6 to + display the y-axis values in u (Micro, 10e-6, millionths). Use a value + of 0 to prevent any scaling of the y-axis values. - This option is very effective at confusing the heck out of the - default rrdtool autoscaler and grid painter. If rrdtool detects - that it is not successful in labeling the graph under the given - circumstances, it will switch to the more robust ----aalltt--yy--ggrriidd mode. + This option is very effective at confusing the heck out of the default + rrdtool autoscaler and grid painter. If rrdtool detects that it is not + successful in labeling the graph under the given circumstances, it will + switch to the more robust ----aalltt--yy--ggrriidd mode. - [--LL|----uunniittss--lleennggtthh _v_a_l_u_e] + [--LL|----uunniittss--lleennggtthh _v_a_l_u_e] - How many digits should rrdtool assume the y-axis labels to be? You - may have to use this option to make enough space once you start - fideling with the y-axis labeling. + How many digits should rrdtool assume the y-axis labels to be? You may + have to use this option to make enough space once you start fiddling + with the y-axis labeling. - [----uunniittss==ssii] + [----uunniittss==ssii] - With this option y-axis values on logarithmic graphs will be scaled - to the appropriate units (k, M, etc.) instead of using exponential - notation. Note that for linear graphs, SI notation is used by - default. + With this option y-axis values on logarithmic graphs will be scaled to + the appropriate units (k, M, etc.) instead of using exponential + notation. Note that for linear graphs, SI notation is used by default. + + RRiigghhtt YY AAxxiiss + [----rriigghhtt--aaxxiiss _s_c_a_l_e::_s_h_i_f_t] [----rriigghhtt--aaxxiiss--llaabbeell _l_a_b_e_l] + + A second axis will be drawn to the right of the graph. It is tied to + the left axis via the scale and shift parameters. You can also define a + label for the right axis. + + [----rriigghhtt--aaxxiiss--ffoorrmmaatt _f_o_r_m_a_t_-_s_t_r_i_n_g] + + By default the format of the axis lables gets determined automatically. + If you want todo this your self, use this option with the same %lf + arguments you know from the PRING and GPRINT commands. + + LLeeggeenndd + [--gg|----nnoo--lleeggeenndd] + + Suppress generation of the legend; only render the graph. + + [--FF|----ffoorrccee--rruulleess--lleeggeenndd] + + Force the generation of HRULE and VRULE legends even if those HRULE or + VRULE will not be drawn because out of graph boundaries (mimics + behaviour of pre 1.0.42 versions). + + [----lleeggeenndd--ppoossiittiioonn=(north|south|west|east)] + + Place the legend at the given side of the graph. The default is south. + In west or east position it is necessary to add line breaks manually. + + [----lleeggeenndd--ddiirreeccttiioonn=(topdown|bottomup)] + + Place the legend items in the given vertical order. The default is + topdown. Using bottomup the legend items appear in the same vertical + order as a stack of lines or areas. MMiisscceellllaanneeoouuss [--zz|----llaazzyy] @@ -256,6 +271,16 @@ OOPPTTIIOONNSS lazy will not generate the graph when it is already there and up to date, and also that it will output the size of the graph. + [----ddaaeemmoonn _a_d_d_r_e_s_s] + + Address of the rrdcached daemon. If specified, a "flush" command is + sent to the server before reading the RRD files. This allows the graph + to contain fresh data even if the daemon is configured to cache values + for a long time. For a list of accepted formats, see the --ll option in + the rrdcached manual. + + rrdtool graph [...] --daemon unix:/var/run/rrdcached.sock [...] + [--ff|----iimmggiinnffoo _p_r_i_n_t_f_s_t_r] After the image has been created, the graph function uses printf @@ -283,6 +308,12 @@ OOPPTTIIOONNSS A green arrow is made by: "--color ARROW#00FF00" + [----bboorrddeerr _w_i_d_t_h]] + + Width in pixels for the 3d border drawn around the image. Default 2, 0 + disables the border. See "SHADEA" and "SHADEB" above for setting the + border color. + [----zzoooomm _f_a_c_t_o_r] Zoom the graphics by the given amount. The factor must be > 0 @@ -297,6 +328,9 @@ OOPPTTIIOONNSS Use Times for the title: "--font TITLE:13:Times" + Note that you need to quote the argument to ----ffoonntt if the font-name + contains whitespace: --font "TITLE:13:Some Font" + If you do not give a font string you can modify just the size of the default font: "--font TITLE:13:". @@ -389,16 +423,6 @@ OOPPTTIIOONNSS If images are interlaced they become visible on browsers more quickly. - [--gg|----nnoo--lleeggeenndd] - - Suppress generation of the legend; only render the graph. - - [--FF|----ffoorrccee--rruulleess--lleeggeenndd] - - Force the generation of HRULE and VRULE legends even if those HRULE or - VRULE will not be drawn because out of graph boundaries (mimics - behaviour of pre 1.0.42 versions). - [--TT|----ttaabbwwiiddtthh _v_a_l_u_e] By default the tab-width is 40 pixels, use this option to change it. @@ -460,6 +484,15 @@ OOPPTTIIOONNSS Especially the 'graph_*' keys are new. They help applications that want to know what is where on the graph. +EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS + The following environment variables may be used to change the behavior + of "rrdtool graph": + + RRRRDDCCAACCHHEEDD__AADDDDRREESSSS + If this environment variable is set it will have the same effect as + specifying the "--daemon" option on the command line. If both are + present, the command line argument takes precedence. + SSEEEE AALLSSOO rrdgraph gives an overview of how rrrrddttooooll ggrraapphh works. rrdgraph_data describes DDEEFF,CCDDEEFF and VVDDEEFF in detail. rrdgraph_rpn describes the RRPPNN @@ -476,4 +509,4 @@ AAUUTTHHOORR -1.3.8 2009-04-07 RRDGRAPH(1) +1.3.999 2009-09-24 RRDGRAPH(1)