File: README — Documentation for bloopletech-webstats (0.1.0)

Webstats

Webstats is a server and clients that monitors your servers performance (CPU usage, memory usage, disk usage) and allows you to get notifications on your computer when the server is having problems, as well as showing () the current performance stats for the server on a web page.

Webstats has 2 components: the server and one or more clients.

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 app runs.

See Installation below for install instructions.

The server app 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 bloople.net:9970/ to see my performance stats. 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 app runs, just like the built-in stats page.

You can prevent public access to your webstats by invoking the server application with a single argument (e.g. ruby webstats.rb <password>). 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 7MB.

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

Clients

If all you want to do is be able to view the performance stats for your server in a web browser, then you don’t need to use any of these clients; going to http://<server’s hostname>: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.

Right now there’s only one client application available, which is a Growl notifier. The Growl notifier only works on OS X, with RubyCocoa installed. This application runs in the background and monitors the server; if the server goes under high CPU load for more than a few seconds, or if the server is nearly out of memory, you’ll get a Growl notification saying what the problem is. This way, you can just set and forget, knowing that Webstats will report any problems.

To run the Growl notifier, open a terminal on your computer, then run (the first line is only needed the first time you run the notifier): ~$ git clone git://github.com/bloopletech/webstats.git ~$ cd webstats/clients/growl_notifier ~/webstats/clients/growl_notifier$ ruby growl_notifier.rb http://<server’s hostname>:9970/

Where server’s hostname is the host name of the server you want to monitor (e.g. bloople.net). The Growl notifier will then run in the background.

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: ~$ sudo gem install bloopletech-webstats

To run the server application, run: ~$ webstats

The server application will start in the background.

Coming soon: growl notifier client via rubygems.

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: ~$ 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

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

Todo

(DONE) (Coming soon) Add disk space remaining, with warnings / danger signals.
(DONE) (Coming soon) Add optional authentication to server application.
(Coming soon) Make webstats configurable.
Add email notifier to client applications.
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.
(DONE) Make into a gem?
(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.