The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Log::Common - log messages in the httpd access and error log styles

SYNOPSIS

  use Log::Common;

  $l = new Log::Common(access => "/var/log/search-hits",
                       error  => "/usr/local/log/error_log",
                       no_stderr => 1,
                       class => "debug");

  $l->error(message => "Uh-oh... :-(", fatal => 1);
  $l->access(user => "martin", message => "$query_string",
               code => 200);

DESCRIPTION

This class defines two methods which may be used to write messages to httpd common log file style access and error log files, such as those maintained by the Apache and NCSA WWW servers. The log file is locked whilst being written to avoid corruption when multiple processes attempt to write to the same file at the same time. For convenience both methods support a parameter which, if specified, results in "exit" being called to bomb out of the program.

If the environmental variable GATEWAY_INTERFACE isn't set, error messages are also sent to STDERR - though this behaviour can be overridden if undesired. This is so that Perl programs which use this class can trivially dump out messages both to their end user and to a system log file at the same time.

Error log file entries are written with a leading UTC timestamp, in the common HTTP server usage.

METHODS

access( [ OPTIONS ] );
error( [ OPTIONS ] );

PARAMETERS

When creating a Log::Common object:

access => access_log_filename

This is the filename to use when logging via the access method.

error => error_log_filename

This is the filename to use when logging via the error method.

class => class_name

The default class of error log messages. You can use this to distinguish between debugging info, security related info, messages from WWW servers, messages from the mail system, and so on. This default value can be overridden in an individual call to the error logging method.

no_stderr => 0 or 1

Suppress the printing of the message to STDERR if set to 1, defaults to 0. This can be overridden when the error method is invoked.

Common to both methods:

fatal => exit_code

This indicates that whatever happened was a fatal error, and causes the program to croak after the log file entry has been written. The value given will be used as the program's exit code.

message => message_string

The actual message to write to the log file.

For the access method only:

count => number

Normally the number of bytes transferred - 0 if not supplied.

code => response_code

Normally the number of bytes transferred - 0 if not supplied.

host => host_name

The domain name or IP address of the calling/client host. If not supplied, the process environment will be checked for REMOTE_HOST and REMOTE_ADDR (as set by CGI) in turn. If neither of these is present this field in the log file will be set to 0.0.0.0.

ident => value_of_ident_lookup

Normally the result of an IDENT (AUTH) lookup on the calling host and port. If not supplied, the value of REMOTE_IDENT in the process environment will be used, or "-".

user => authenticated_user_name

Normally the user name which has been authenticated, e.g. using basic HTTP authentication. If not supplied, the value of REMOTE_USER in the process environment will be used instead, or "-".

For the error method only:

class => class_name

Overrides default setting for this invocation - see above.

info => info_string

Additional info - this will be rendered enclosed in round brackets at the end of this line in the log file.

no_stderr => 0 or 1

Overrides default setting for this invocation - see above.

FILE FORMATS

Note that these are the common field usages - you don't have to put the same things in the same fields, though it would probably make life easier if you were planning to process these log files through existing HTTP server log file analysis tools.

The error log file is structured as follows :-

the date

This is prettyprinted in GMT (UTC) using the gmtime function and enclosed in square brackets. It's always generated for you.

the class of message

This will be followed by a colon character ':'. Taken from the class parameter. This overrides any default value set for the object as a whole.

any supplementary information

Taken from the info parameter. This will be enclosed in round brackets.

The access log file is structured as follows :-

client host name/IP address

Taken from the host parameter.

remote user name

Taken from the ident parameter. This is normally found via the AUTH/IDENT protocol - RFC 1413, RFC 931.

remote user name

Taken from the user parameter. This is normally from HTTP authentication.

timestamp

Generated using localtime, with a GMT (UTC) offset. This will be enclosed in square brackets, and will always be generated automatically for you.

the message itself

Taken from the message parameter.

response status code

Taken from the code parameter. This is normally numeric.

bytes transferred count

Taken from the count parameter. This is normally numeric.

BUGS

None ? :-)

TODO

Extended log file format (dump variable X as field Y in the log file entry?) might be useful.

COPYRIGHT

Copyright (c) 1998 Martin Hamilton <martinh@gnu.org> and Jon Knight <jon@net.lut.ac.uk>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

It was developed by the Department of Computer Studies at Loughborough University of Technology, as part of the ROADS project. This work was funded by the Joint Information Systems Committee (JISC) of the Higher Education Funding Councils under the UK Electronic Libraries Programme (eLib), the European Commission DESIRE project, and the TERENA development programme.

AUTHORS

  Jon Knight <jon@net.lut.ac.uk>
  Martin Hamilton <martinh@gnu.org>