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