selog(7) selog(7) NAME selog - selective logging configuration DESCRIPTION Selog is a library of routines for error reporting, activity logging, and debug tracing. It gives users flexible control over which messages are written and where they are written to. Messages are classified using "selectors" that determine their priority level (e.g. debug or info or error, etc.) and category (the part of the program that they relate to). You can selectively enable or disable messages based on their selectors using a simple textual configuration. In some cases you may be given fine control over the verbosity of a message, beyond just switching it on or off, using separate selectors that control optional parts of the message. Enabled messages are written to one or more channels, as specified by the configuration. Several kinds of channel are supported, including the standard error stream, syslog, files, etc. You can configure selog to write messages with different selectors to different sets of output channels. This manual describes how you can configure selog, and the behaviour of selog's output channels. The programmer's interface to selog is described in selog(3), as are the auxiliary libraries that can be used to replace the standard err(3) and syslog(3) interfaces with implemen- tations based on selog. CONFIGURATION Given a selector defined by the program, selog needs to determine (for message selectors) where messages controlled by the selector are to be written, or (for option selectors) whether the selector is enabled or not. To do this, it scans the configuration string provided by the user, which comprises a sequence of selection items and channel items. The selector has a notional on/off state which is manipulated as the configuration string is scanned. The initial state of a message selec- tor is on iff its level is "info" or above. (That is, there is an implicit "+default" at the start of the configuration string.) Option selectors can start in either state. If the selector matches a selection item, it is switched on or off according to whether the first character of the item is "+" or "-". If the selector does not match a selection item then its state remains unchanged. If the selector is on when a channel item is encountered, then messages controlled by the selector are written to the channel specified by the item. If there are trailing selection items not followed by a channel item, then selog appends an implicit "@stderr" channel item. An option selector is enabled if it is enabled for any channel, and disabled only if it is disabled for all channels. This implies that it is best to group option selection items at the start of the configura- tion string, so that turning off a default-on option works as expected. Syntax The formal syntax is described using ABNF (RFC 4234). Items may be terminated by semicolons, which are optional except between a channel item and a following selection item. White space may be freely inserted between tokens. Space is only required to separate the arguments of a channel item. config = SP *(*selection *channel ";") *selection *channel space = %x20 / %x09 / %x0A / %x0D SP = *space SEP = 1*space TERM = *(space / ";") Selection items A selection item starts with a "+" if it is to enable selectors, or a "-" if it is to disable them. If this is followed by a category name then only selectors with the given name will match. The category name may be followed by a level comparison. If the opera- tor is "<" then the selector matches if its level is less than or equal to the given level. If the operator is "=" then the selector matches if its level is the same as the given level. If the operator is ">" or "." then the selector matches if its level is greater than or equal to the given level. If the comparison is omitted then it is equivalent to ">all". If the category name is omitted, any selector matches if its level matches. In this case a ">" comparison operator can be omitted. selection = sign category compare level TERM / sign category TERM / sign compare level TERM / sign level TERM sign = ("+" / "-") SP compare = ("<" / "=" / ">" / ".") SP ; In order of increasing priority: level = "trace" / "debug" / "all" / "option" / "option_off" / "opt_off" / "verbose" / "default" / "option_on" / "opt_on" / "info" / "notice" / "warning" / "warn" / "error" / "err" / "critical" / "crit" / "alert" / "emergency" / "emerg" / "fatal" / "exit" / "abort" category = *catchar SP catchar = %x21-2A / %x2C / %x2F-3A / %x3F / %x41-7E / %x80-FF ; all visible characters except + - . ; < = > @ Option selectors are distinguished from message selectors by having one of two special levels. The "default" level is used for options that are on by default, and the "option" level is used for options that are off by default. So, for example, you can turn on all options without turning on "verbose" messages using the selection item "+=option". The level name "all" is a synonym for "option" that is useful when you want to enable all non-debug message selectors and all option selectors. Message selectors with a higher level than "default" are also on by default. Channel items A channel item starts with an "@" and a keyword indicating what kind of channel it is. If the keyword is not recognised then if it starts with a "/" it is treated as the first argument following a "file" keyword, and if it starts with a "|" the rest is treated as the first argument following a "pipe" keyword. (In other words, "file" keywords can be omitted, and "|" is a synonym for "pipe".) The keyword may be followed by space-separated arguments as required. The details of each kind of channel are described in the next section. channel = "@" SP kind *(SEP argument) TERM kind = "file" / "pipe" / "rotate" / "stderr" / "stdout" / "syslog" / "|" argument / argument argument = *argchar argchar = %x21-3A / %x3C-3F / %x41-7E / %x80-FF ; all visible characters except ; @ CHANNELS The following sub-sections describe the details of each kind of chan- nel, the arguments they require after their keywords in the configura- tion string, and any differences from the usual message format described in the next section. stderr The stderr channel writes its messages to the standard error stream (file descriptor 2). It takes no arguments. The time stamp and host name are omitted. stdout The stdout channel writes its messages to the standard output stream (file descriptor 1) and is otherwise the same as the stderr channel. file The file channel's first argument is an absolute path to the log file. (Because arguments are separated with white space, the path name cannot contain spaces.) It takes an optional second argument which is the numeric access mode to be used when creating the file. The default mode is 0666. The mode is affected by the process's umask setting. Messages are appended in a way that is compatible with multiple pro- grams logging to the same file concurrently. Selog automatically re- opens the file when it detects that it has been moved aside, so there is no need to HUP the process(es) when the log is rotated. If the log_rotate option is enabled then the file channel behaves like the rotate channel. The host name is ommitted from the messages. rotate The rotate channel is very similar to the file channel, except that it automatically opens a new log file at midnight. The given file name has a date stamp appended in the format ".YYYY-MM-DD". By default mid- night is local time, unless the log_zulu option is enabled. pipe The arguments to the pipe channel are a command-line that is passed to the shell to start a sub-process. Messages are written to the sub- process's standard input stream via a pipe. syslog The syslog channel takes a single argument which is a syslog facility name, i.e. one of: user uucp local1 local0 mail cron local2 daemon authpriv local3 auth ftp local4 syslog ntp local5 lpr security local6 news console local7 Messages are written to the system log socket using the facility speci- fied by the channel configuration and a severity derived from the mes- sage selector. Most selog levels map directly to syslog severities. Those that do not map as follows: SELOG_TRACE LOG_DEBUG SELOG_VERBOSE LOG_INFO SELOG_FATAL LOG_CRIT SELOG_ABORT LOG_ALERT The time stamp is in the standard syslog format and is in local time unless the log_zulu option is set. The host name is omitted because syslogd(8) adds it when necessary. MESSAGE FORMAT As well as determining where messages are written, the channel type also affects the format of the message prefix. For example, syslog has its own time stamp format. Messages written by selog follow the same general scheme, though parts are often omitted depending on the partic- ular message and the channel it is written to. time host prog[pid] file:line func() name level: message: error time The time the message was written. Except for syslog, the format is similar to ISO 8601 / RFC 3339. (For readability the "T" separator is replaced with a space and a space is added before the time zone). YYYY-MM-DD hh:mm:ss.fff +ZZ:ZZ YYYY year 2008 MM month 04 DD day 30 hh hour 23 mm minute 01 ss second 59 fff fraction .500 ZZZZ time zone +01:00 Fractional seconds are usually omitted. They can be enabled to millisecond precision using the log_msec option, and to microsecond precision using the log_usec option. By default the time stamp is in local time. Positive time zone offsets are ahead of UTC (East of Greenwich). You can choose UTC time stamps using the log_zulu option, in which case the time zone is written as "Z" instead of as a numeric offset. You can omit the time zone by turning off the log_tz option, though this is unwise especially if you are logging local time in a place which is subject to daylight saving variations. host The fully-qualified host name of the machine that generated the message. prog[pid] The program name and process ID. The pid field is turned on using the log_pid option. The precise format of the preceding fields, and whether or not they are present, depends on the channel, as described in the previous section. The presence of the following fields depends on the message. file:line The source code file and line number where the message is gener- ated. This is usually omitted except by "trace" messages. func() The source function where the message is generated. This is usually omitted except by "trace" messages. func() The source function where the message is generated. This is usually omitted except by "trace" messages. name The message selector's category name. level The message selector's level. mesage The main part of the message, which has no particular format. error Operating system errors are generally added to the end of the message after a colon. DIAGNOSTICS This section lists the built-in selectors used by selog itself. Selec- tors are written {category, LEVEL}. {log_config, ERROR} This is used by selog to report configuration syntax errors. Because it is used before selog is fully initialized, the mes- sages it controls are always written to the standard error stream. {log_msec, OPTION_OFF} For logging time stamps to millisecond accuracy. Overridden by log_usec. {log_panic, FATAL} If an error occurs when selog is writing a message, it tries to write the error using the log_panic selector before exiting the program. {log_pid, OPTION_OFF} For enabling the process ID field. {log_rotate, OPTION_OFF} For enabling auto-rotation of file channels. {log_tz, OPTION_ON} For disabling the time zone field. This is unwise especially if you are logging local time in a place which is subject to day- light saving variations. {log_usec, OPTION_OFF} For logging time stamps to millisecond accuracy. Overrides log_msec. {log_zulu, OPTION_OFF} For logging in UTC instead of local time. ENVIRONMENT SELOG_CONFIG Overrides the configuration string passed to selog by the pro- gram. SEE ALSO selog(3), syslogd(8) RFC 5234: Augmented BNF for Syntax Specifications: ABNF, by Dave Crocker (ed.), Paul Overell, January 2008. RFC 3339: Date and time on the Internet: Timestamps, by Graham Klyne (ed.), Chris Newman, July 2002. AUTHOR Written by Tony Finch at the University of Cambridge Computing Service. Source available from selog(7)