1.\"
2.\" Copyright (c) 2002-2010 Daniel Hartmeier
3.\" Copyright (c) 2013-2014 Nikola Kolev
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\"
10.\"    - Redistributions of source code must retain the above copyright
11.\"      notice, this list of conditions and the following disclaimer.
12.\"    - Redistributions in binary form must reproduce the above
13.\"      copyright notice, this list of conditions and the following
14.\"      disclaimer in the documentation and/or other materials provided
15.\"      with the distribution.
16.\"
17.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
18.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
19.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
20.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
21.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
22.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
23.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
24.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
25.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
27.\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28.\" POSSIBILITY OF SUCH DAMAGE.
29.\"
30.Dd April 2, 2013
31.Dt GRAFFER 8
32.Os
33.Sh NAME
34.Nm graffer
35.Nd collect numeric values and generate graphs
36.Sh SYNOPSIS
37.Nm graffer
38.Op Fl c Ar config
39.Op Fl d Ar database
40.Op Fl f Ar file
41.Op Fl q
42.Op Fl p
43.Op Fl t days[:days]
44.Sh DESCRIPTION
45The
46.Nm
47utility can collect numeric values from external programs
48and produce graphs from the collected data.
49.Pp
50The options are as follows:
51.Bl -tag -width "-d database"
52.It Fl q
53Query the current values from described external programs
54and store them in the database.
55This is usually done from a
56.Xr crontab 5
57like this:
58.Bd -literal
59* * * * * /usr/local/bin/graffer -q
60.Ed
61.Pp
62Note that without regular truncating (see below), the database
63will grow continually.
64.It Fl p
65Produce the configured set of graph images based on the statistics
66collected beforehand.
67.It Fl t Ar days:[days]
68Truncate the database, removing entries older than the specified number
69of days.
70The first value applies to uncompressed entries which constitute roughly
7190 percent of the database, the second value to compressed entries.
72Uncompressed entries are needed only for high-resolution graphs over
73short time periods.
74.Pp
75Assuming statistics are queried every I seconds, and a graph of width W
76pixels covering a time period of T seconds is generated, then
77uncompressed entries are only used when T/I < W*10.
78.Pp
79In other words, removing uncompressed entries earlier than compressed
80ones drastically reduces the database size.
81Graphs can be generated over the entire time range the compressed
82entries cover (monthly or yearly graphs), and high resolution graphs
83over short time periods in the recent past don't lose any precision.
84The precision is gradually lost for older periods.
85.Pp
86A typical invokation would be
87.Bd -literal
88graffer -t 31:365
89.Ed
90.Pp
91This removes uncompressed entries older than a month and compressed
92entries older than a year, allowing generation of graphs up to one
93year into the past, while keeping full precision for one month.
94.Pp
95Note that truncating the database does not usually shrink the size
96of the database file.
97Removed entries are only marked as deleted and their space is later
98reused for new entries.
99.It Fl f Ar file
100Copy the database into a new file, skipping removed and invalid
101entries.
102This operation takes longer than truncating, but produces a
103smaller database file.
104This can also be used to recover data from a corrupted database,
105indicated by the following error during truncating:
106.Bd -literal
107data_truncate: db->del() returned 1
108main: data_truncate() failed
109.Ed
110.It Fl c Ar config
111Use the specified configuration file instead of the default /usr/local/etc/graffer.conf.
112Syntax:
113.Bd -literal
114collect = "collect" number = coldef .
115coldef  = ( "path to external program" ) [ "diff" ] .
116image   = "image" filename "{"
117              time type size [ left ] [ right ] "}" .
118time    = "from" number [ unit ] [ "to" number [ unit ] ] .
119unit    = "minutes" | "hours" | "days" | "weeks" | "months" |
120                      "years" .
121type	= "type" ( "jpeg" | "png" ) .
122size    = "width" number "height" number .
123left    = "left" graphs .
124right   = "right" graphs .
125graphs  = graph [ "," graphs ] .
126graph   = "graph" number [ "bps" ] [ "avg" | "min" | "max" ]
127                  label unit "color" red green blue [ "filled" ] .
128.Ed
129.Pp
130.Pa collect
131lines define what values to store in the database.
132Each definition should use a unique number, which is used
133in
134.Pa graph
135lines to reference those values.
136.Pp
137The
138.Pa diff
139option causes differential values (change of value per second)
140to be stored instead of absolute values.
141For example, storing interface byte counters (which count the
142number of bytes since last reset) differentially produces
143values representing current speed (bytes per second).
144.Pp
145Several images can be defined in the same config file.
146An image can include two independent y-axes, both of which auto-scale
147independently to the maximum value in the selected range.
148Each axis can display an arbitrary number of graphs.
149.Pp
150When the
151.Pa bps
152option is used, values are multiplied by eight, and the unit
153prefixes 'k' (kilo), 'm' (mega), etc. are multiples of 1024,
154instead of 1000.
155.It Fl d Ar database
156Database file.
157Default is /var/db/graffer.db.
158.Sh EXAMPLES
159.Bd -literal
160collect 1 = "/usr/local/bin/statgrab -u net.sis0.rx" diff
161collect 2 = "/usr/local/bin/statgrab -u net.sis0.tx" diff
162image "/var/www/htdocs/bandwidth.jpg" {
163        from 7 days to now
164        width 1000 height 400
165        left
166                graph 1 bps "in" "bits/s" color 0 192 0 filled
167        right
168                graph 2 bps "out" "bits/s" color 0 0 255
169}
170collect 3 = "/usr/local/etc/graffer/scripts/freebsd/netstat.sh rl0 in" diff
171collect 4 = "/usr/local/etc/graffer/scripts/freebsd/disk.sh /dev/ad0 temp"
172image "/var/www/htdocs/rl0.jpg" {
173	from 12 months to now
174	width 800 height 200
175	left
176		graph 3 bps "states" "entries" color 200 0 0 filled,
177	right
178		graph 4 "ad0" "temperature" color 0 0 255
179}
180.Ed
181.Sh SEE ALSO
182.Xr crontab 5
183