Apache...ompiler(3pm)

💖 NAME 💖

Apache::LogFormat::Compiler — Compile a log format string to perl-code.

okay bestie, quick header tea before we get into it: this page lives under User Contributed Perl Documentation, the header is Apache...ompiler(3pm), and the manual name is Apache::LogFormat::Compiler. It compiles a log format string into perl-code for faster generation of access_log lines. periodt.

---

✨ SYNOPSIS ✨

synopsis time — copy-paste ready, no cap:

use Apache::LogFormat::Compiler;

my $log_handler = Apache::LogFormat::Compiler->new("combined");
my $log = $log_handler->log_line(
    $env,
    $res,
    $length,
    $reqtime,
    $time
);

---

🦋 DESCRIPTION 🦋

Compile a log format string to perl-code. For faster generation of access_log lines.

the whole vibe is faster access_log line generation. obsessed.

---

🎀 METHOD 🎀

new($fmt:String)

Takes a format string — or a preset template "combined" or "custom" — to specify the log format. This module implements a subset of Apache's LogFormat templates (<http://httpd.apache.org/docs/2.0/mod/mod_log_config.html>):

%%    a percent sign
%h    REMOTE_ADDR from the PSGI environment, or -
%l    remote logname not implemented (currently always -)
%u    REMOTE_USER from the PSGI environment, or -
%t    [local timestamp, in default format]
%r    REQUEST_METHOD, REQUEST_URI and SERVER_PROTOCOL from the PSGI environment
%s    the HTTP status code of the response
%b    content length of the response
%T    custom field for handling times in subclasses
%D    custom field for handling sub-second times in subclasses
%v    SERVER_NAME from the PSGI environment, or -
%V    HTTP_HOST or SERVER_NAME from the PSGI environment, or -
%p    SERVER_PORT from the PSGI environment
%P    the worker's process id
%m    REQUEST_METHOD from the PSGI environment
%U    PATH_INFO from the PSGI environment
%q    QUERY_STRING from the PSGI environment
%H    SERVER_PROTOCOL from the PSGI environment

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

%{variable-name}i    HTTP_VARIABLE_NAME value from the PSGI environment
%{header-name}o      header-name header in the response
%{time-format]t      localtime in the specified strftime format

log_line($env:HashRef, $res:ArrayRef, $length:Integer, $reqtime:Integer, $time:Integer): $log:String

Generates log line. here's the arg tea:

• $env — PSGI env request HashRef
• $res — PSGI response ArrayRef
• $length — Content-Length
• $reqtime — The time taken to serve request in microseconds. optional
• $time — Time the request was received. optional. If $time is undefined. current timestamp is used.

Sample psgi

sample psgi — yes, it's a whole little app:

use Plack::Builder;
use Time::HiRes;
use Apache::LogFormat::Compiler;

my $log_handler = Apache::LogFormat::Compiler->new(
    '%h %l %u %t "%r" %>s %b "%{Referer}i" "%{User-agent}i" %D'
);
my $compile_log_app = builder {
    enable sub {
        my $app = shift;
        sub {
            my $env = shift;
            my $t0 = [gettimeofday];
            my $res = $app->();
            my $reqtime = int(Time::HiRes::tv_interval($t0) * 1_000_000);
            $env->{psgi.error}->print($log_handler->log_line(
                $env,$res,6,$reqtime, $t0->[0]));
        }
    };
    $app
};

---

🌈 ABOUT POSIX::strftime::Compiler 🌈

This module uses POSIX::strftime::Compiler for generating the datetime string. POSIX::strftime::Compiler provides GNU C library compatible strftime(3). But this module won't be affected by the system locale. this feature is useful when you want to write loggers, servers and portable applications.

---

💅 ADD CUSTOM FORMAT STRING 💅

Apache::LogFormat::Compiler allows one to add a custom format string

my $log_handler = Apache::LogFormat::Compiler->new(
    '%z %{HTTP_X_FORWARDED_FOR|REMOTE_ADDR}Z',
    char_handlers => +{
        'z' => sub {
            my ($env,$req) = @_;
            return $env->{HTTP_X_FORWARDED_FOR};
        }
    },
    block_handlers => +{
        'Z' => sub {
            my ($block,$env,$req) = @_;
            # block eq 'HTTP_X_FORWARDED_FOR|REMOTE_ADDR'
            my ($main, $alt) = split('\|', $args);
            return exists $env->{$main} ? $env->{$main} : $env->{$alt};
        }
    },
);

Any single letter can be used, other than those already defined by Apache::LogFormat::Compiler. Your sub is called with two or three arguments: the content inside the "{}" from the format (block_handlers only), the PSGI environment ($env), and the ArrayRef of the response. It should return the string to be logged. iykyk 💅

---

👑 AUTHOR 👑

Masahiro Nagano <kazeburo@gmail.com>

---

🔥 SEE ALSO 🔥

• Plack::Middleware::AccessLog
• <http://httpd.apache.org/docs/2.2/mod/mod_log_config.html>

---

🍓 LICENSE 🍓

Copyright (C) Masahiro Nagano

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

and that's the legal tea, bestie.

💖 okay that's the whole page — source/version is perl v5.42.0, dated 2019-11-19, and that's the cute footer sign-off. mwah 💖