3.3 Tracing and Debugging

The amount of information logged by the server is configurable. By default, it is quite silent and outputs only diagnostics that call to special attention, such as errors and the like. You may request more information, however. For further discussion, it is convenient to introduce two main information groups: query traces and debugging information. Query traces are log messages that show received queries and corresponding replies. They look like:

 
user bar => NOTFOUND
access connect:111.67.206.187 => OK REJECT

The part to the left of the ‘=>’ sign shows the query exactly as received from the client, i.e. the first word is the map name, and the rest of words constitute the key. The part to the right of ‘=>’ is the reply to this query.

To enable query traces, use the ‘--trace’ (‘-T’) command line option or ‘trace yes’ statement in the configuration file.

When using syslog, query traces are reported using the ‘info’ priority.

Some requests may be of particular interest to you, whereas others may not be relevant at all. There is a way to abridge the traces to show those relevant requests only. If you give the ‘--trace-pattern=pattern’ option, only those requests that begin with pattern(5) will be shown. For example, to show only positive responses, use

 
--trace --trace-pattern=OK

The same can be requested in the configuration file as well:

 
trace yes
trace-pattern OK

Any number of ‘--trace-pattern’ options (or configuration statements) may be given. The server will log only those queries that match one of the patterns specified by them.

Debugging information is auxiliary diagnostics reflecting various details of internal functionality of smapd. Although aimed primarily to help in debugging the server, it may occasionally be of use for server administrators as well.

Debugging information is requested using the ‘--debug’ (‘-d’) command line option or ‘debug’ configuration statement. In both cases, the argument is a debug specification, consisting of two parts, separated by a dot: ‘cat.lev’. The cat part is a debug category. It is either an integer number identifying the category, or its symbolic names. For a list of categories and their meaning, see Debug Categories.

The lev part is the category level, an integer specifying how much verbosity is requested from that category. The ‘0’ value means no verbosity (i.e. to disable that category), the value of ‘100’ means maximum verbosity. The convention is that levels below ‘10’ may be of occasional use for sysadmins, whereas higher values are useful only for debugging.

To enable several debug categories, use several ‘--debug’ option (or ‘debug’ configuration statements).

Footnotes

(5)

Actually, the argument would better be named prefix, but I plan to implement globbing patterns (or maybe even regular expressions) in future versions, so I refer to it as pattern in anticipation.