Merge pull request #205 from kpinc/doc_translogger

Import and change appropriately the pyramid docs regards paste.transl…

2 files changed, 153 insertions, 0 deletions

diff --git a/docs/glossary.rst b/docs/glossary.rst
index 92aaf31..9729a74 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -13,3 +13,17 @@ Glossary
    asyncore
       A standard library module for asynchronous communications.  See
       http://docs.python.org/library/asyncore.html .
+
+   middleware
+     *Middleware* is a :term:`WSGI` concept.  It is a WSGI component
+     that acts both as a server and an application.  Interesting uses
+     for middleware exist, such as caching, content-transport
+     encoding, and other functions.  See `WSGI.org <http://www.wsgi.org>`_
+     or `PyPI <http://python.org/pypi>`_ to find middleware for your
+     application.
+
+   WSGI
+     `Web Server Gateway Interface <http://www.wsgi.org/>`_.  This is a
+     Python standard for connecting web applications to web servers,
+     similar to the concept of Java Servlets.  Waitress requires
+     that your application be served as a WSGI application.
diff --git a/docs/index.rst b/docs/index.rst
index 9e89395..2a2260b 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -102,6 +102,7 @@ can be used in development and in situations where the likes of
 
 For more information on this, see :ref:`runner`.
 
+
 .. _logging:
 
 Logging
@@ -133,6 +134,144 @@ options.  For example:
    [logger_waitress]
    level = INFO
 
+
+Web Traffic Logging With Paste's TransLogging Middleware
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The WSGI design is modular.  Waitress logs error conditions, debugging
+output, etc., but not web traffic.  For web traffic logging Paste
+provides the `TransLogger
+<http://pythonpaste.org/modules/translogger.html>`_
+:term:`middleware`.  TransLogger produces logs in the `Apache Combined
+Log Format <http://httpd.apache.org/docs/2.2/logs.html#combined>`_.
+But TransLogger does not write to files, the Python logging system
+must be configured to do this.  The Python `FileHandler
+<https://docs.python.org/3/library/logging.handlers.html#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 setup 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 
+
+
+
 Using Behind a Reverse Proxy
 ----------------------------