.. _aiohttp-logging:

Logging
=======

.. currentmodule:: aiohttp


*aiohttp* uses standard :mod:`logging` for tracking the
library activity.

We have the following loggers enumerated by names:

- ``'aiohttp.access'``
- ``'aiohttp.client'``
- ``'aiohttp.internal'``
- ``'aiohttp.server'``
- ``'aiohttp.web'``
- ``'aiohttp.websocket'``

You may subscribe to these loggers for getting logging messages.  The
page does not provide instructions for logging subscribing while the
most friendly method is :func:`logging.config.dictConfig` for
configuring whole loggers in your application.



Access logs
-----------

Access log by default is switched on and uses ``'aiohttp.access'``
logger name.

The log may be controlled by :meth:`aiohttp.web.AppRunner` and 
:func:`aiohttp.web.run_app`.


Pass *access_log* parameter with value of :class:`logging.Logger`
instance to override default logger.

.. note::

   Use ``web.run_app(app, access_log=None)`` for disabling access logs.


Other parameter called *access_log_format* may be used for specifying log
format (see below).


.. _aiohttp-logging-access-log-format-spec:

Format specification
^^^^^^^^^^^^^^^^^^^^

The library provides custom micro-language to specifying info about
request and response:

+--------------+---------------------------------------------------------+
| Option       | Meaning                                                 |
+==============+=========================================================+
| ``%%``       | The percent sign                                        |
+--------------+---------------------------------------------------------+
| ``%a``       | Remote IP-address                                       |
|              | (IP-address of proxy if using reverse proxy)            |
+--------------+---------------------------------------------------------+
| ``%t``       | Time when the request was started to process            |
+--------------+---------------------------------------------------------+
| ``%P``       | The process ID of the child that serviced the request   |
+--------------+---------------------------------------------------------+
| ``%r``       | First line of request                                   |
+--------------+---------------------------------------------------------+
| ``%s``       | Response status code                                    |
+--------------+---------------------------------------------------------+
| ``%b``       | Size of response in bytes, excluding HTTP headers       |
+--------------+---------------------------------------------------------+
| ``%T``       | The time taken to serve the request, in seconds         |
+--------------+---------------------------------------------------------+
| ``%Tf``      | The time taken to serve the request, in seconds         |
|              | with fraction in %.06f format                           |
+--------------+---------------------------------------------------------+
| ``%D``       | The time taken to serve the request, in microseconds    |
+--------------+---------------------------------------------------------+
| ``%{FOO}i``  | ``request.headers['FOO']``                              |
+--------------+---------------------------------------------------------+
| ``%{FOO}o``  | ``response.headers['FOO']``                             |
+--------------+---------------------------------------------------------+

Default access log format is::

   '%a %t "%r" %s %b "%{Referer}i" "%{User-Agent}i"'

.. versionadded:: 2.3.0

*access_log_class* introduced.

Example of drop-in replacement for :class:`aiohttp.helpers.AccessLogger`::

  from aiohttp.abc import AbstractAccessLogger

  class AccessLogger(AbstractAccessLogger):

      def log(self, request, response, time):
          self.logger.info(f'{request.remote} '
                           f'"{request.method} {request.path} '
                           f'done in {time}s: {response.status}')


.. _gunicorn-accesslog:

Gunicorn access logs
^^^^^^^^^^^^^^^^^^^^
When `Gunicorn <http://docs.gunicorn.org/en/latest/index.html>`_ is used for
:ref:`deployment <aiohttp-deployment-gunicorn>` its default access log format
will be automatically replaced with the default aiohttp's access log format.

If Gunicorn's option access_logformat_ is
specified explicitly it should use aiohttp's format specification.

Gunicorn access log works only if accesslog_ is specified explicitly in your
config or as a command line option.
This configuration can be either a path or ``'-'``. If the application uses
a custom logging setup intercepting the ``'gunicorn.access'`` logger,
accesslog_ should be set to ``'-'`` to prevent Gunicorn to create an empty
access log file upon every startup.




Error logs
----------

*aiohttp.web* uses logger named ``'aiohttp.server'`` to store errors
given on web requests handling.

The log is enabled by default.

To use different logger name please pass *logger* parameter
(:class:`logging.Logger` instance) to :meth:`aiohttp.web.AppRunner` constructor.


.. _access_logformat:
    http://docs.gunicorn.org/en/stable/settings.html#access-log-format

.. _accesslog:
    http://docs.gunicorn.org/en/stable/settings.html#accesslog