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¶
combinedThe 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"
commonThe 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
jsonA line of JSON, with the fields of a message of JSON of
Pyjo.Logand those of the request,client,method,path,protocol,status,bytes,referrer,user_agentanddurationin seconds, andhttpRequest, which Cloud Logging shows as a request, the default with thePYJO_LOG_FORMATenvironment variable set tojson.{"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,%hThe client, see
client.%bThe bytes of the body,
-for none.%BThe bytes of the body,
0for none.%{name}CA cookie of the request.
%DThe time of the response in microseconds.
%HThe protocol, as
HTTP/1.1.%{name}iA header of the request.
%l-, the remote logname of identd.%mThe method.
%{name}oA header of the response.
%pThe port of the server.
%PThe process.
%qThe query, with
?, or nothing.%rThe first line of the request.
%s,%>s,%<sThe status.
%tThe time of the request, as
[06/Nov/2026:09:42:28 +0000].%{format}tThe time of the request in the format of
time.strftime(), in the local time or in the time zone oftz, orsec,msec,usec,msec_fracandusec_fracof the epoch, and of the end of the response with the prefixend:.%TThe time of the response in seconds.
%{unit}TThe time of the response in
s,msorus.%uThe user of Basic authentication.
%UThe path, without the query.
%v,%VThe 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.AccessLoginherits all methods fromPyjoyment.Pluginand 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
Pyjoymentapplication.