Move Logging into a separate page

2 files changed, 197 insertions, 2 deletions

diff --git a/docs/index.rst b/docs/index.rst
index 0416370..eb59c82 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,5 +1,8 @@
+.. _index:
+
+========
 Waitress
---------
+========
 
 Waitress is meant to be a production-quality pure-Python WSGI server with
 very acceptable performance.  It has no dependencies except ones which live
@@ -178,6 +181,7 @@ Extended Documentation
    :maxdepth: 1
 
    usage
+   logging
    design
    differences
    api
@@ -195,7 +199,7 @@ Change History
 Known Issues
 ------------
 
-- Does not support SSL natively.
+- Does not support TLS natively.
 
 Support and Development
 -----------------------
diff --git a/docs/logging.rst b/docs/logging.rst
new file mode 100644
index 0000000..bfcd032
--- /dev/null
+++ b/docs/logging.rst
@@ -0,0 +1,191 @@
+.. _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``.
+
+
+.. _logging-to-a-file-using-python:
+
+Logging to a File Using Python
+------------------------------
+
+.. warning:: This section needs help.
+
+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