rrdtool graph文档翻译

rrdtool graph官方文档翻译。 很久很久以前将rrdtool全部文档都翻译了一遍，结果翻译全部结束时硬盘挂了，经过抢救也只剩下这2篇了，还是偶然的机会里找回来的，给大家分享下吧，当时翻译的rrdtool版本比较旧了（1.2.x吧），不知道官方有什么最新的文档了，估计大体变动不会很大，图片部分已经丢失了，图片不能显示的大家自己猜吧。

RRD翻译计划之续篇——graph

round robin database

1、术语

RRD——round robin database

DS——data source

DST——data source type

RRA——round robin archive

CF——consolidation function（合并/归并函数）

PDP——primary data point（基本数据点）

CDP——consolidation data point（合并/归并数据点）

RPN expression——逆波兰表达式

DEF——Definition

CDEF——Calculation Define

confidence band —— 【统计数学】置信带

confidence bound —— 置信界限

resolution ——分辨率 某个方向上的像素数量，也可以在这里把它理解为清晰度，但个人觉得分辨率更合理

wrap around —— 环绕，其实它的意思就是饼状数据库的数据覆盖满一圈，马上即将有数据丢失发生

2、RRD GRAPH/GRAPHV的语法

Graph语法格式：

rrdtool graph|graphv filename [ ...] [ ...] [data calculation ...] [ ...] [ ...] [ ...]

Rrdtool的graph功能是用来从视图的角度展现一个rrd的数据，其主要目的是创建一个很好的图形化展现，但它也可以产生一个数值的报告。

       Rrdtool的graph功能需要和数据一个工作，所以您必须使用一个或多个数据定义语句，以收集此数据。你不需要局限于一个数据库，从二个或者更多的数据库中收集数据是完全合理的（虽然是每个语句一个）。

如果您想显示平均值，最大值，百分，等等。最好的收集他们的方法是使用的变量的定义声明。目前这些没有差别，但在将来的rrdtool的版本中你可能会想要收集归并前的值。

从RRA里取得的数据是合并过的，因此在图形中正好每个像素一个数据点（datapoint）。如果你自己不小心，那么必要的话rrdtool将稍稍扩大它的范围，请注意，在这种情况下，第一个和/或最后一个像素很可能成为未知！

有些时候一些数据不是刚好你想要显示的格式，例如，您可能会收集每秒字节数（bypes per second），但是想显示每秒的比特数（bits per second），这就是设计了数据计算命令的用意，数据合并之后，会创建一个副本，然后这个副本会使用一个相当强大的逆波兰的命令集（RPN command）来修改。

当你完成获取或处理数据的时候，是时候来对它进行绘图（graph）或者打印（print）了。

选项及说明

Graphv

它是graph的替代版本，具有同graph一样的参数，执行相同的功能，v代表verbose（详细），描述返回的输出， graphv将返回了非常多的信息（相比使用相同格式的graph），同rrdtool info一样（key = value）。可以参考文档底部以获取更多信息。

 

Filename（文件名）

       这是产生图形的路径和名称，推荐用.png .svg 或.eps结尾。Filename可以是“-”，表示将图像（image）发送到标准输出（stdout），这种情况下，将不会产生其他的输出了。

 

Timerange（时间域）

[-s|--start time] [-e|--end time] [-S|--step seconds]

       Start和end是你想显示的时间序列，和数据应该来自于哪个RRA。缺省值是：1 day ago until now。

为了得到可能的最好的分辨率（resolution），start和end可以指定几种不同格式的，参见AT-STYLE TIME SPECIFICATION和rrdgraph_examples，默认情况下，rrdtool graph计算时间域内的一个像素的宽度，并试图从一个RRA中使用那个分辨率来获取数据。你可以用step选项来改变这个行为，如果您想rrdtool graph从RRD中以小时分辨率(one-hour resolution)获取数据，那么设置step为3600，注：step小于一个像素将被忽略.

