Contents:
Since Thalassa 0.3.70, the CGI program is capable of generating log
messages. The logging is done with the
loghorn
library, which, basically, allows to send the log messages to the
system logger, write the same messages to a specified text file and/or to
the stderr stream. Those a called channels. The
library also supports custom channels, but Thalassa doesn't use this
feature.
It is important to understand the channels are configured independently.
It is also worth mentioning that CGI's stderr goes nowhere, at
least with Apache, but one can use some wrapper programs to catch it.
Never mind, it is more convenient to use a log file; the possibility to log
to the stderr is still there because there are rumors some other
HTTP servers handle CGIs' stderr that way or another.
By default, no logging is done at all. The Thalassa CGI program will not bother with any logging unless you explicitly order it to do so.
The loghorn library supports five levels of
verbosity, named alert, normal,
info, debug and debug2. Each
message sent to the library is assigned its minimum verbosity
level, which means that for lower verbosity level the message is ignored;
on the other hand, each logging channel, if it is enabled at all, is
configured with its maximum verbosity level, which means it
rejects messages with the level higher than that. It is useful to
know the debug2 level can not be configured for the system
logger, so messages of that level are never sent to the syslog, only to the
file streams (in case the same level is set on them); messages of the other
four levels, being sent to the system logger, are assigned the
importance level LOG_ERR, LOG_NOTICE,
LOG_INFO and LOG_DEBUG, accordingly; this means
the system logger configuration may silently drop some of the messages on
its own.
The Thalassa CGI program uses messages of the alert type for
reporting errors presumably caused by local conditions; errors caused by
the clients' activity are not reported this way.
The normal type is used when the users take
actions that have persistent consequences, such as establishing a new user
account, creating, editing and deleting a comment, sending an email through
the contact form. On the info level, events that have no
persistent results are logged: generally, at least one message of this
level is generated per each script run, just to log the client's ip address
and some other details, and separate messages of the same level are issued
on establishing work sessions, users logging in and logging out, etc.
Errors caused by clients are reported here, too. The
messages of the debug level contain a lot of information,
mostly useless for you until you really perform debugging of the
CGI program, and the debug2 level messages are mostly useless
even for the Thalassa developers.
The dedicated log file section named [logging] controls where
the log messages go. If the section is omitted altogether, no logging will
be done, which is exactly what the program did before the logging subsystem
was added. The following parameters are supported for the section:
syslog, file and stderr
determine if each of the channels (system logger, custom log file and the
stderr stream, accordingly) is enabled and what verbosity level it has.
The following values are recognized: alert, normal,
info, debug and debug2 set the
verbosity level of the same name (debug2 is not supported for
the syslog channel), none, disable
and disabled disable the channel, but it is perhaps much
easier just to leave the parameter's value empty, which has exactly the
same effect.syslog_facility and syslog_ident determine
the facility and the identity for the messages sent to
the system logger. For the facility, the following values are recognized:
default, user, daemon,
local0, local1, ..., local7;
default and user have exactly the same meaning,
and the same thing happens in case the parameter is omitted or left empty.
For the identity, the default is thalassa. See
man 3 openlog for more information on this.file_name sets the file name for the file
chhannel. No default is provided, so if you enable the channel but forget
to set the file name, it won't work. One can assume the default is
/dev/null, heh.Here is an example of the section:
[logging] syslog = alert syslog_facility = local3 syslog_ident = my_website_cgi file = normal file_name = /var/www/MySite/the_cgi_log stderr = none