NAME

Catalyst::Plugin::AccessLog::Formatter - Log formatter for Catalyst::Plugin::AccessLog

VERSION

version 0.02

DESCRIPTION

The log format argument is a string which will be used to generate each line of the access log. The string consists of literal characters which will be copied to the log output verbatim, and escapes, which will be replaced with information about the request or the response. This format string is intended to be compatible with the Apache LogFormat directive, however it contains some extensions and leaves a few features unimplemented.

Escapes can be either short escapes or long escapes. Both types begin with the "%" character. Short escapes consist of a % followed by a single character, for example %h for the remote hostname. Long escapes consist of a % followed by a name inside square brackets, for example %[remote_hostname] for the same option. Apache-compatible options have both short escapes and long escapes, while incompatible options have only long escapes.

Some escapes (currently %[time], %[apache_time], %[header], and %[apache_header]) may also take an argument, which can be optional or required. The argument is placed inside curly braces between the percent sign and the name of the escape, for example %{User-agent}i or %{User-agent}[header] to get the value of the User-agent header.

A literal percent-sign can be produced in the output using the escape sequence %%.

Escapes

%[remote_address], %a

The IP address of the remote client.

%[clf_size], %b

The size of the response content in bytes. If the response content is empty, produces a dash - instead of 0. This is compatible with CLF.

%[size], %B

The size of the response content in bytes. Always numeric, even for 0.

%[remote_host], %h

The hostname of the remote client, if the hostname_lookups config option is true. Otherwise, the IP address of the remote client, as %[remote_address].

%[header], %i

The value of the request header named in the (mandatory) argument, or "-" if no such header was provided. Usage: %{User-agent}i to get the User-agent request header.

%l

For Apache compatibility, this option produces a single dash -. In Apache this option returns the remote username from an ident check, if the module is present, which it never is, which means it always produces a single dash on Apache as well. We don't bother implementing ident.

%[method], %m

The request method (e.g. GET, POST).

%[port], %p

The port number that the request was received on. In apache this is the server's "canonical port", however this is information that's not available to Catalyst.

%[request_line], %r

The first line of the HTTP request, e.g. "GET / HTTP/1.0".

%[status], %s

The HTTP status of the response, e.g. 200 or 404.

%[apache_time], %t

The time that the request was received.

While this escape and the %[time] escape both take an optional strftime argument, they differ in their default formats. This escape defaults to a "human readable" format which is lousy to parse, but is nonetheless compatible with apache.

%[time], %[datetime]

The time that the request was received.

While this escape and the %[apache_time] escape both take an optional strftime argument, they differ in their default formats. This escape defaults to the time_format config option provided to Catalyst::Plugin::AccessLog. If that option is not provided, the default is ISO 8601.

%[remote_user], %u

The REMOTE_USER variable as set by HTTP basic auth, or certain frontend authentication methods. Returns a dash - if no such thing exists.

%[host_port], %v, %V

The host and the port of the request URI. Apache specifies that these should be the server's "canonical" host and port, but this information is unavailable to Catalyst.

%[hostname]

The hostname of the request URI.

%[path], %U

The request path (relative to the application root, but with a leading slash).

%[handle_time], %T

The time spent handling this request, as provided by the $c->stats object. Returns a dash - if stats are unavailable.

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.