/ 
Mojolicious-Plugin-AccessLog-0.010
River stage zero No dependents
/ Mojolicious::Plugin::AccessLog

NAME

Mojolicious::Plugin::AccessLog - An AccessLog Plugin for Mojolicious

VERSION

Version 0.010

SYNOPSIS

# Mojolicious
$self->plugin(AccessLog => log => '/var/log/mojo/access.log');

# Mojolicious::Lite
plugin AccessLog => {log => '/var/log/mojo/access.log'};

DESCRIPTION

Mojolicious::Plugin::AccessLog is a plugin to easily generate an access log.

OPTIONS

Mojolicious::Plugin::AccessLog supports the following options.

log

Log data destination.

Default: $app->log->handle, so that access log lines go to the same destination as lines created with $app->log->$method(...).

This option may be set to one of the following values:

Absolute path

plugin AccessLog => {log => '/var/log/mojo/access.log'};

A string specifying an absolute path to the log file. If the file does not exist already, it will be created, otherwise log output will be appended to the file. The log directory must exist in every case though.

Relative path

# Mojolicious::Lite
plugin AccessLog => {log => 'log/access.log'};

Similar to absolute path, but relative to the application home directory.

File Handle

open $fh, '>', '/var/log/mojo/access.log';
plugin AccessLog => {log => $fh};

plugin AccessLog => {log => \*STDERR};

A file handle to which log lines are printed.

Object

$log = IO::File->new('/var/log/mojo/access.log', O_WRONLY|O_APPEND);
plugin AccessLog => {log => $log};

$log = Log::Dispatch->new(...);
plugin AccessLog => {log => $log};

An object, that implements either a print method (like IO::Handle based classes) or an info method (i.e. Log::Dispatch or Log::Log4perl).

Callback routine

$log = Log::Dispatch->new(...);
plugin AccessLog => {
  log => sub { $log->log(level => 'debug', message => @_) }
};

A code reference. The provided subroutine will be called for every log line, that it gets as a single argument.

format

A string to specify the format of each line of log output.

Default: "common" (see below).

This plugin implements a subset of Apache's LogFormat.

%%

A percent sign.

%a

Remote IP-address.

%A

Local IP-address.

%b

Size of response in bytes, excluding HTTP headers. In CLF format, i.e. a '-' rather than a 0 when no bytes are sent.

%B

Size of response in bytes, excluding HTTP headers.

%D

The time taken to serve the request, in microseconds.

%h

Remote host. See "hostname_lookups" below.

%H

The request protocol.

%I

Bytes received, including request and headers. Cannot be zero.

%l

The remote logname, not implemented: currently always '-'.

%m

The request method.

%O

Bytes sent, including headers. Cannot be zero.

%p

The port of the server serving the request.

%P

The process ID of the child that serviced the request.

%r

First line of request: Request method, request URL and request protocol. Synthesized from other fields, so it may not be the request verbatim.

%s

The HTTP status code of the response.

%t

Time the request was received (standard english format).

%T

The time taken to serve the request, in seconds.

%u

Remote user, or '-'.

The remote user is first looked up in $c->req->env->{REMOTE_USER} and only if that does not exist then in the first part of $c->req->url->base->userinfo. This means the latter lookup can be disabled by setting $c->req->env->{REMOTE_USER} = undef.

%U

The URL path requested, not including any query string.

%v

The name of the server serving the request.

%V

The name of the server serving the request.

In addition, custom values can be referenced, using %{name}, with one of the mandatory modifier flags i, o, t, C or e:

%{RequestHeaderName}i

The contents of request header RequestHeaderName.

%{ResponseHeaderName}o

The contents of response header ResponseHeaderName.

%{Format}t

The time, in the form given by Format, which should be in extended strftime(3) format (potentially localized). In addition to the formats supported by strftime(3), the following format tokens are supported:

sec:

Number of seconds since the Epoch.

msec:

Number of milliseconds since the Epoch.

usec:

Number of microseconds since the Epoch.

msec_frac:

Millisecond fraction.

usec_frac:

Microsecond fraction.

These tokens can not be combined with each other or strftime(3) formatting in the same format string. You can use multiple %{format}t tokens instead:

"%{%d/%b/%Y %T}t.%{msec_frac}t %{%z}t"
%{CookieName}C

The contents of cookie CookieName in the request sent to the server.

%{VariableName}e

Content of the request environment hash variable VariableName:

$c->req->env->{VariableName}

The request environment hash is set by a CGI or PSGI server.

Non-printable bytes are replaced by an escape sequence of \x.. with .. being the hexadecimal code of the replaced byte.

For mostly historical reasons template names "common", "combined" and "combinedio" can also be used:

common
%h %l %u %t "%r" %>s %b
combined
%h %l %u %t "%r" %>s %b "%{Referer}i" "%{User-Agent}i"
combinedio
%h %l %u %t "%r" %>s %b "%{Referer}i" "%{User-Agent}i" %I %O

These format template names have two drawbacks though:

  1. The username (%u) is not quoted, but a username is allowed to contain spaces. As a consequence, log file parsers might lose track of the right fields. To get around this, spaces in usernames are replaced by \x20 if one of the format template names is used.

  2. The remote logname %l as provided by an ident service is not useful these days and therefore not supported, %l is always substituted by a hyphen ("-").

hostname_lookups

Enable reverse DNS hostname lookup if true. Keep in mind, that this adds latency to every request, if %h is part of the log line, because it requires a DNS lookup to complete before the request is finished. Default is false (= disabled).

METHODS

Mojolicious::Plugin::AccessLog inherits all methods from Mojolicious::Plugin and implements the following new ones.

register

$plugin->register(
  Mojolicious->new, {
    log => '/var/log/mojo/access.log',
    format => 'combined',
  }
);

Register plugin hooks in Mojolicious application.

SEE ALSO

Mojolicious, Plack::Middleware::AccessLog, Catalyst::Plugin::AccessLog, http://httpd.apache.org/docs/current/mod/mod_log_config.html.

ACKNOWLEDGEMENTS

Many thanks to Tatsuhiko Miyagawa for Plack::Middleware::AccessLog and Andrew Rodland for Catalyst::Plugin::AccessLog. Mojolicious:Plugin::AccessLog borrows a lot of code and ideas from those modules.

AUTHOR

Bernhard Graf

COPYRIGHT AND LICENSE

Copyright (C) 2012 - 2015 Bernhard Graf

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

See http://dev.perl.org/licenses/ for more information.