FAQ: Using Debugging Output

How can I debug my custom log format, or my log filters?

Short Answer

Build the database from the command line with the -v option: sawmill -p profilename -a bd -v egblpfd.

Long Answer

Custom log formats and log filters can be difficult to debug from the graphical interface, because there is little feedback about what Sawmill is doing as it processes the log. Fortunately, Sawmill has a powerful feature called "debugging output" that makes debugging custom log formats and filters much easier.

To see the debugging output, you need to use a command-line version of Sawmill. On Windows, that means using the SawmillCL.exe program, and running it from the command prompt. On Unix, you can use the normal Sawmill executable, since it works on the command line. On MacOS, you need to use the MacOS X command-line version of Sawmill.

Using the command shell, go to the Sawmill installation directory (using the "cd" command). Then rebuild the database like this:

  sawmill -p profilename -a bd -v egblpfd | more

This command rebuilds the database for the profilename profile, and -v egblpfd tells Sawmill to report a great deal of information about what it's doing (other -v options are available, but egblpfd are the seven options which are most useful for debugging profiles and filters). The results are piped through the "more" program, so you can page through the output using the space bar. Lines starting with "Processing line" show when Sawmill is processing a new log line. Lines starting with "Marking hits" show the end results that are being put into the database. Other lines provide information about log parsing and filtering that can be very useful when you're trying to debug a problem in the parsing of your custom format, or in your custom log filter.