【黑体部分原文为：If you want rrdtool graph to get data at a one-hour resolution from the RRD, set step to 3'600.关于分辨率的含义请参考开头的术语解释。】

 

Labels（标签）

[-t|--title string] [-v|--vertical-label string]

(title就是标题啦，v就是垂直标签了，就是Y轴的标签)

       横向字符串放置在图表的顶部和/或垂直的把字符串放置在图形的左手边

SIZE（图形的大小）

[-w|--width pixels] [-h|--height pixels] [-j|--only-graph] [-D|--full-size-mode]

       默认情况下，宽度和高度的画布(实际数据部分诸如此类)，这个预设为400像素×100像素。

       如果您指定了全尺寸（--full-size-mode ）的模式选项，宽度和高度指定的图像输出的最后尺寸和帆布是自适应调整大小的。

       如果您指定了--only-graph选项，并设定高度<32像素，你将获得一个微小的图像（缩略图），例如你可以用它作为图标的预览。所有的标签将会从图形中被剥夺。附张图吧，这就是--only-graph的效果。

      

       长和高都设为30pixel的图如下：

      

 

Limits（Y轴上下限）

[-u|--upper-limit value] [-l|--lower-limit value] [-r|--rigid]

       默认情况下该图形将自缩放，以便它调整Y轴来适应数据的范围，你可以通过明确指定limits来改变这种行为。

Y轴的显示范围至少从lower-limit到upper-limit。除非rigid选项被设置，自动缩放（autoscaling）将仍然允许这些界限被拉伸

[-A|--alt-autoscale]

       有时默认算法选择Y轴的比例并不理想，通常比例是由预定义的一套范围决定的，当你需要画象260+0.001*sin（x）的时候，这将失败的很惨。这个选项从实际的最低和最高的数据值中计算出最小值和最大值。我们的例子将显示略少于260-0.001至略多于260 0.001 （此功能由萨莎米科赫夫[Sasha Mikheev]贡献） 。

[-J|--alt-autoscale-min]

       --alt-autoscale选项是对绝对最大和最小值都进行修改，但此选项只会影响最小值。最大值如果没有在命令行中定义的话将会是0，在画WAN（广域网）线路使用压缩时的路由器的流量图时，这个选项会很有用的，从而吞吐量可能高于WAN的线路速度。

[-M|--alt-autoscale-max]

       --alt-autoscale选项是对绝对最大和最小值都进行修改，但此选项只会影响最大值。最小值如果没有在命令行中定义的话将会是0，在画WAN（广域网）线路使用压缩时的路由器的流量图时，这个选项会很有用的，从而吞吐量可能高于WAN的线路速度。

[-N|--no-gridfit]

       为了避免抗混叠模糊效果，rrdtool关闭拐点（snaps point）以适应设备分辨率像素，这将产生一个更清晰的展现，如果这不是您想要的，您可以把这个开关关掉。

       网格适应（gridfitting）在以PDF、EPS、SVG格式输出时，缺省是关闭的。

 

Grid（X/Y轴刻度）

X轴

[-x|--x-grid GTM:GST:MTM:MST:LTM:LST:LPR:LFM]

 

[-x|--x-grid none]

X轴标签的配置是相当复杂的。如果您还没有非常特殊的需求，最好让rrdtool自动配置。您可以指定--x-grid none来一起取消网格和X轴标签。这里拿个图举例吧，下图就是取消网格竖线和X轴标签后的效果（使用了--x-grid none）

       网格可以通过在X时间轴上指定一定数量的时间来定义，你可以从SECOND, MINUTE, HOUR, DAY, WEEK, MONTH或YEAR中选择，官方这里说了一堆数量，其实主要就是要理解这6个参数——GTM:GST:MTM:MST:LTM:LST，这些参数需要被指定来做基格（base grid）(G??)，主要的网格（major grid）（M??）和标签（L??），针对标签，您还必须定义一个精度在LPR和一个strftime类型的字符串格式在LFM。LPR定义每个标签放在哪里，如果LPR是零，标签将放在X轴线刻度的正下方（使用hours, dates等等标识），如果LPR在这里指定的是多少秒数，标签将置于间隔的正中间（标识会是Monday, January等等）。看看例子什么都清楚了。

