Readme for analog -- debugging

[ Top | Up | Prev | Next | Map | Index ]

# Analog 6.0: Debugging

This section lists commands to help you debug analog, if you think it's going wrong. There's another section later which lists all the errors and warnings which analog can generate, and what they all mean, and another section which tells you how to report bugs.

First, remember the option we mentioned before, to list the current settings of all of analog's variables. To get this, just put `-settings` on the command line, or `SETTINGS ON` in one of your configuration files, along with your other commands. Then analog will produce the list of settings instead of running in the normal way.

There are commands which control how much debugging information and warning information analog gives out while it is running. By default you get all the warnings and no debugging, but you can change this by means of the commands `DEBUG` and `WARNINGS`. If you say

    DEBUG ON

you get all the debugging. (And `DEBUG OFF` turns it all off.) You can also get just certain categories of debugging. The categories are

`C`
  list all corrupt logfile lines
`D`
  information about DNS lookups
`F`
  information about file opening and closing
`S`
  summary information about each logfile when it's closed
`U`
  list unknown domains
`V`
  list hosts without a domain (i.e., without a dot)

So, for example, the command

    DEBUG FS

would give you information about file opening and closing, and what was in each logfile, but none of the other sorts of debugging. Each line of debugging information is prepended with its code letter. You can also specify

    DEBUG +CD

to add `C` and `D` category debugging to whatever you've already got, and

    DEBUG -CD

to remove those two categories.

There is also a command line abbreviation for this command. Use `+V` (for `ON`), `-V` (for `OFF`), `+VFS` (to select exactly options `FS`), `+V+FS` (to add those options), and `+V-FS` (to remove them).

The `C` messages actually come on two lines. The first line gives the logfile line which was corrupt. The second line indicates where analog first noticed a problem. (This is usually, but not always, close to where the problem actually was!) In fact, each "line" of the message may spread over more than one line on your screen, and you have to be careful to take that into account when trying to find out where the logfile line was corrupt.

The `WARNINGS` command acts similarly to the `DEBUG` command (see the syntax above). By default all warnings are on. As well as `WARNINGS ON` and `WARNINGS OFF`, you can turn warnings on and off in the following categories.

`C`
  invalid configuration specified
`D`
  dubious configuration specified
`E`
  `ERRFILE` command used (see below)
`F`
  files missing or corrupt
`L`
  apparent problems in logfiles
`M`
  possible problems in logfiles
`R`
  turning off empty reports

See the section on Errors and warnings for more details about the various categories. Again, warnings are printed with their code letters.

Warnings range from the probably harmless to the usually serious. So it is generally not a good idea to turn all warnings off, or you might miss some important information. If you want to ignore a particular warning, turn just its category off.

There is also a command line version of the `WARNINGS` command, looking like `+q`, `-q`, `+q<options>`, `+q+<options>` or `+q-<options>`. (The syntax is the same as the `+V` command above.)

By default all these messages go to standard error, which is normally just the screen. But you can change that by means of a command like

    ERRFILE newfile

If you do this, analog will warn you that it's redirecting the messages, just so that you don't miss any. To change back to standard error, use

    ERRFILE stderr

The `ERRFILE` command will also erase any previous contents of that file. (So don't use the same `ERRFILE` command twice, or you may lose messages!) If the name of the `ERRFILE` doesn't include a directory, it will be put in whichever directory was specified for that purpose when the program was compiled. For example, on Windows it would be in the same folder as the analog executable.

There is a command called `ERRLINELENGTH` to tell analog the width of screen you want these messages to fit in. As a special case,

    ERRLINELENGTH 0

specifies an unlimited screen width.

There is one more command which is useful when trying to debug analog. If you give the command

    PROGRESSFREQ 20000  # say

then analog will produce a little message after every 20,000 lines it reads from the logfile. (This message is sent to the screen and to the `ERRFILE`.) This is useful to determine whether the program has really stopped or (as is more likely) is just being slow for some reason (such as using DNS lookups).

There is just one more section about analog's configuration commands and command line arguments, but it's a rather long one, on the form interface. (This is a way of running analog by selecting options from a web page.) You might prefer to go straight onto the section on What the results mean.

Go to the analog home page.

Need help with analog? Use the analog-help mailing list.

[ Top | Up | Prev | Next | Map | Index ]