NAME

Catalyst::Plugin::AccessLog

VERSION

version 0.02

SYNOPSIS

Requires Catalyst 5.8 or above.

# In lib/MyApp.pm context
use Catalyst qw(
    ConfigLoader
    -Stats=1
    AccessLog
    ... other plugins here ...
);

__PACKAGE__->config(
    'Plugin::AccessLog' => {
        format => '%[time] %[remote_address] %[path] %[status] %[size]',
        time_format => '%c',
        time_zone => 'America/Chicago',
    }
);

__PACKAGE__->setup();

DESCRIPTION

This plugin isn't for "debug" logging. Instead it enables you to create "access logs" from within a Catalyst application instead of requiring a webserver to do it for you. It will work even with Catalyst debug logging turned off (but see enable_stats below).

CONFIGURATION

All configuration is optional; by default the plugin will log to STDERR in a format compatible with the "Common Log Format" (http://en.wikipedia.org/wiki/Common_Log_Format).

target

Default: \*STDERR

Where to log to. If target is a filehandle or something that isa("IO::Handle"), lines of logging information will be printed to it. If target is an object with an info method it's assumed to be a logging object (e.g. Log::Dispatch or Log::Log4perl) and lines will be passed to the info method. If it's a CODE ref then it will be called with each line of logging output. If it's an unblessed scalar it will be interpreted as a filehandle and the plugin will try to open it for append and write lines to it.

format

Default: '%h %l %u %t "%r" %s %b "%{Referer}i" "%{User-Agent}i"' (Apache common log format).

The format string for each line of output. You can use Apache LogFormat strings, with a reasonably good level of compatibility, or you can use a slightly more readable format. The log format is documented in detail in Catalyst::Plugin::AccessLog::Formatter.

time_format

Default: '%Y-%m-%dT%H:%M:%S' (ISO 8601)

The default time format for the %t / %[time] escape. This is a strftime format string, which will be provided to DateTime's strftime method.

time_zone

Default: local

The timezone to use when printing times in access logs. This will be passed to DateTime::TimeZone's constructor. Olson timezone names, POSIX TZ values, and the keywords "local" and "UTC" are reasonable choices.

formatter_class

Default: Catalyst::Plugin::AccessLog::Formatter

In case you want to do something completely different you may provide your own formatter class that implements the format_line method and provide its name here.

hostname_lookups

Default: false

If this option is set to a true value, then the %h / %[remote_hostname] escape will resolve the client IP address using reverse DNS. This is generally not recommended for reasons of performance and security. Equivalent to the Apache option HostnameLookups.

enable_stats

Default: true

Catalyst::Plugin::AccessLog works without regard to Catalyst's debug logging option. However, the time-related escapes are only available if the Catalyst::Stats statistics collection is enabled, and by default stats are tied to the value of the debug flag. If this option is set, stats will be enabled for the application regardless of the -Stats or -Debug flags, or the MYAPP_STATS or MYAPP_DEBUG environment variables.

NOTES

Logging to $c->log

It is generally not recommended to write the access log to $c->log, especially if static file handling is enabled. However, there might be a good reason to do it somewhere. If the logging target is a coderef, it will receive $c as its second argument. You can log to $c->log with:

target => sub { pop->log->info(shift) }

Don't store $c anywhere that persists after the lifetime of the coderef or bad things will happen to you and everyone you know.

SOURCE, BUGS, ETC.

http://github.com/arodland/Catalyst-Plugin-AccessLog

AUTHORS

Andrew Rodland <andrew@hbslabs.com>
Murray <sysmon@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2009 by Andrew Rodland.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.