axxess - graph the bandwidth usage of a Telkom ADSL account
axxess [-v|--version | [-?|-h|--help] | [-g|--debug] | [-m|--mail] | [-p|--png] | [-n|--noplot] | [filename]
This program will allow you to automatically retrieve the current monthly usage of the internet connection bandwidth usage of your Telkom ADSL line in South Africa.
The internet infrastructure in South Africa does exists and works but its wide use is hindered by excessive cost, long installation times, byrocracy and slow international connections. Most of the ADSL connections are 'capped' meaning that your usage is limited to certain amount of bytes uploaded and downloaded in any given month. If you exceed your limit, you can not use the connection unless you pay for more or wait until the next month. It therefore necessary to monitor the usage not to run over the limit.
The first version of this program used the usage website of my ISP. They now redirect requests to the Telkom site, but the name of the program remains the same.
The program needs and uses several one non-core perl class to run. When running it for the first time, you will be alerted if you do not have HTML::TableExtract. Install it and its depenencies from CPAN repository or using the package management program of your linux distribution (e.g. urpmi).
If you want to automate the graph generation and have it mailed to you, MIME::Lite needs to be installed. It not needed otherwise.
Program wget <http://www.gnu.org/software/wget/> is used to retrive the web page.
Commom graphing program gnuplot <http://www.gnuplot.info/> is used for plotting the results.
Edit the values in the script area below marked 'Your details':
Your ADSL username including the domain. Replace the '@' character with '%40'.
Your password
Writable directory to store all log files.
Integer. Your usage monthly limit in mega bytes.
Factor by which daily values are multipied before storing and displaying. The default value 10 will make it easier to see the bars on the graph.
If you are mailing results to one or more recipients using the -m option, you need to specify these, too:
Your valid email address.
A string of comma separated email addresses of recipients of the mail.
The string for the subject line of the mail.
Your local SMTP server name. Your computer must have an internet address that is recognised by the server to be able to send emails.
You run this program in a unixy environment by putting into your path and giving it executable priviledges (chmod 755 axxess ) and running it without any arguments.
The wget program is required to retrive the web pages, but gnuplot can be ignored by using the option --noplot.
If a valid log filename is given as an argument, the contents are displayed in a plot. Using appropriate options (-p, -m) you can create image files and mail them.
Print out a line with the program name and version number.
Show this help.
Print out various intermediate values for debugging purposes.
Create a PNG image file in the storage directory. This option disables default X window display. Noplot option (see next item) overrides any plot generation.
If you do not have gnuplot available, you can use this program to conveniently retrieve the total bandwidth usage even when you can not display the plot.
The log file format is very simple one needed by gnuplot. Every item is separated by a tab character. The five fields are : 1) day of the month in two digits 2) downward traffic for the day 3) uploaded traffic for the day 4) total for the day (2+3), and 5) cumulative total.
The cumulative total is a floating point number with unit in magabytes. The actual numerical values of daily counts are in megabytes, too, but they have been multiplied by variable $dayvalue_multiple. It defaults to 10 to make the bars more visible and easy to read.
The X axis is numbered from 0 to number of days in the current month. The Y axis goes from 0 to what the usage cap ($cap) is set to. The expected (highly theoretical) usage is plotted as strigh line from lower left corner to upper right corner. You can compare the lot more wavy line of the actual daily cumulative usage against it to see if you are going to run out of bandwidth before the end of the month - or if you can do that big download you have been wanting to do but had not dared in fear of running out.
The daily usage is not in the same scale as the cumulative data. If you have left the magnification to 10, you can easily convert the numbers seen on the scale on the right hand side of the plot to actual numbers by ignoring the last zero.
The avarage daily allowance is plotted as horisontal line accross the plot. You might want to check the days you've used more than the avarage allowance and try to remember what you were doing to use all that bandwidth. The vertical bar for daily usage is devided by a line which indicates the amount downloaded that day. The remaining top part, which is usually a lot smaller, represents uploaded bytes.
v. 1.0 31 Jan 2006, first version
v. 1.1 16 Feb 2006, graph generation using gnuplot
v. 1.2 20 Feb 2006, gnuplot, input file from command line
v. 1.2.1 23 Feb 2006, fixed the input month, was reading the previous one
v. 1.3 20 Sep 2006, Axxess redirects to Telcom usage site
rewrite using wget and HTML::TableExtract
v. 1.3.1 12 Nov 2006, expicit zero start-up point,
fixes plots with only the first day value
v. 1.4 12 Dec 2006, options to create PNG image and mail it
v. 1.4.1 13 Dec 2006, fix typos in the docs
Please report bugs to the author.
You may distribute this program under the same terms as perl itself.
Heikki Lehvaslaiho, heikki lehvaslaiho a gmail com
No input from others so far.
You can get the latest version of this program at http://heikki.lehvaslaiho.googlepages.com/axxess
http://en.wikipedia.org/wiki/Telkom#Monthly_Traffic_Limitations_and_Port_Prioritization
The rest of the documentation details each of the subroutines this program is composed of.
Example : init;
Description: Initialize non-standard perl modules and external programs and fail
gracefully if any of them is missing.
Returns : true on success
Exceptions : dies on fail
Caller : main()
Example : gnuplot ($filename, $days_in_month, $max_bandwidth)
Description: Call gnuplot to open a data file and create a graph
Returns : pathname of the graph generated generated (only for PNG file)
Exceptions : -
Caller : main()
Arguments : 1. filename, scalar
2. length of the current month, X axis, scalar
3. max available bandwidth, Y axis, scalar
4. boolean to enable PNG file generation
Example : gnuplot_png ($filename, $days_in_month, $max_bandwidth)
Description: Call gnuplot to open a data file and graph usage into a PNG file
This function is an alias of gnuplot() with PNG option enabled
Returns : pathname of the graph generated generated
Exceptions : -
Caller : main()
Arguments : 1. filename, scalar
2. length of the current month, X axis, scalar
3. max available bandwidth, Y axis, scalar
Example : mail_plot ($filename) Description: Email the stored PNG image file to recipients Returns : true Exceptions : MIME::Lite module not available Caller : main() Arguments : 1. filename, scalar
Example : datetime
Description: Easy to sort date/time string.
The string starts with the year and ends with seconds.
Returns : scalar, formatted date/time
Exceptions : -
Caller : main()