Enswitch logging

Logging by Enswitch processes is controlled by /etc/enswitch/logs.ini. This includes routed, sipd, fees, the JSON API, and all other code written by Integrics. It does not affect code written by third parties such as Asterisk, Kamailio, and mysqld, which have their own logging.

logs.ini is arranged into sections. With the exception of the [rotation] section (see below), the section names are not used and are only for your convenience. Each normal section may contain the following fields:

type: "file" to log to a file, "syslog" to log to syslog.
file: The file to log to. Only used if type is file. This field may contain variables; see below.
format: The format to log in. Only used if type is file. This field may contain variables; see below.
facility: The facility to log as. Only used if type is syslog.
backtrace: List of levels (space separated) where backtrace will be added. Only used if type is "file". Default is "error warn".
recreate: "yes" to re-create the log file as an empty file after rotation, "no" not to. Only used if type is "file" and the file name does not contain any variables. Default is "no".
error, warn, info, auth, debug, api, sql: Whether to log messages of this level. If type is file, use a value of "yes" to log messages of this level, and a value of "no" (or omit the line) not to. If type is syslog, use a syslog severity level (see below) to log to syslog with this severity, or "no" (or omit the line) not to log.

New levels may be added in future versions of Enswitch.

Variables

When logging to a file, the file and format fields may contain variables. Allowed variables are:

%a: The activity message being logged.
%c: The command doing the logging, or empty string if none.
%d: The day of the month as two digits, from 01 to 31.
%H: The hour as two digits, from 00 to 23.
%i: The source IP address making the request, or empty string if none.
%l: The level.
%M: The minute as two digits, from 00 to 59.
%m: The month as two digits, from 01 to 12.
%p: The PID of the process doing the logging.
%S: The second as two digits, from 00 to 59. Leap seconds are ignored as per Unix time.
%t: Function backtrace dump.
%Y: The year as four digits.
%%: A literal percent sign.

The date and time variables correspond to the Unix date(1) format. For the current date and time, "%Y-%m-%d %H:%M:%S" is suggested. New variables may be added in future versions of Enswitch.

syslog destination

By default syslog will send logs to local syslogd. To change this set the "protocol" field to "tcp" or "udp". In this case you should also set the "host", "port", and optionally the "timeout" fields. For example:

[syslog]
type = syslog
facility = local3
protocol = tcp
host = 1.2.3.4
port = 514
timeout = 5
...

syslog severity levels

When logging to syslog, each Enswitch level can be mapped to a chosen syslog severity. For example, "error = err" will map Enswitch's "error" level to syslog's "err" severity. Allowed values of syslog severity are "alert", "crit", "debug", "emerg", "err", "info", "notice", and "warning". These values are case insensitive. Any other value will cause the level to not be logged.

Log rotation

It's important to rotate log files to prevent disks filling up. If a special [rotation] section exists in logs.ini, then Enswitch will rotate log files in the chosen directory. If the [rotation] section does not exist, or is commented out, then Enswitch will assume that some other process is handling log rotation, and will do nothing.

The [rotation] section may contain the following fields:

directory: The directory to rotate log files in. If not specified, defaults to /var/log/enswitch.
delete_days: Files with an mtime more than this many days are deleted.
delete_pattern: Only delete files matching this regular expression. If not specified, all files older than delete_days will be deleted.
gzip_days: Files with an mtime more than this many days are compressed using gzip.
gzip_pattern: Only gzip files matching this regular expression. If not specified, all files older than gzip_days are gzipped, which could result in files being gzipped more than once.
gzip_level: The gzip level to use. If not specified, defaults to 9.
move_destination: This should only be used with log files that do not contain the date, such as "trace.log". If set, moves files to a different name. The value of this field controls the destination used. At present, "date" is the only allowed value. This value moves the file to one containing the date, for example "trace.log" to "trace_2000-01-01.log".
move_days: Files with an mtime more than this many days are moved according to move_destination.
move_suffix: A regular expression to match the suffix part of log files moved by move_destination. The suffix is kept after the date. Do not include a "$" to match the end of string.

mtime means the last modification time of the time, as reported by "ls -l". Since log rotation is run once per day from cron, files may be up to one day older than the number of days specified. Regular expressions are Perl-style, and matched case-sensitively against the full path of the file name.

Example: logs.ini for production system, using log files with dates

[trace]
type = file
file = /var/log/enswitch/trace_%Y-%m-%d.log
format = %Y-%m-%d %H:%M:%S (%i) [%p] %l: %c %a %t
error = yes
warn = yes
info = yes
auth = yes

[syslog]
type = syslog
facility = local3
error = err
warn = warning
info = info
auth = info
debug = debug

[rotation]
directory = /var/log/enswitch
gzip_days = 1
gzip_level = 9
gzip_pattern = \.log$
delete_days = 32
delete_pattern = \.gz$

Example: logs.ini for development system, using log files with static names

[trace]
type = file
file = /var/log/enswitch/trace.log
format = %Y-%m-%d %H:%M:%S (%i) [%p] %l: %c %a %t
error = yes
warn = yes
info = yes
auth = yes
debug = yes

[api]
type = file
file = /var/log/enswitch/api.log
format = %Y-%m-%d %H:%M:%S: %c %a %t
api = yes

[sql]
type = file
file = /var/log/enswitch/sql.log
format = %Y-%m-%d %H:%M:%S: %c %a %t
sql = yes

[syslog]
type = syslog
error = err
warn = warning
info = info

[rotation]
directory = /var/log/enswitch
move_destination = date
move_days = 0
move_pattern = \/\D+.log$
move_suffix = \.log
gzip_days = 1
gzip_level = 9
gzip_pattern = _\d{4}\-\d{2}\-\d{2}\.log$
delete_days = 32
delete_pattern = \.gz$