举例1：

               --x-grid MINUTE:10:HOUR:1:HOUR:4:0:%X

       这个例子就表示这个地方的网格线的刻度时每10分钟标志一次（就是画一个竖线来表示刻度，最小粒度的刻度），主网格线（major grid line）的刻度是每一个小时标识一次（主刻度），标签是每4个小时标志一次（就是X轴的标注）。标签放在主网格线下方，因为它们指定的正是这个时候。使用上述配置，让我们来看看day图的展现：

举例2：

          --x-grid HOUR:8:DAY:1:DAY:1:86400:%A

       这个例子就表示最小刻度是8小时，主网格线的刻度是1天，标签的刻度也是1天，标签放在2个主网格线之间，因为参数指定的是完整的1天的秒数，而不是午夜（midnight）这个时刻。使用上述配置，让我们来看看week图的展现：

Y轴

[-y|--y-grid grid step:label factor]

[-y|--y-grid none]

Y轴的网格线出现在每一个网格步长区间，标签是放在每个标签刻度线旁，您可以指定--y-grid none来一起取消网格和Y轴标签。这里拿个图举例吧，下图就是取消网格横线和Y轴标签后的效果（使用了--y-grid none）

这个选项的缺省是自动选择合理的值。如果你将--y-grid设置为none，不仅标签被禁止，预留空间的标签也会被删除。你也可以手工把预留空间加上——使用units-length命令来明确保留的空间。

 

[-Y|--alt-y-grid]

       根据图形的Y轴的值范围动态的调整Y轴的网格，该算法可以确保您始终有一个网格，是足够的，但不会太多网格线，并且网格是可度量（metric）的。这是网格线每1 ， 2 ， 5或10个单位分布。此参数也将确保您获得足够的小数显示，即使您的图形从69.998至70.001 。（此功能由萨莎米科赫夫[Sasha Mikheev]贡献）

 

[-o|--logarithmic]

       对数Y轴缩放。

 

[-X|--units-exponent value]

       这个参数是设置Y轴的缩放的值——10的指数次幂。例如，通常情况下，值将被缩小到适当的单位（k，M等），不过即使数据是在M (Mega, 10e6)范围内，也可以始终以k（Kilo, 10e3）为单位显示。值应该是一个整数，且是3的倍数，值在-18（包含）至18（包含）之间，该指数是您想使用的单位。例如，使用3就表示用k (Kilo, 10e3, 千)来显示Y轴的值，使用-6就表示用u (Micro, 10e-6, 百万分之一) 来显示Y轴的值，使用0就是阻止任何对Y轴的比例缩放。

       这个选项对于扰乱不管是缺省的rrdtool自缩放还是网格画法都非常有效。如果rrdtool检测到特定情况下不能在图形上添加标签，它将切换到更强大的--alt-y-grid模式。

 

[-L|--units-length value]

       Rrdtool应该假设Y轴标签是多少位数字？一旦你开始填充Y轴的标签了，您可能必须要使用这个选项，留出足够的空间。——其实就是应该在Y轴的左边留多少空来放标签的数字。

 

[--units=si]

       对于这个选项，对数图上的y轴的值将被缩小到适当的单位（K，M等等），而不是使用指数符号。请注意，对于线性图表，SI标记是默认使用的。

 

其他参数

[-z|--lazy]

       如果当前图不存在或者在日期范围以外，那么仅仅只产生图形，请注意，如果你使用了lazy选项，即使你使用了graphv或者使用了PRINT，那么也只返回图像的尺寸。

 

[-f|--imginfo printfstr]

       图像被创建后，graph使用printf函数创建类似于PRINT输出的格式化字符串，仅当提供了filename, xsize and ysize这3个参数后，printf函数才会生效。为了创建一个合适IMG标签，使得可以在web页面里可以引用，命令行看起来就像这样：

