% This LaTeX document was generated using the LaTeX backend of PlDoc,
% The SWI-Prolog documentation system



\subsection{library(http/http_log): HTTP Logging module}

\label{sec:httplog}

Simple module for logging HTTP requests to a file. Logging is enabled by
loading this file and ensure the setting http:logfile is not the empty
atom. The default file for writing the log is \verb$httpd.log$. See
\file{library(settings)} for details.

The level of logging can be modified using the multifile predicate
\qpredref{http_log}{nolog}{1} to hide HTTP request fields from the logfile and
\qpredref{http_log}{password_field}{1} to hide passwords from HTTP search
specifications (e.g. \verb$/topsecret?password=secret$).\vspace{0.7cm}

\begin{description}
    \predicate[semidet]{http_log_stream}{1}{-Stream}
True when \arg{Stream} is a stream to the opened HTTP log file. Opens the
log file in \const{append} mode if the file is not yet open. The log file
is determined from the setting \verb$http:logfile$. If this setting is
set to the empty atom (''), this predicate fails.

If a file error is encountered, this is reported using
\predref{print_message}{2}, after which this predicate silently fails. Opening
is retried every minute when a new message arrives.

Before opening the log file, the message \verb$http_log_open(Term)$ is
broadcasted. This message allows for creating the directory,
renaming, deleting or truncating an existing log file.

    \predicate[det]{http_log_close}{1}{+Reason}
If there is a currently open HTTP logfile, close it after adding
a term \verb$server(Reason, Time)$. to the logfile. This call is
intended for cooperation with the Unix logrotate facility
using the following schema:

\begin{itemize}
    \item Move logfile (the HTTP server keeps writing to the moved
file)
    \item Inform the server using an HTTP request that calls
\predref{http_log_close}{1}
    \item Compress the moved logfile
\end{itemize}

\begin{tags}
    \tag{author}
Suggested by Jacco van Ossenbruggen
\end{tags}

    \predicate[det]{http_log}{2}{+Format, +Args}
Write message from \arg{Format} and \arg{Args} to log-stream. See \predref{format}{2}
for details. Succeed without side effects if logging is not
enabled.

    \predicate[semidet,multifile]{password_field}{1}{+Field}
Multifile predicate that can be defined to hide passwords from
the logfile.

    \predicate[multifile]{nolog}{1}{+HTTPField}
Multifile predicate that can be defined to hide request
parameters from the request logfile.

    \predicate[semidet,multifile]{nolog_post_content_type}{1}{+Type}
Multifile hook called with the \verb$Content-type$ header. If the
hook succeeds, the POST data is not logged. For example, to stop
logging anything but application/json messages:

\begin{code}
:- multifile http_log:nolog_post_content_type/1.

http_log:nolog_post_content_type(Type) :-
   Type \= (application/json).
\end{code}

\begin{arguments}
\arg{Type} & is a term MainType/SubType \\
\end{arguments}

    \predicate[det]{post_data_encoded}{2}{?Bytes:string, ?Encoded:string}
Encode the POST body for inclusion into the HTTP log file. The
POST data is (in/de)flated using \predref{zopen}{3} and base64 encoded
using \dcgref{base64}{1}. The encoding makes long text messages shorter
and keeps readable logfiles if binary data is posted.

    \predicate[det]{http_logrotate}{1}{+Options}
Rotate the available log files. Note that there are two ways to
deal with the rotation of log files:

\begin{enumerate}
    \item Use the OS log rotation facility. In that case the OS must
(1) move the logfile and (2) have something calling
\predref{http_log_close}{1} to close the (moved) file and make this
server create a new one on the next log message. If
\file{library(http/http_unix_daemon)} is used, closing is
achieved by sending SIGHUP or SIGUSR1 to the process.
    \item Call this predicate at scheduled intervals. This can
be achieved by calling \predref{http_schedule_logrotate}{2} in the
context of \file{library(http/http_unix_daemon)} which schedules
the maintenance actions.
\end{enumerate}

\arg{Options}:

\begin{description}
    \termitem{min_size}{+Bytes}
Do not rotate if the log file is smaller than \arg{Bytes}.
The default is 1Mbytes.
    \termitem{keep_logs}{+Count}
Number of rotated log files to keep (default 10)
    \termitem{compress_logs}{+Format}
Compress the log files to the given format.
    \termitem{background}{+Boolean}
If \const{true}, rotate the log files in the background.
\end{description}

    \predicate{http_schedule_logrotate}{2}{When, Options}
Schedule log rotation based on maintenance broadcasts. \arg{When}
is one of:

\begin{description}
    \termitem{daily}{Hour:Min}
Run each day at \arg{Hour}:\arg{Min}. \arg{Min} is rounded to a multitude
of 5.
    \termitem{weekly}{Day, Hour:Min}
Run at the given \arg{Day} and Time each week. \arg{Day} is either a
number 1..7 (1 is Monday) or a weekday name or abbreviation.
    \termitem{monthly}{DayOfTheMonth, Hour:Min}
Run each month at the given Day (1..31). Note that not all
months have all days.
\end{description}

This must be used with a timer that broadcasts a
\verb$maintenance(_,_)$ message (see \predref{broadcast}{1}). Such a timer is part
of \file{library(http/http_unix_daemon)}.
\end{description}