X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=doc%2Frrdgraph_graph.txt;h=52bf57f05df65fa0e2f381d5e6a65812106c1830;hb=d9822df7ed5e8122cf3a62e4e99678e94007f504;hp=993771be64f94471d00dd95d8cf906bbf71abb7c;hpb=a93b6b71c84ffda2b82a8dc5e56e01940d5a5bbe;p=pkg-rrdtool.git diff --git a/doc/rrdgraph_graph.txt b/doc/rrdgraph_graph.txt index 993771b..52bf57f 100644 --- a/doc/rrdgraph_graph.txt +++ b/doc/rrdgraph_graph.txt @@ -12,17 +12,13 @@ SSYYNNOOPPSSIISS CCOOMMMMEENNTT::_t_e_x_t - VVRRUULLEE::_t_i_m_e##_c_o_l_o_r[::_l_e_g_- - _e_n_d][::ddaasshheess[==_o_n___s[,_o_f_f___s[,_o_n___s,_o_f_f___s]...]][::ddaasshh--ooffffsseett==_o_f_f_s_e_t]] + VVRRUULLEE::_t_i_m_e##_c_o_l_o_r[::_l_e_g_e_n_d][::ddaasshheess[==_o_n___s[,_o_f_f___s[,_o_n___s,_o_f_f___s]...]][::ddaasshh--ooffffsseett==_o_f_f_s_e_t]] - HHRRUULLEE::_v_a_l_u_e##_c_o_l_o_r[::_l_e_g_- - _e_n_d][::ddaasshheess[==_o_n___s[,_o_f_f___s[,_o_n___s,_o_f_f___s]...]][::ddaasshh--ooffffsseett==_o_f_f_s_e_t]] + HHRRUULLEE::_v_a_l_u_e##_c_o_l_o_r[::_l_e_g_e_n_d][::ddaasshheess[==_o_n___s[,_o_f_f___s[,_o_n___s,_o_f_f___s]...]][::ddaasshh--ooffffsseett==_o_f_f_s_e_t]] - LLIINNEE[_w_i_d_t_h]::_v_a_l_u_e[##_c_o_l_o_r][::[_l_e_g_- - _e_n_d][::SSTTAACCKK]][::ddaasshheess[==_o_n___s[,_o_f_f___s[,_o_n___s,_o_f_f___s]...]][::ddaasshh--ooffffsseett==_o_f_f_- - _s_e_t]] + LLIINNEE[_w_i_d_t_h]::_v_a_l_u_e[##_c_o_l_o_r][::[_l_e_g_e_n_d][::SSTTAACCKK][::sskkiippssccaallee][::ddaasshheess[==_o_n___s[,_o_f_f___s[,_o_n___s,_o_f_f___s]...]][::ddaasshh--ooffffsseett==_o_f_f_s_e_t]] - AARREEAA::_v_a_l_u_e[##_c_o_l_o_r][::[_l_e_g_e_n_d][::SSTTAACCKK]] + AARREEAA::_v_a_l_u_e[##_c_o_l_o_r][::[_l_e_g_e_n_d][::SSTTAACCKK][::sskkiippssccaallee]] TTIICCKK::_v_n_a_m_e##_r_r_g_g_b_b[_a_a][::_f_r_a_c_t_i_o_n[::_l_e_g_e_n_d]] @@ -41,13 +37,12 @@ DDEESSCCRRIIPPTTIIOONN don't use any graph elements, no graph is generated. Similarly, no report is generated if you don't use print options. - PPRRIINNTT - + PPRRIINNTT _PP_RR_II_NN_TT_::_v_n_a_m_e_::_f_o_r_m_a_t_[_::_ss_tt_rr_ff_tt_ii_mm_ee_] - Depending on the context, either the value component or the time compo- - nent of a VVDDEEFF is printed using _f_o_r_m_a_t. It is an error to specify a - _v_n_a_m_e generated by a DDEEFF or CCDDEEFF. + Depending on the context, either the value component or the time + component of a VVDDEEFF is printed using _f_o_r_m_a_t. It is an error to specify + a _v_n_a_m_e generated by a DDEEFF or CCDDEEFF. Any text in _f_o_r_m_a_t is printed literally with one exception: The percent character introduces a formatter string. This string can be: @@ -61,25 +56,26 @@ DDEESSCCRRIIPPTTIIOONN field width and decimal precision. %%##..##llff - prints numbers like 12345.6789, with optional field width and pre- - cision. + prints numbers like 12345.6789, with optional field width and + precision. %%ss place this after %%llee, %%llff or %%llgg. This will be replaced by the - appropriate SI magnitude unit and the value will be scaled accord- - ingly (123456 -> 123.456 k). + appropriate SI magnitude unit and the value will be scaled + accordingly (123456 -> 123.456 k). - %%SS is similar to %%ss. It does, however, use a previously defined magni- - tude unit. If there is no such unit yet, it tries to define one - (just like %%ss) unless the value is zero, in which case the magni- - tude unit stays undefined. Thus, formatter strings using %%SS and no - %%ss will all use the same magnitude unit except for zero values. + %%SS is similar to %%ss. It does, however, use a previously defined + magnitude unit. If there is no such unit yet, it tries to define + one (just like %%ss) unless the value is zero, in which case the + magnitude unit stays undefined. Thus, formatter strings using %%SS + and no %%ss will all use the same magnitude unit except for zero + values. If you PRINT a VDEF value, you can also print the time associated with - it by appending the string ::ssttrrffttiimmee to the format. Note that rrdtool + it by appending the string ::ssttrrffttiimmee to the format. Note that RRDtool uses the strftime function of your OSs C library. This means that the - conversion specifier may vary. Check the manual page if you are uncer- - tain. The following is a list of conversion specifiers usually sup- - ported across the board. + conversion specifier may vary. Check the manual page if you are + uncertain. The following is a list of conversion specifiers usually + supported across the board. %%aa The abbreviated weekday name according to the current locale. @@ -105,24 +101,25 @@ DDEESSCCRRIIPPTTIIOONN %%MM The minute as a decimal number (range 00 to 59). - %%pp Either `AM' or `PM' according to the given time value, or the cor- - responding strings for the current locale. Noon is treated as `pm' - and midnight as `am'. Note that in many locales and `pm' notation - is unsupported and in such cases %p will return an empty string. + %%pp Either `AM' or `PM' according to the given time value, or the + corresponding strings for the current locale. Noon is treated as + `pm' and midnight as `am'. Note that in many locales and `pm' + notation is unsupported and in such cases %p will return an empty + string. %%ss The second as a decimal number (range 00 to 61). - %%SS The seconds since the epoch (1.1.1970) (libc dependant non stan- - dard!) + %%SS The seconds since the epoch (1.1.1970) (libc dependent non + standard!) %%UU The week number of the current year as a decimal number, range 00 to 53, starting with the first Sunday as the first day of week 01. See also %V and %W. - %%VV The ISO 8601:1988 week number of the current year as a decimal num- - ber, range 01 to 53, where week 1 is the first week that has at - least 4 days in the current year, and with Monday as the first day - of the week. See also %U and %W. + %%VV The ISO 8601:1988 week number of the current year as a decimal + number, range 01 to 53, where week 1 is the first week that has + at least 4 days in the current year, and with Monday as the first + day of the week. See also %U and %W. %%ww The day of the week as a decimal, range 0 to 6, Sunday being 0. See also %u. @@ -150,8 +147,7 @@ DDEESSCCRRIIPPTTIIOONN _D_e_p_r_e_c_a_t_e_d_. _U_s_e _t_h_e _n_e_w _f_o_r_m _o_f _t_h_i_s _c_o_m_m_a_n_d _i_n _n_e_w _s_c_r_i_p_t_s_. The first form of this command is to be used with CCDDEEFF _v_n_a_m_es. - GGRRAAPPHH - + GGRRAAPPHH _GG_PP_RR_II_NN_TT_::_v_n_a_m_e_::_f_o_r_m_a_t This is the same as "PRINT", but printed inside the graph. @@ -167,27 +163,23 @@ DDEESSCCRRIIPPTTIIOONN in RRDtool 1.2 you have to escape colons in COMMENT text in the same way you have to escape them in **PPRRIINNTT commands by writing ''\\::''. - _VV_RR_UU_LL_EE_::_t_i_m_e_##_c_o_l_o_r_[_::_l_e_g_- - _e_n_d_]_[_::_dd_aa_ss_hh_ee_ss_[_==_o_n___s_[_,_o_f_f___s_[_,_o_n___s_,_o_f_f___s_]_._._._]_]_[_::_dd_aa_ss_hh_--_oo_ff_ff_ss_ee_tt_==_o_f_f_s_e_t_]_] + _VV_RR_UU_LL_EE_::_t_i_m_e_##_c_o_l_o_r_[_::_l_e_g_e_n_d_]_[_::_dd_aa_ss_hh_ee_ss_[_==_o_n___s_[_,_o_f_f___s_[_,_o_n___s_,_o_f_f___s_]_._._._]_]_[_::_dd_aa_ss_hh_--_oo_ff_ff_ss_ee_tt_==_o_f_f_s_e_t_]_] - Draw a vertical line at _t_i_m_e. Its color is composed from three hex- - adecimal numbers specifying the rgb color components (00 is off, FF is - maximum) red, green and blue followed by an optional alpha. Optionally, - a legend box and string is printed in the legend section. _t_i_m_e may be a - number or a variable from a VVDDEEFF. It is an error to use _v_n_a_m_es from DDEEFF - or CCDDEEFF here. Dashed lines can be drawn using the ddaasshheess modifier. See - LLIINNEE for more details. + Draw a vertical line at _t_i_m_e. Its color is composed from three + hexadecimal numbers specifying the rgb color components (00 is off, FF + is maximum) red, green and blue followed by an optional alpha. + Optionally, a legend box and string is printed in the legend section. + _t_i_m_e may be a number or a variable from a VVDDEEFF. It is an error to use + _v_n_a_m_es from DDEEFF or CCDDEEFF here. Dashed lines can be drawn using the + ddaasshheess modifier. See LLIINNEE for more details. - _HH_RR_UU_LL_EE_::_v_a_l_u_e_##_c_o_l_o_r_[_::_l_e_g_- - _e_n_d_]_[_::_dd_aa_ss_hh_ee_ss_[_==_o_n___s_[_,_o_f_f___s_[_,_o_n___s_,_o_f_f___s_]_._._._]_]_[_::_dd_aa_ss_hh_--_oo_ff_ff_ss_ee_tt_==_o_f_f_s_e_t_]_] + _HH_RR_UU_LL_EE_::_v_a_l_u_e_##_c_o_l_o_r_[_::_l_e_g_e_n_d_]_[_::_dd_aa_ss_hh_ee_ss_[_==_o_n___s_[_,_o_f_f___s_[_,_o_n___s_,_o_f_f___s_]_._._._]_]_[_::_dd_aa_ss_hh_--_oo_ff_ff_ss_ee_tt_==_o_f_f_s_e_t_]_] Draw a horizontal line at _v_a_l_u_e. HRULE acts much like LINE except that will have no effect on the scale of the graph. If a HRULE is outside the graphing area it will just not be visible. - _LL_II_NN_EE_[_w_i_d_t_h_]_::_v_a_l_u_e_[_##_c_o_l_o_r_]_[_::_[_l_e_g_- - _e_n_d_]_[_::_SS_TT_AA_CC_KK_]_]_[_::_dd_aa_ss_hh_ee_ss_[_==_o_n___s_[_,_o_f_f___s_[_,_o_n___s_,_o_f_f___s_]_._._._]_]_[_::_dd_aa_ss_hh_--_oo_ff_ff_ss_ee_tt_==_o_f_f_- - _s_e_t_]_] + _LL_II_NN_EE_[_w_i_d_t_h_]_::_v_a_l_u_e_[_##_c_o_l_o_r_]_[_::_[_l_e_g_e_n_d_]_[_::_SS_TT_AA_CC_KK_]_[_::_ss_kk_ii_pp_ss_cc_aa_ll_ee_]_]_[_::_dd_aa_ss_hh_ee_ss_[_==_o_n___s_[_,_o_f_f___s_[_,_o_n___s_,_o_f_f___s_]_._._._]_]_[_::_dd_aa_ss_hh_--_oo_ff_ff_ss_ee_tt_==_o_f_f_s_e_t_]_] Draw a line of the specified width onto the graph. _w_i_d_t_h can be a floating point number. If the color is not specified, the drawing is @@ -198,6 +190,11 @@ DDEESSCCRRIIPPTTIIOONN line is stacked on top of the previous element which can be a LLIINNEE or an AARREEAA. + Normally the graphing function makes sure that the entire LLIINNEE or AARREEAA + is visible in the chart. The scaling of the chart will be modified + accordingly if necessary. Any LLIINNEE or AARREEAA can be excluded from this + process by adding the option sskkiippssccaallee. + The ddaasshheess modifier enables dashed line style. Without any further options a symmetric dashed line with a segment length of 5 pixels will be drawn. The dash pattern can be changed if the ddaasshheess== parameter is @@ -207,9 +204,9 @@ DDEESSCCRRIIPPTTIIOONN _o_f_f_s_e_t into the pattern at which the stroke begins. When you do not specify a color, you cannot specify a legend. Should - you want to use STACK, use the "LINEx:::STACK" form. + you want to use SSTTAACCKK, use the "LINEx:::STACK" form. - _AA_RR_EE_AA_::_v_a_l_u_e_[_##_c_o_l_o_r_]_[_::_[_l_e_g_e_n_d_]_[_::_SS_TT_AA_CC_KK_]_] + _AA_RR_EE_AA_::_v_a_l_u_e_[_##_c_o_l_o_r_]_[_::_[_l_e_g_e_n_d_]_[_::_SS_TT_AA_CC_KK_]_[_::_ss_kk_ii_pp_ss_cc_aa_ll_ee_]_] See LLIINNEE, however the area between the x-axis and the line will be filled. @@ -256,51 +253,62 @@ DDEESSCCRRIIPPTTIIOONN know where to end. If you want to make sure you will be displaying a certain variable, - make sure never to stack upon the unknown value. Use a CDEF instruc- - tion with IIFF and UUNN to do so. + make sure never to stack upon the unknown value. Use a CDEF + instruction with IIFF and UUNN to do so. NNOOTTEESS oonn lleeggeenndd aarrgguummeennttss - EEssccaappiinngg tthhee ccoolloonn - + EEssccaappiinngg tthhee ccoolloonn A colon ':' in a _l_e_g_e_n_d argument will mark the end of the legend. To - enter a ':' as part of a legend, the colon must be escaped with a back- - slash '\:'. Beware that many environments process backslashes them- - selves, so it may be necessary to write two backslashes in order to one - being passed onto rrd_graph. - - SSttrriinngg FFoorrmmaattttiinngg + 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. + SSttrriinngg FFoorrmmaattttiinngg 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 char- - acter occurs, all pending text is pushed onto the graph according to - the character specified. + 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: \\jj for justified, \\ll for left aligned, \\rr for right aligned, and \\cc for centered. In the next section there is an example showing how to use centered formatting. \\nn is a valid alias for \\ll since incomplete parsing in earlier versions - of rrdtool lead to this behavior and a number of people has been using + of RRDtool lead to this behavior and a number of people has been using it. Normally there are two space characters inserted between every two - items printed into the graph. The space following a string can be sup- - pressed by putting a \\gg at the end of the string. The \\gg also ignores - any space inside the string if it is at the very end of the string. - This can be used in connection with %%ss to suppress empty unit strings. + items printed into the graph. The space following a string can be + suppressed by putting a \\gg at the end of the string. The \\gg also + ignores any space inside the string if it is at the very end of the + string. This can be used in connection with %%ss to suppress empty unit + strings. GPRINT:a:MAX:%lf%s\g A special case is COMMENT:\\ss 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 \\tt to line-up legend elements. Note that the - tabs inserted are relative to the start of the current legend element! + If you want to have left and right aligned legends on the same line use + COMMENT:\\uu to go one line back like this: + + COMMENT:left\l + COMMENT:\u + COMMENT:right\r + + There is also a 'nop' control for situations where you want a string to + actually end in a backslash character sequence \\.. + + COMMENT:OS\2\. + + When using a proportional font in your graph, the tab characters or the + sequence \\tt will line-up legend elements. Note that the tabs inserted + are relative to the start of the current legend element! Since RRDtool 1.3 is using Pango for rending text, you can use Pango - markup. Pango uses the xml ssppaann tags for inline formatting instruc- - tions.: + markup. Pango uses the xml ssppaann tags for inline formatting + instructions.: A simple example of a marked-up string might be: @@ -341,9 +349,9 @@ NNOOTTEESS oonn lleeggeenndd aarrgguummeennttss 'normal' or 'smallcaps' ssttrreettcchh - One of 'ultracondensed', 'extracondensed', 'condensed', 'semicon- - densed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', - 'ultraexpanded' + One of 'ultracondensed', 'extracondensed', 'condensed', + 'semicondensed', 'normal', 'semiexpanded', 'expanded', + 'extraexpanded', 'ultraexpanded' ffoorreeggrroouunndd An RGB color specification such as '#00FF00' or a color name such @@ -368,8 +376,8 @@ NNOOTTEESS oonn lleeggeenndd aarrgguummeennttss 'true' or 'false' whether to strike through the text ssttrriikkeetthhrroouugghh__ccoolloorr - The color of strikethrough lines; an RGB color specification such - as '#00FF00' or a color name such as 'red' + The color of crossed out lines; an RGB color specification such as + '#00FF00' or a color name such as 'red' ffaallllbbaacckk 'true' or 'false' whether to enable fallback. If disabled, then @@ -398,7 +406,7 @@ NNOOTTEESS oonn lleeggeenndd aarrgguummeennttss ii Italic - ss Strikethrough + ss Strike through ssuubb Subscript @@ -427,4 +435,4 @@ AAUUTTHHOORR -1.3.99909060808 2009-02-21 RRDGRAPH_GRAPH(1) +1.4.8 2013-05-23 RRDGRAPH_GRAPH(1)