Pyjoyment.Plugin.AccessLog - Access log plugin

# Pyjoyment
app.plugin('AccessLog')

# Pyjoyment.Lite
plugin('AccessLog')

# Lines of JSON, with the client of a header of the gateway, and the errors only
app.plugin('AccessLog', format='json', client='X-Envoy-External-Address', status=400)

# A file, in a format of LogFormat of Apache, with the time of the response in milliseconds
app.plugin('AccessLog', log='/var/log/myapp/access.log', format='%h %t "%r" %>s %b %{ms}T')

# A file of each day in UTC
app.plugin('AccessLog', log='/var/log/myapp/access-%Y-%m-%d.log', tz='UTC')

Pyjoyment.Plugin.AccessLog writes the access log of the application, as a server of production writes it: one line for each response, with the client, the request, the status, the size, the referrer and the user agent, to the standard output by default, as a container has it.

203.0.113.7 - - [06/Nov/2026:09:42:28 +0000] "GET / HTTP/1.1" 200 39676 "-" "Mozilla/5.0 ..."

It sees every response of the application, also of the static files, of the mounted applications and of the requests that no route takes, as it follows the transaction from the hook after_build_tx, before the request is parsed. The line is written once the response has been written, so that it has the bytes of the body that the server has written, also of a chunked response, which has no Content-Length, and of one whose client closed the connection before its end. A request whose client closed the connection before the application responded is logged with the status 499, as nginx logs it, and a WebSocket with the status 101 of its handshake, once the connection is upgraded. The time of %t is the one of the request, in the local time or in the time zone of tz, with its offset, as of Apache, and the one of a line of JSON the one of the message of the log, after the response.

A line is written with one write of its own and flushed, so that the lines of the workers of Pyjo.Server.Prefork and Pyjo.Server.Prethread on one standard output do not mix, as a write of less than PIPE_BUF, 4096 bytes on Linux, to a pipe is atomic, and a file is locked for it.

The endpoints of Pyjoyment.Plugin.Health, whose probes would fill the log, are left out by default.

See Pyjoyment.Plugins for a list of plugins that are available by default.

Formats

combined

The combined log format of Apache and nginx, which log analyzers read, the default, %h %l %u %t "%r" %>s %b "%{Referer}i" "%{User-Agent}i".

203.0.113.7 - - [06/Nov/2026:09:42:28 +0000] "GET /?q=1 HTTP/1.1" 200 39676 "https://example.com/" "curl/8.7.1"
common

The common log format, without the referrer and the user agent, %h %l %u %t "%r" %>s %b.

203.0.113.7 - - [06/Nov/2026:09:42:28 +0000] "GET /?q=1 HTTP/1.1" 200 39676
json

A line of JSON, with the fields of a message of JSON of Pyjo.Log and those of the request, client, method, path, protocol, status, bytes, referrer, user_agent and duration in seconds, and httpRequest, which Cloud Logging shows as a request, the default with the PYJO_LOG_FORMAT environment variable set to json.

{"time":"2026-11-06T09:42:28.048120Z","level":"info","severity":"INFO","message":"GET /?q=1 200","pid":7,...}

Another format is a string of the directives of LogFormat of Apache, as Plack::Middleware::AccessLog takes it, and the text between them, which is written as it is.

app.plugin('AccessLog', format='%h %t "%r" %>s %b %D "%{X-Request-ID}i"')
%%

A percent sign.

%a, %h

The client, see client.

%b

The bytes of the body, - for none.

%B

The bytes of the body, 0 for none.

%{name}C

A cookie of the request.

%D

The time of the response in microseconds.

%H

The protocol, as HTTP/1.1.

%{name}i

A header of the request.

%l

-, the remote logname of identd.

%m

The method.

%{name}o

A header of the response.

%p

The port of the server.

%P

The process.

%q

The query, with ?, or nothing.

%r

The first line of the request.

%s, %>s, %<s

The status.

%t

The time of the request, as [06/Nov/2026:09:42:28 +0000].

%{format}t

The time of the request in the format of time.strftime(), in the local time or in the time zone of tz, or sec, msec, usec, msec_frac and usec_frac of the epoch, and of the end of the response with the prefix end:.

%T

The time of the response in seconds.

%{unit}T

The time of the response in s, ms or us.

%u

The user of Basic authentication.

%U

The path, without the query.

%v, %V

The host of the request.

A directive that is not one of them, as one with the statuses of Apache, %400,501{User-Agent}i, raises an exception when the plugin is registered. The size is the one of the body that the server has written, with the framing of a chunked response, as nginx has it. A value that is missing is -, as of Apache, and null in JSON. A quote, a backslash and a character that is not printable ASCII, as of a header that a client made up to forge a line, are escaped as \xhh of its bytes, as nginx escapes them.

