Geeklog Usage Stats Plugin [v1.7.0]

by Andy Maloney [imol00@gmail.com]
09 Apr 2006

Table of Contents

Description

The Geeklog Usage Stats [GUS] plugin collects statistics on who visits your site, what browser and operating system they are using, which pages they view, and which links they are clicking to get there. It allows the administrator to browse these stats through a series of tables, getting right down into the data. It is based on the venerable stats plugin v1.3 by Tom Willett and John Hughes. Some of this documentation is based on their work as well. I was using the stats plugin for a long time and eventually decided it needed some cleanup and updating to work with the latest version of geeklog. Tom mentioned he wasn't going to continue supporting it, so I thought I'd make a few changes myself and release them. I figured this was going to be a quick week's work - wrong! As I got into it, I found I wanted to fix this and... oh that while I'm here, and optimise this a bit... oh and tweak that... Eventually I decided to do a major overhaul.

Differences Between GUS and 'Stats'

I made the following changes to the database:

I also changed the name of the plugin from 'stats' to 'gus', eliminated the 'name the plugin whatever you want' functionality, put all the documentation in this readme, added the ability to import stats from the stats plugin, and changed the installation/upgrade mechanism. I probably did some other things here and there too...

The changes to the database will improve performance and require less space. I don't have any real statistics on this, but from the feedback I got from the testers, it reduces databases to less than half their size and is noticeably faster when browsing the stats.

Since the initial changes to the stats plugin, many other features and tweaks have been added to GUS.

Developed Using These Tools

If you find GUS useful for monitoring and managing your site, please consider making a donation to support development. How about the price of a pizza or even just a beer? Check out the Things You Can Do section.

Version History

Thanks!

Installing The Plugin

  1. Backup your Geeklog database because the GUS plugin adds and modifies tables. You can do this with the built in database backup facility in the Admin menu.
  2. Uncompress the GUS plugin archive while in the <geeklog_dir>/plugins directory. The archive will create a directory called gus.
  3. In your <public_html> directory, create a directory called gus. Under your <public_html>/admin/plugins/ directory create a directory called gus.
  4. Change to your <geeklog_dir>/plugins/gus/ directory.
  5. Copy the files in the admin directory to the admin/plugins/gus/ directory you created in step 3.
  6. Copy the files and directories in the public_html directory to the public_html/gus/ directory you created in step 3.
  7. Go to the plugin administration page. The gus plugin should show up with a link to install it. Click it. The install page will tell you if the install was successful or not. If not, examine the Geeklog system errorlog in <geeklog_dir>/logs to see what the problem was. Fix it and re-install.
  8. The install page will offer you a link to the import page if it finds a suitable stats plugin to import from. If you choose not to do this right away, a link will appear on the admin page.

Configuring The Plugin

  1. In the Admin block you will find a link to the GUS admin page where you may set up ignored IP addresses, pages, and users. By default the user and IP of the user who installed the plugin is entered in the ignore list and statistics capture is turned on. The admin page lets you enter additional users and IPs for which usage information will not be collected. It also allows you to enable and disable statics capture.
  2. Set up security. Upon install, only the root users have access to statistics admin and viewing. You can delegate control for either of these functions through the user and group editors.
  3. Review the privacy policy. The installation also provides a privacy policy page. This is controlled by the $_GUS_priv variable in the config.php file. If your site already has a privacy policy available to your site users, I would encourage you to review it and see that it is worded so that your site users know what information is being collected about them. If you allowed anonymous access, a link to the visitor statistics viewer is also added.
  4. There are several variables in the config.php file which control the display of information. These are documented in the file itself.
  5. As of version 1.2, GUS uses CSS when displaying the tables. It only includes the CSS file when you are viewing a GUS page. It first looks in <public_html>/gus/css for a file called {theme}.css - where {theme} is the name of the current theme. If it doesn't find it, it will use the default.css file included with the plugin. If you have created a CSS file for one of the common themes, send it to me and I will include it in future versions of GUS.

Importing Data From Stats

GUS will give you the option to import your data and ignored lists from the stats plugin version 1.3. You may do this either when you are installing GUS, or from the admin page. If you are going to do this, I recommend doing it as soon as you install GUS because if there are problems with the import, it may be difficult to recover.

Note that GUS does not use any of the tables from the stats plugin after the data has been imported, so it is safe to remove the stats plugin and all its tables.

Upgrading The Plugin

Upgrading GUS is very similar to installation:
  1. Backup your Geeklog database because upgrading may add or modify database tables. You can do this with the built in database backup facility in the Admin menu.
  2. Disable GUS using the admin interface's plugin editor [Admin->Plugins->gus]
  3. Make a backup of your config.php so you can update the new one with your settings.
  4. Uncompress the GUS plugin and copy the new files over the old ones as if it were a new installation.
  5. Enable GUS using the admin interface [Admin->Plugins->gus]
  6. Go back to the plugin editor for GUS [Admin->Plugins->gus] and click the 'Update' button.

Removing The Plugin

  1. Because the plugin modifies several database tables, it should always be removed through the interface provided. Log in to your Geeklog as a root user and go to the plugin administration page. Click the 'gus' link and then click the 'Delete' button. It will ask you to confirm it. Confirm it.
  2. Delete the three plugin directories created in the install process:
  3. There is no step three.

Things You Can Do

License

The GUS plugin is licensed under the GPL even though I don't really understand it and all its implications.

Why do we let legalese control the world?