Using Sawmill

This page provides simple instructions and guidelines for using Sawmill, especially for the first time. Common uses are described with examples and more indepth links for creating filters, reports and power user techniques.

Creating a profile

When you create a profile, Sawmill asks you for the log source. The log data can come from a file, a collection of files, or from the output of an arbitrary command (this last option is available only on UNIX and Windows). The files can be local, or Sawmill can download them from an FTP site (you can use a standard FTP URL to specify the location of the files). They can also come from a single file downloaded by HTTP. Sawmill supports and automatically detects a wide range of log formats.

Once you have told Sawmill where your log data is, Sawmill will create a profile for you using reasonable values for all the options. You can then click "View Reports" to see the reports -- Sawmill will read and process the log data to build its database, and then will display the reports. You could also click "View Config" to customize any of the profile settings. Sawmill's options can be confusing at first because there are so many of them, but you don't need to change any of them if you don't want to. A good way to start is to leave them all alone at first, and just look at the reports, using all the default settings. Once you're familiar with your statistics using the default settings, you can go back and start changing them if necessary. Options you may eventually decide to change especially include the Log Filters, which let you include or exclude log data from your database (see Using Log Filters) and the Reports, which lets you customize existing reports and create new ones. For performance tuning, you may also want to edit the cross-references or the database fields (see Cross-Referencing and Simultaneous Filters).

You can use the Log Filters, within the View Config menu, to specify a complex set of filters to control exactly which log entries you are interested in, and which you are not. Some common filters are pre-defined, but you may want to enhance the pre-defined filter set with your own filters, or you may want to remove pre-defined filters. See Using Log Filters for more information and examples.

Viewing Reports

You can view reports at any time by clicking View Reports next to the name of a profile in the administrative profile list. You can also switch to the reports when you're editing the profile options by clicking the View Reports link in the upper right. For information on using and navigating the statistics pages, see Reports.

Building and Updating Databases from the Command Line

You can build and update databases from the graphical interface, but in some cases you may prefer to use the command line to build or update databases. The command line is useful, for instance, if you want to automatically and regularly update the database with the latest log entries (this can also be done from the scheduler; see Using the Sawmill Scheduler). For instance, it is possible to set up a cron job on a UNIX system to automatically update the database every day with the previous day's log. The command line would look something like this:

  sawmill -p profilename -a ud

This command line updates the database for the profile profilename. See Power User Techniques for more examples of command line usage.

For More Information

The Create New Profile process creates a profile with default settings, which is generally a good starting point. After that, it's up to you to fine-tune it if you want. There is a wealth of options in The Config Page, letting you control everything from the speed of log file processing to the color of graphs bars. To get the most out of Sawmill, you should spend some time looking over these options, or browsing the All Options page.