id: thalcgi_logging
type: listitem
list: userdoc
tags: userdoc
title: Thalassa CGI logging
format: texbreaks

Contents:<ul>
<li><a href="#overview">Available logging options</a></li>
<li><a href="#logger_configuration">Logger configuration</a></li>
</ul>

<h2 id="overview">Available logging options</h2>

Since Thalassa 0.3.70, the CGI program is capable of generating log
messages.  The logging is done with the
<a href="http://www.croco.net/software/loghorn/"><code>loghorn</code>
library</a>, 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 <code>stderr</code> stream.  Those a called <em>channels</em>.  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 <code>stderr</code> 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 <em>rumors</em> some other
HTTP servers handle CGIs' stderr that way or another.

<strong>By default, no logging is done at all</strong>.  The Thalassa CGI
program will not bother with any logging unless you explicitly order it to
do so.

The <code>loghorn</code> library supports five levels of
<em>verbosity</em>, named <code>alert</code>, <code>normal</code>,
<code>info</code>, <code>debug</code> and <code>debug2</code>.  Each
message sent to the library is assigned its <em>minimum</em> 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 <em>maximum</em> verbosity level, which means it
rejects messages with the level higher than that.  It is useful to
know the <code>debug2</code> 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
<em>importance level</em> <code>LOG_ERR</code>, <code>LOG_NOTICE</code>,
<code>LOG_INFO</code> and <code>LOG_DEBUG</code>, 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 <code>alert</code> type for
reporting errors presumably caused by local conditions; errors caused by
the clients' activity are not reported this way.
The <code>normal</code> 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 <code>info</code> 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 <code>debug</code> level contain a lot of information,
mostly useless for you until you <em>really</em> perform debugging of the
CGI program, and the <code>debug2</code> level messages are mostly useless
even for the Thalassa developers.



<h2 id="logger_configuration">Logger configuration</h2>

The dedicated log file section named <code>[logging]</code> 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:<ul>

<li><code>syslog</code>, <code>file</code> and <code>stderr</code>
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: <code>alert</code>, <code>normal</code>,
<code>info</code>, <code>debug</code> and <code>debug2</code> set the
verbosity level of the same name (<code>debug2</code> is not supported for
the <code>syslog</code> channel), <code>none</code>, <code>disable</code>
and <code>disabled</code> disable the channel, but it is perhaps much
easier just to leave the parameter's value empty, which has exactly the
same effect.</li>

<li><code>syslog_facility</code> and <code>syslog_ident</code> determine
the <em>facility</em> and the <em>identity</em> for the messages sent to
the system logger.  For the facility, the following values are recognized:
<code>default</code>, <code>user</code>, <code>daemon</code>,
<code>local0</code>, <code>local1</code>, ..., <code>local7</code>;
<code>default</code> and <code>user</code> have exactly the same meaning,
and the same thing happens in case the parameter is omitted or left empty.
For the <em>identity</em>, the default is <code>thalassa</code>.  See
<code>man 3 openlog</code> for more information on this.</li>

<li><code>file_name</code> sets the file name for the <code>file</code>
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
<code>/dev/null</code>, heh.</li>

</ul>


Here is an example of the section:
<pre>
  [logging]

  syslog = alert
  syslog_facility = local3
  syslog_ident = my_website_cgi

  file = normal
  file_name = /var/www/MySite/the_cgi_log

  stderr = none
</pre>