--imginfo ''

 

[-c|--color COLORTAG#rrggbb[aa]]

这个选项的目的是覆盖图形的标准元素的缺省颜色。COLORTAG的选项有以下这些：

（1）这个图形的幕布背景色使用BACK选项，示例：-c BACK#FF0000（红色），如下图：（中间的颜色不是红色的原因是：缺省的CANVAS选项是#FFFFFF白色，CANVAS选项可以参考下面的说明）

（2）实际图形的背景色使用CANVAS选项，示例：-c CANVAS#FF0000（红色），如下图

（3）左侧和顶部边界的颜色使用SHADEA选项，示例：-c SHADEA#FF0000（红色），如下图

（4）右侧和底部边界的颜色使用SHADEB选项，示例：-c SHADEB#FF0000（红色），如下图

（5）主网格（major grid）的颜色使用GRID, MGRID选项，示例：-c GRID#ff00ff -c MGRID#0000ff（主网格用蓝色，基础网格使用紫色），如下图

 

（6）字体的颜色使用FONT选项，示例：-c FONT#ff0000（红色），如下图

（7）图形的轴线颜色使用AXIS选项，示例：-c AXIS#ff00ff（紫色），如下图

（8）图块周围的线条的颜色使用FRAME选项，示例：使用-c FRAME#ff0000（红色），如下图

（9）箭头的颜色使用ARROW选项，示例：使用-c ARROW#ff0000（红色），如下图

RGB的颜色的简单介绍大家自己看吧。反正就是16进制的数字游戏，从00至FF，00是关闭（off），FF是最大值（maximum）。

 

[--zoom factor]

       这个选项是图形缩放的比例因子，factor必须>0

 

[-n|--font FONTTAG:size:[font]]

       这个选项是让你自定义不同的文字元素的字体，默认是使用所有元素的缺省值。

标题的字体使用TITLE选项，坐标轴标签的字体使用AXIT选项，垂直单位的标签的字体使用UNIT选项，图形下个小图标的说明字体使用LEGEND选项。

比如使用Times的字体格式作为标题的字体：--font TITLE:13:Times（这里要注意的一点是你的server上要存在这种字体，如果不存在你输入的字体，那么标题会显示为空。另外最后的字体也可以不写，如--font TITLE:13:或者--font TITLE:13都可以，这就表示使用默认的字体——养成习惯，最后的冒号尽量不要省略，否则容易出问题）

如果大小使用0，就表示只设置相关的字体，大小使用默认值。

如果你想修改rrdtool环境的缺省字体的话，可以设置环境变量RRD_DEFAULT_FONT的值来指定缺省字体

Rrdtool使用pango来处理其字体，意思就是当选择字体是可以充分利用Pango的语法来定义：字体名称的语法形式类似这样”[FAMILY-LIST] [STYLE-OPTIONS] [SIZE]”，其中FAMILY-LIST是一些以逗号分隔的families的列表，STYLE_OPTIONS是一个空格分隔的字词清单，其中每个WORD描述一个style，variant, weight, stretch, or gravity（这些都是对字体的处理样式，应该大家好理解的），SIZE是一个十进制数（大小的点），后面可跟px为单位来表示绝对大小。任何选项都是可省略的（不是必须的）——实际上，pango是渲染字体用的底层库，这里如果大家不明白pango的语法的话，随便找个css的语法看下font的部分，非常容易理解。

 

[-R|--font-render-mode {normal,light,mono}]

提供了3种字体显示效果模式：

normal: Full Hinting and Antialiasing (default)

light: Slight Hinting and Antialiasing

mono: Full Hinting and NO Antialiasing

解释一下吧：Hinting的意思是：字体微调，优化小字体时的显示效果

                            Antialiasing是反锯齿效果，No Antialiasing是没有反锯齿效果

[-B|--font-smoothing-threshold size]

（此选项在1.3版本中将被忽略）

这个选项指定了没有任何字体平滑下所提供位图的最大字体的大小，默认情况下提供的位图是没有文字的。

 

[-P|--pango-markup]

Rrdtool中的所有文本是使用pango标记的。使用了--pango-markup这个选项，所有的文本将被pango标记处理，和使用标签

text

一样，允许嵌入一些简单的html标记。

除了详细的语法，下面也有也写短标记可以使用

b     粗体 big   使字体相对较大, 等同于 i     斜体 s     删除线 sub   下标 sup   上标 small 使字体相对较小, 等同于 tt    等宽字体（Monospace font） u     下划线

详细标记语法见http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html

 

[-G|--graph-render-mode {normal,mono}]

       提供了2种图形显示模式：

normal: 反锯齿(默认值)

mono:无反锯齿

 

[-E|--slope-mode]

Rrdtool默认对阶梯状的数据会进行自动平滑处理，这就是rrdtool对数据的线性计算方法。一些人主张即使数据并非准确的或者真实的，但依然希望他们的图形看起来更“自然”一点。

 

[-a|--imgformat PNG|SVG|EPS|PDF]

       这个选项是说明产生图像的格式，您可以从这些标准的PostScript字体中进行选择来作为矢量格式：Courier-Bold, Courier-BoldOblique, Courier-Oblique, Courier, Helvetica-Bold, Helvetica-BoldOblique, Helvetica-Oblique, Helvetica, Symbol, Times-Bold, Times-BoldItalic, Times-Italic, Times-Roman和ZapfDingbats

 

[-i|--interlaced]

       （此选项在1.3版本中将被忽略）

如果图像是交错的，那么会加速图像的浏览和展现。

 

[-g|--no-legend]

       这个选项就是隐藏数据说明栏

 

[-F|--force-rules-legend]

       即使HRULE或VRULE没有被画出，也强制产生HRULE和VRULE图标，因为这2个值已经超过图形的边界

 

[-T|--tabwidth value]

       缺省tab-width 是40像素，使用这个选项可以更改它

 

[-b|--base value]

       如果你在画memory图（并非traffic图），这个选项应该被设定为1024，这样1Kb就是1024字节。对traffic来说1 kb/s是1000 b/s.（大家注意大K和小k的区别，K-1024， k-1000）

 

[-W|--watermark string]

       这个嘛很明显喽，就是水印，贴张图大家看看就知道了，大家注意水印“Design by Exp”的位置——底部的正中间。

 

数据和变量

DEF:vname=rrdfile:ds-name:CF[:step=step][:start=time][:end=time]

CDEF:vname=RPN expression

VDEF:vname=RPN expression

你至少要定义一个DEF表达式，其他的表达式是可选的。参见和 中的详细描述。

注意：graph和print部分

你至少要定义一个print表达式来产生一个数据报表。参见中的详细描述。

 

Graphv

调用rrdtool的graphv选项时，将以info的形式返回信息。命令行上这就意味着所有的输出将是key=value 格式。当使用Perl和ruby绑定变量时，将返回调用的一个哈希指针。

当文件名使用‘-’，图像内容的自身也将通过它的接口被返回（hash key 'image'），命令行上的输出就像这样：

print[0] = "0.020833" print[1] = "0.0440833" graph_left = 51 graph_top = 22 graph_width = 400 graph_height = 100 image_width = 481 image_height = 154 value_min = 0.0000000000e+00 value_max = 4.0000000000e-02 image = BLOB_SIZE:8196 [... 8196 bytes of image data ...]

这比标准接口返回更多的信息，尤其是'graph_*' keys are new，这些输出帮助理解图形的什么位置存在什么样的内容。

参见

Rrdgraph简单的描述了rrdtool 的graph使用方法，会详细描述DEF,CDEF和VDEF的用法。描述DEF表达式中的RPN的语法（逆波兰表达式），详细描述了graph和print函数的用法。

这里有一些graph的用法示例。