Skip to content
Browse files

Document the logging changes

  • Loading branch information...
1 parent a1f6bee commit dd3b0c2ccfefd10fab081019c8373bffeace8f0a @bdarnell bdarnell committed
Showing with 71 additions and 14 deletions.
  1. +31 −12 tornado/log.py
  2. +20 −1 tornado/testing.py
  3. +5 −0 website/sphinx/log.rst
  4. +11 −0 website/sphinx/releases/next.rst
  5. +3 −0 website/sphinx/testing.rst
  6. +1 −1 website/sphinx/utilities.rst
View
43 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 @@
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
View
21 tornado/testing.py
@@ -377,10 +377,29 @@ def run(self, result=None):
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
View
5 website/sphinx/log.rst
@@ -0,0 +1,5 @@
+``tornado.log`` --- Logging support
+===================================
+
+.. automodule:: tornado.log
+ :members:
View
11 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`
View
3 website/sphinx/testing.rst
@@ -18,6 +18,9 @@
Controlling log output
----------------------
+ .. autoclass:: ExpectLog
+ :members:
+
.. autoclass:: LogTrapTestCase
:members:
View
2 website/sphinx/utilities.rst
@@ -6,8 +6,8 @@ Utilities
autoreload
gen
httputil
+ log
options
process
stack_context
testing
-

0 comments on commit dd3b0c2

Please sign in to comment.
Something went wrong with that request. Please try again.