Document the logging changes

diff --git a/tornado/log.py b/tornado/log.py
index c76d404db844b04ed3c18e4f691a3c835c9046e8..988af3ac4ed621db137e5002aa8d9fafe59d3c66 100644 (file)
--- a/tornado/log.py
+++ b/tornado/log.py
@@ -13,6 +13,21 @@
 # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 # License for the specific language governing permissions and limitations
 # under the License.
+"""Logging support for Tornado.
+
+Tornado uses three logger streams:
+
+* ``tornado.access``: Per-request logging for Tornado's HTTP servers (and
+  potentially other servers in the future)
+* ``tornado.application``: Logging of errors from application code (i.e.
+  uncaught exceptions from callbacks)
+* ``tornado.general``: General-purpose logging, including any errors
+  or warnings from Tornado itself.
+
+These streams may be configured independently using the standard library's
+`logging` module.  For example, you may wish to send ``tornado.access`` logs
+to a separate file for analysis.
+"""
 from __future__ import absolute_import, division, with_statement
 
 import logging
@@ -26,15 +41,9 @@ try:
 except ImportError:
     curses = None
 
-# Per-request logging for Tornado's HTTP servers (and potentially other servers
-# in the future)
+# Logger objects for internal tornado use
 access_log = logging.getLogger("tornado.access")
-
-# Logging of errors from application code (i.e. uncaught exceptions from
-# callbacks
 app_log = logging.getLogger("tornado.application")
-
-# General logging, i.e. everything else
 gen_log = logging.getLogger("tornado.general")
 
 def _stderr_supports_color():
@@ -50,12 +59,22 @@ def _stderr_supports_color():
 
 
 class LogFormatter(logging.Formatter):
-    def __init__(self, color=None, *args, **kwargs):
+    """Log formatter used in Tornado.
+
+    Key features of this formatter are:
+
+    * Color support when logging to a terminal that supports it.
+    * Timestamps on every log line.
+    * Robust against str/bytes encoding problems.
+
+    This formatter is enabled automatically by
+    `tornado.options.parse_command_line` (unless ``--logging=none`` is
+    used).
+    """
+    def __init__(self, color=True, *args, **kwargs):
         logging.Formatter.__init__(self, *args, **kwargs)
-        if color is None:
-            color = _stderr_supports_color()
-        self._color = color
-        if color:
+        self._color = color and _stderr_supports_color()
+        if self._color:
             # The curses module has some str/bytes confusion in
             # python3.  Until version 3.2.3, most methods return
             # bytes, but only accept strings.  In addition, we want to

diff --git a/tornado/testing.py b/tornado/testing.py
index 06d23037bce3c462e28d3f02dc1bafe69403ea46..966c860642a1e70ba4775b28cc2ad8d1579de81e 100644 (file)
--- a/tornado/testing.py
+++ b/tornado/testing.py
@@ -377,10 +377,29 @@ class LogTrapTestCase(unittest.TestCase):
 
 
 class ExpectLog(logging.Filter):
+    """Context manager to capture and suppress expected log output.
+
+    Useful to make tests of error conditions less noisy, while still
+    leaving unexpected log entries visible.  *Not thread safe.*
+
+    Usage::
+
+        with ExpectLog('tornado.application', "Uncaught exception"):
+            error_response = self.fetch("/some_page")
+    """
     def __init__(self, logger, regex, required=True):
+        """Constructs an ExpectLog context manager.
+
+        :param logger: Logger object (or name of logger) to watch.  Pass
+            an empty string to watch the root logger.
+        :param regex: Regular expression to match.  Any log entries on
+            the specified logger that match this regex will be suppressed.
+        :param required: If true, an exeption will be raised if the end of
+            the ``with`` statement is reached without matching any log entries.
+        """
         if isinstance(logger, basestring):
             logger = logging.getLogger(logger)
-        self.logger = logger  # may be either a Logger or a Handler
+        self.logger = logger
         self.regex = re.compile(regex)
         self.required = required
         self.matched = False

diff --git a/website/sphinx/log.rst b/website/sphinx/log.rst
new file mode 100644 (file)
index 0000000..719282c
--- /dev/null
+++ b/website/sphinx/log.rst
@@ -0,0 +1,5 @@
+``tornado.log`` --- Logging support
+===================================
+
+.. automodule:: tornado.log
+   :members:

diff --git a/website/sphinx/releases/next.rst b/website/sphinx/releases/next.rst
index 9d2f99a9d1a545cacd68ff719fe62323dd8b89f8..e851a47ea91f2769f7a4101cf39d06ca4c36b427 100644 (file)
--- a/website/sphinx/releases/next.rst
+++ b/website/sphinx/releases/next.rst
@@ -13,3 +13,14 @@ In progress
   cause it to bind to both ipv4 and ipv6 more often than before.
 * `tornado.netutil.bind_sockets` has a new ``flags`` argument that can
   be used to pass additional flags to ``getaddrinfo``.
+* Tornado no longer logs to the root logger.  Details on the new logging
+  scheme can be found under the `tornado.log` module.  Note that in some
+  cases this will require that you add an explicit logging configuration
+  in ordre to see any output (perhaps just calling ``logging.basicConfig()``),
+  although both `IOLoop.start()` and `tornado.options.parse_command_line`
+  will do this for you.
+* Errors while rendering templates no longer log the generated code,
+  since the enhanced stack traces (from version 2.1) should make this
+  unnecessary.
+* `tornado.testing.ExpectLog` can be used as a finer-grained alternative
+  to `tornado.testing.LogTrapTestCase`

diff --git a/website/sphinx/testing.rst b/website/sphinx/testing.rst
index 38738085b2384caca9ef4f53d8f62bdbb655e70d..faf4ac7ad6eacf7a4beebaf7df22ec91ec11e844 100644 (file)
--- a/website/sphinx/testing.rst
+++ b/website/sphinx/testing.rst
@@ -18,6 +18,9 @@
    Controlling log output
    ----------------------
 
+   .. autoclass:: ExpectLog
+      :members:
+
    .. autoclass:: LogTrapTestCase
       :members:
 

diff --git a/website/sphinx/utilities.rst b/website/sphinx/utilities.rst
index 775e46c2937c9d7b8d6a364eaa596a31f83ccb32..077cfda3aca975e5bcf3bc30df18f0ea39f80750 100644 (file)
--- a/website/sphinx/utilities.rst
+++ b/website/sphinx/utilities.rst
@@ -6,8 +6,8 @@ Utilities
    autoreload
    gen
    httputil
+   log
    options
    process
    stack_context
    testing
-