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 httpd.log
. See
library(settings) for details.
The level of logging can be modified using the multifile predicate
http_log:nolog/1 to hide HTTP request fields from the logfile and
http_log:password_field/1 to hide passwords from HTTP search
specifications (e.g. /topsecret?password=secret
).
- log_error(+Error)[private]
- There was an error writing the log file. The message is printed
using print_message/2 and execution continues according to the
setting
http:on_log_error
, which is one of:
- retry
- Close the log file. The system will try to reopen it on the
next log event, recovering from the error. Note that the
most common case for this is probably running out of disc space.
- exit
- exit(Code)
- Stop the server using
halt(Code)
. The exit
variant is equivalent
to exit(1)
.
The best choice depends on your priorities. Using retry
gives
priority to keep the server running. Using exit
guarantees proper
log files and thus the ability to examine these for security
reasons. An attacker may try to flood the disc, causing a successful
DoS attack if exit
is used and the ability to interact without
being logged if retry
is used.
- http_log_stream(-Stream) is semidet
- True when Stream is a stream to the opened HTTP log file. Opens the
log file in
append
mode if the file is not yet open. The log file
is determined from the setting http:logfile
. If this setting is
set to the empty atom (''), this predicate fails.
If a file error is encountered, this is reported using
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 http_log_open(Term)
is
broadcasted. This message allows for creating the directory,
renaming, deleting or truncating an existing log file.
- http_log_close(+Reason) is det
- If there is a currently open HTTP logfile, close it after adding
a term
server(Reason, Time)
. to the logfile. This call is
intended for cooperation with the Unix logrotate facility
using the following schema:
- Move logfile (the HTTP server keeps writing to the moved
file)
- Inform the server using an HTTP request that calls
http_log_close/1
- Compress the moved logfile
- author
- - Suggested by Jacco van Ossenbruggen
- http_log(+Format, +Args) is det
- Write message from Format and Args to log-stream. See format/2
for details. Succeed without side effects if logging is not
enabled.
- log_started(+Request, +Id, +Stream) is det[private]
- Write log message that Request was started to Stream.
- Arguments:
-
Filled | - with sequence identifier for the request |
- log_request(+Request, -Log)[private]
- Remove passwords from the request to avoid sending them to the
logfiles.
- password_field(+Field) is semidet[multifile]
- Multifile predicate that can be defined to hide passwords from
the logfile.
- nolog(+HTTPField)[multifile]
- Multifile predicate that can be defined to hide request
parameters from the request logfile.
- nolog_post_content_type(+Type) is semidet[multifile]
- Multifile hook called with the
Content-type
header. If the
hook succeeds, the POST data is not logged. For example, to stop
logging anything but application/json messages:
:- multifile http_log:nolog_post_content_type/1.
http_log:nolog_post_content_type(Type) :-
Type \= (application/json).
- Arguments:
-
Type | - is a term MainType/SubType |
- add_post_data(+Request0, -Request) is det[private]
- Add a request field
post_data(Data)
if the setting
http:log_post_data is an integer > 0, the content length < this
setting and nolog_post_content_type/1 does not succeed on the
provided content type.
- post_data_encoded(?Bytes:string, ?Encoded:string) is det
- Encode the POST body for inclusion into the HTTP log file. The
POST data is (in/de)flated using zopen/3 and base64 encoded
using base64//1. The encoding makes long text messages shorter
and keeps readable logfiles if binary data is posted.
- log_completed(+Code, +Status, +Bytes, +Id, +CPU, +Stream) is det[private]
- Write log message to Stream from a call_cleanup/3 call.
- Arguments:
-
Status | - 2nd argument of call_cleanup/3 |
Id | - Term identifying the completed request |
CPU0 | - CPU time at time of entrance |
Stream | - Stream to write to (normally from http_log_stream/1). |
- log_check_deleted(+Stream) is semidet[private]
- If the link-count of the stream has dropped to zero, the file
has been deleted/moved. In this case the log file is closed and
log_check_deleted/6 will open a new one. This provides some
support for cleaning up the logfile without shutting down the
server.
- See also
- -
logrotate(1)
to manage logfiles on Unix systems.
- http_logrotate(+Options) is det
- Rotate the available log files. Note that there are two ways to
deal with the rotation of log files:
- Use the OS log rotation facility. In that case the OS must
(1) move the logfile and (2) have something calling
http_log_close/1 to close the (moved) file and make this
server create a new one on the next log message. If
library(http/http_unix_daemon) is used, closing is
achieved by sending SIGHUP or SIGUSR1 to the process.
- Call this predicate at scheduled intervals. This can
be achieved by calling http_schedule_logrotate/2 in the
context of library(http/http_unix_daemon) which schedules
the maintenance actions.
Options:
- min_size(+Bytes)
- Do not rotate if the log file is smaller than Bytes.
The default is 1Mbytes.
- keep_logs(+Count)
- Number of rotated log files to keep (default 10)
- compress_logs(+Format)
- Compress the log files to the given format.
- background(+Boolean)
- If
true
, rotate the log files in the background.
- compress_file(+File, +Format)[private]
- Compress a file according to Format. Currently only supports
gzip.
- http_schedule_logrotate(When, Options)
- Schedule log rotation based on maintenance broadcasts. When
is one of:
- daily(Hour:Min)
- Run each day at Hour:Min. Min is rounded to a multitude
of 5.
- weekly(Day, Hour:Min)
- Run at the given Day and Time each week. Day is either a
number 1..7 (1 is Monday) or a weekday name or abbreviation.
- monthly(DayOfTheMonth, Hour:Min)
- Run each month at the given Day (1..31). Note that not all
months have all days.
This must be used with a timer that broadcasts a
maintenance(_,_)
message (see broadcast/1). Such a timer is part
of library(http/http_unix_daemon).
- http_consider_logrotate[private]
- Perform a log rotation if the schedule is met