A dict of fields is a line of JSON of fields of its own, in the place of the ones of the request of json, after the fields of a message of JSON of Pyjo.Log, which a field of the same name does not replace. A field is a format of LogFormat, whose directive alone is a value of its type, as a number of %>s or null of a header that is missing, and a text with directives a string, with - for a value that is missing, or a dict of fields, a function of the transaction and of the dict of the values of the request, or a constant.

app.plugin('AccessLog', format={
    'client': '%h',
    'request': '%m %U%q',
    'status': '%>s',
    'bytes': '%B',
    'ms': '%{ms}T',
    'request_id': '%{X-Request-ID}i',
    'http': {'user_agent': '%{User-Agent}i', 'referrer': '%{Referer}i'},
    'service': 'myapp',
})

{"time":"...","level":"info","severity":"INFO","message":"GET /?q=1 200","pid":7,"client":"203.0.113.7",
 "request":"GET /?q=1","status":200,"bytes":6,"ms":3,"request_id":null,"http":{"user_agent":"curl/8.7.1",
 "referrer":null},"service":"myapp"}

Options

Pyjoyment.Plugin.AccessLog supports the following options.

client

app.plugin('AccessLog', client='X-Real-IP')
app.plugin('AccessLog', client=lambda tx: tx.req.headers.header('Fly-Client-IP'))

The address of the client, defaults to
:attr:`Pyjo.Transaction.Pyjo_Transaction.remote_address`, which takes
``X-Forwarded-For`` of the trusted proxies with
:attr:`Pyjo.Server.Pyjo_Server.reverse_proxy`, as the option ``-p`` of
the servers sets it, the name of a header that a gateway sets, as
``X-Envoy-External-Address`` of Istio, whose request without it, as a
probe of the address of a pod, has the remote address, or a function of
the transaction.

exclude

app.plugin('AccessLog', exclude=['/livez', '/readyz', re.compile(r'^/assets/')])
app.plugin('AccessLog', exclude=lambda tx: tx.req.headers.user_agent == 'kube-probe')

The paths whose requests are not logged, a path with the paths under it,
a regular expression of the path, or a function of the transaction,
defaults to the endpoints of :mod:`Pyjoyment.Plugin.Health`, whose paths
it takes from the helper ``health.path``. An empty list logs every
request.

format

app.plugin('AccessLog', format='json')
app.plugin('AccessLog', format='%h %t "%r" %>s %b %{ms}T')
app.plugin('AccessLog', format={'client': '%h', 'status': '%>s', 'request_id': '%{X-Request-ID}i'})
app.plugin('AccessLog', format=lambda tx, entry: f'{entry["method"]} {entry["path"]} {entry["status"]}')

The format of the lines, ``combined``, ``common``, ``json``, one of
``LogFormat`` or a dict of the fields of JSON, see `Formats`_, or a
function of the transaction and of a dict with the values of the
request, ``client``, ``time``, ``method``, ``path``, ``protocol``,
``status``, ``bytes``, ``referrer``, ``user_agent`` and ``duration``,
which returns the line, defaults to ``json`` with
:attr:`Pyjo.Log.Pyjo_Log.json` of the log and to ``combined``
otherwise.

level

app.plugin('AccessLog', log=app.log, level='debug')

The level of the lines in a :mod:`Pyjo.Log` of ``log``, defaults to
``info``.

log

app.plugin('AccessLog', log='/var/log/myapp/access.log')
app.plugin('AccessLog', log='/var/log/myapp/access-%Y-%m-%d.log')
app.plugin('AccessLog', log=app.log)

Where the lines go, the standard output by default, the path of a file,
or the pattern of its name, whose file of each period
:attr:`Pyjo.Log.Pyjo_Log.path` takes, or a :mod:`Pyjo.Log`, as the log
of the application, whose format a line gets, as a message of the level
of ``level``.

status

app.plugin('AccessLog', status=400)
app.plugin('AccessLog', status=[404, 499])

The lowest status that is logged, or the statuses, defaults to all.

tz

app.plugin('AccessLog', tz='UTC')
app.plugin('AccessLog', tz='Europe/Warsaw')

The time zone of ``%t`` and ``%{format}t``, and of the time of a line of
JSON and the name of the file of a pattern of ``log``, as of
:attr:`Pyjo.Log.Pyjo_Log.tz`, defaults to the one of the
:mod:`Pyjo.Log` of ``log``, and to the local time.

See also

Pyjoyment, https://mojolicious.org.

It has no counterpart in Mojolicious.

Classes

class Pyjoyment.Plugin.AccessLog.Pyjoyment_Plugin_AccessLog[source]

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

register(app: Pyjoyment_App, conf: dict[str, Any] | None = None) → None[source]
plugin.register(Pyjoyment.new())
plugin.register(Pyjoyment.new(), {'format': 'json'})

Register the hook in Pyjoyment application.