h1. Webstats

Webstats is a server and clients that monitors your servers performance (CPU usage, memory usage, disk usage, disk activity, url load time) and allows you to get notifications on your computer when the server is having problems, as well as showing (http://kimag.es/share/91090734.png) the current performance stats for the server on a web page.

Webstats has 2 components: the _server_ and one or more _clients_.

h2. Server

The server runs on the computer whose performance you want to monitor; the server application's job is to (1) monitor the computer's performance and (2) report these performance statistics through a webserver that the server application runs.

See Installation below for install instructions.

The server application executes in the background and starts a tiny webserver on port 9970. You can view the performance stats for your server by going to http://<server's hostname>:9970/, for example if my server was under the domain name bloople.net, I would go to http://bloople.net:9970/. The statistics on this page automatically update every 5 seconds. You may need to open port 9970 if you have a firewall on your server. Note that the various clients get their data via the webserver the server application runs, just like the built-in stats page.

The statistic provided by the server application are:

* CPU usage and load average
* Memory (RAM) usage, with free, free - buffers, and total counts
* Disk usage by mount point
* Disk activity for reads and writes
* URL monitoring, to load URL's you specify to ensure they work

The server application will warn you of any of these statistics indicate a problem on the server - for example if you've have < 5MB free RAM for the last 12 seconds, that indicates a potential problem on your server that needs looking at. If you're looking at the performance statistics web page, the warnings will be presented by higlighting the perf stat that's causing the warning; when you're using a client application, it will present warnings to you as it sees fit.

You can configure at what thresholds the warnings get generated, as well as the URL's to monitor, by editing ~/.webstats. This file is generated the first time you run webstats, so it's pre-filled with sensible defaults; but you can change them as you see fit.

You can prevent public access to your webstats by invoking the server application with a single argument (e.g. <code>ruby webstats.rb <password to use></code>). Then, when you visit the webstats, you'll be prompted for a username and password; the username is always 'webstats', and the password is the password specified just above.

The server application requires Linux kernel 2.6+, will not work in *BSD or OS X; the server application requires only Ruby; it does not rely on rubygems or any external libraries that aren't included with Ruby; the server application uses very little RAM, approximately 10MB.

All the client applications depend on the server application being run to work.

h2. Clients

If all you want to do is be able to view the performance statistics for your server in a web browser, then you don't need to use any of these clients; going to http://&lt;server's hostname&gt;:9970/ will do just fine. But if you want to have Growl or email notification when something goes wrong, without having to look at a web page all the time, then you'll want one of the client applications that come with Webstats.

There are currently two client applications available:

* An email notifier; documentation is available in clients/email_notifier/README.textile
* A Growl notifier; documentation is available in clients/growl_notifier/README.textile

The notifiers that ship with Webstats can be started in 2 ways; if you have installed webstats via rubygems, run:

<pre><code>~$ webstats_<notifier_name></code></pre>

For example, to run the email notifier, you can run webstats_email_notifier. If you installed webstats outside of rubygems, first change directory into the directory containing webstats, then run:
<pre><code>~/webstats$ ruby clients/<notifier_name>/<notifier_name>.rb</code></pre>

Many notifiers can also be run on the server, in the same ruby process as teh webstats server itself. To do this, change any settings as required by the documentation for the notifier, then add the notifier name (e.g. email_notifier) to the list of clients under webstats > clients in the ~/.webstats file

h2. Installation

You can now install webstats using rubygems; this saves you a bit of hassle. To install webstats on the server via rubygems, ensure github gems are in your gems sources; then run:
<pre><code>~$ sudo gem install bloopletech-webstats</code></pre>

To run the server application, run:
<pre><code>~$ webstats</code></pre>

The server application will start in the background.

If you don't want to use rubygems, then follow the below instructions:
To install the server app, ssh into the computer you want to monitor. then run:
<pre><code>~$ git clone git://github.com/bloopletech/webstats.git
~$ cd webstats
~/webstats$ cd server/data_providers
~/webstats/server/data_providers$ ruby extconf.rb
~/webstats/server/data_providers$ make
</code></pre>

To run the server app, ssh into the computer you want to monitor. then run:
<pre><code>~$ cd webstats
~/webstats$ ruby server/webstats.rb
</code></pre>

h2. Todo

* More client applications.
* Extend server to work on *BSD (including OS X).
* Make webstats server optionally install itself to run at boot.
* Make client applications optionally install themselves at boot, where suitable.
* (Maybe) Move all server code into it's own module and make code work without running the web server, so you can use it to just grab stats in your own code.