Home | About | Download | Docs | Screenshots | Links | Sourceforge | Logo Donate 
to this project


Using Scratchy

Scratchy currently consists of 2 executable python scripts, namely parse and report. Under normal usage, there is no need to execute report because the parse program automatically generates reports as necessary. Typically, the report script can be executed to rebuild an existing report, perhaps using a different config file.


In order to run the excutables within Scratchy you will need to obtain version 2.1 or greater of
Python, Most Linux/Unix distributions include Python, however, depending on your distro the version may not be as recent as 2.1. You can determine the version of Python installed on your system by executing the following command:

$ python -V
Python 2.1

Scratchy also requires a SQL database. Currently, MySQL and SQLite are supported. Please see choosing the SQL database for more information.
NOTE: SQLite is not currently supported although the latest Scratchy release contains preliminary support it is considerer experiental and not fully documented (and hasn't been tested, in other words, don't use it!).

If you wish for Scratchy to produce bar charts of the parsed data then you will also need the ChartDirector Python API (and optionally, the ChartDirectorScratchy library). The fully-functional ChartDirector trial library adds a yellow banner to each chart it creates. The fine folks at Advanced Software Engineering have created a custom replacement library for the Scratchy project which replaces the yellow banner with a more pleasant transparent image. This replacement library should be installed after ChartDirector is installed and is available for download.


First off, you will need an Apache server log file (typically, located in /var/log/apache or /usr/local/apache/logs). Currently, only the combined log format is supported (others may work, but I haven't tried them yet).

Scratchy ships with a file named config.dist you should copy this file to config if you have only one web server that you are monitoring. If you have multiple distinct servers (such as your default site and then a dedicated search server or user server) you may wish to parse these into separate reports. It's up to you. If you wish to parse them all into one report then you will only need one config file. If however you wish to have distinct reports then you will want to create a config for each report. Under this scenario you may want a config_www, config_search and a config_user.

The config file, at the very least contains central information for the parser and reporter scripts. The config file may also contain other preferences such as color schemes and data limits for the reporter. You may want to explore the settings of the Config file.

Create the database

Assuming you have created one or more config files you must now create the SQL database. To do this, go to the Scratchy/scripts directory and execute the following:

$ cd scripts
$ python -c ../your-config-file

You are now ready to run the parser.