blob: 799b75d6aec9ce24b7ab6299e942a48d09b14acb [file] [log] [blame]
.. _access-logging:
==============
Access Logging
==============
The WSGI design is modular. Waitress logs error conditions, debugging
output, etc., but not web traffic. For web traffic logging, Paste
provides `TransLogger
<https://web.archive.org/web/20160707041338/http://pythonpaste.org/modules/translogger.html>`_
:term:`middleware`. TransLogger produces logs in the `Apache Combined
Log Format <https://httpd.apache.org/docs/current/logs.html#combined>`_.
.. _logging-to-the-console-using-python:
Logging to the Console Using Python
-----------------------------------
``waitress.serve`` calls ``logging.basicConfig()`` to set up logging to the
console when the server starts up. Assuming no other logging configuration
has already been done, this sets the logging default level to
``logging.WARNING``. The Waitress logger will inherit the root logger's
level information (it logs at level ``WARNING`` or above).
Waitress sends its logging output (including application exception
renderings) to the Python logger object named ``waitress``. You can
influence the logger level and output stream using the normal Python
``logging`` module API. For example:
.. code-block:: python
import logging
logger = logging.getLogger('waitress')
logger.setLevel(logging.INFO)
Within a PasteDeploy configuration file, you can use the normal Python
``logging`` module ``.ini`` file format to change similar Waitress logging
options. For example:
.. code-block:: ini
[logger_waitress]
level = INFO
.. _logging-to-the-console-using-pastedeploy:
Logging to the Console Using PasteDeploy
----------------------------------------
TransLogger will automatically setup a logging handler to the console when called with no arguments.
It "just works" in environments that don't configure logging.
This is by virtue of its default configuration setting of ``setup_console_handler = True``.
.. TODO:
.. .. _logging-to-a-file-using-python:
.. Logging to a File Using Python
.. ------------------------------
.. Show how to configure the WSGI logger via python.
.. _logging-to-a-file-using-pastedeploy:
Logging to a File Using PasteDeploy
------------------------------------
TransLogger does not write to files, and the Python logging system
must be configured to do this. The Python class :class:`FileHandler`
logging handler can be used alongside TransLogger to create an
``access.log`` file similar to Apache's.
Like any standard :term:`middleware` with a Paste entry point,
TransLogger can be configured to wrap your application using ``.ini``
file syntax. First add a
``[filter:translogger]`` section, then use a ``[pipeline:main]``
section file to form a WSGI pipeline with both the translogger and
your application in it. For instance, if you have this:
.. code-block:: ini
[app:wsgiapp]
use = egg:mypackage#wsgiapp
[server:main]
use = egg:waitress#main
host = 127.0.0.1
port = 8080
Add this:
.. code-block:: ini
[filter:translogger]
use = egg:Paste#translogger
setup_console_handler = False
[pipeline:main]
pipeline = translogger
wsgiapp
Using PasteDeploy this way to form and serve a pipeline is equivalent to
wrapping your app in a TransLogger instance via the bottom of the ``main``
function of your project's ``__init__`` file:
.. code-block:: python
from mypackage import wsgiapp
from waitress import serve
from paste.translogger import TransLogger
serve(TransLogger(wsgiapp, setup_console_handler=False))
.. note::
TransLogger will automatically set up a logging handler to the console when
called with no arguments, so it "just works" in environments that don't
configure logging. Since our logging handlers are configured, we disable
the automation via ``setup_console_handler = False``.
With the filter in place, TransLogger's logger (named the ``wsgi`` logger) will
propagate its log messages to the parent logger (the root logger), sending
its output to the console when we request a page:
.. code-block:: text
00:50:53,694 INFO [wsgiapp] Returning: Hello World!
(content-type: text/plain)
00:50:53,695 INFO [wsgi] 192.168.1.111 - - [11/Aug/2011:20:09:33 -0700] "GET /hello
HTTP/1.1" 404 - "-"
"Mozilla/5.0 (Macintosh; U; Intel Mac OS X; en-US; rv:1.8.1.6) Gecko/20070725
Firefox/2.0.0.6"
To direct TransLogger to an ``access.log`` FileHandler, we need the
following to add a FileHandler (named ``accesslog``) to the list of
handlers, and ensure that the ``wsgi`` logger is configured and uses
this handler accordingly:
.. code-block:: ini
# Begin logging configuration
[loggers]
keys = root, wsgiapp, wsgi
[handlers]
keys = console, accesslog
[logger_wsgi]
level = INFO
handlers = accesslog
qualname = wsgi
propagate = 0
[handler_accesslog]
class = FileHandler
args = ('%(here)s/access.log','a')
level = INFO
formatter = generic
As mentioned above, non-root loggers by default propagate their log records
to the root logger's handlers (currently the console handler). Setting
``propagate`` to ``0`` (``False``) here disables this; so the ``wsgi`` logger
directs its records only to the ``accesslog`` handler.
Finally, there's no need to use the ``generic`` formatter with
TransLogger, as TransLogger itself provides all the information we
need. We'll use a formatter that passes-through the log messages as
is. Add a new formatter called ``accesslog`` by including the
following in your configuration file:
.. code-block:: ini
[formatters]
keys = generic, accesslog
[formatter_accesslog]
format = %(message)s
Finally alter the existing configuration to wire this new
``accesslog`` formatter into the FileHandler:
.. code-block:: ini
[handler_accesslog]
class = FileHandler
args = ('%(here)s/access.log','a')
level = INFO
formatter = accesslog