From dd3b0c2ccfefd10fab081019c8373bffeace8f0a Mon Sep 17 00:00:00 2001 From: Ben Darnell Date: Sun, 9 Sep 2012 18:43:52 -0700 Subject: [PATCH] Document the logging changes --- tornado/log.py | 43 +++++++++++++++++++++++--------- tornado/testing.py | 21 +++++++++++++++- website/sphinx/log.rst | 5 ++++ website/sphinx/releases/next.rst | 11 ++++++++ website/sphinx/testing.rst | 3 +++ website/sphinx/utilities.rst | 2 +- 6 files changed, 71 insertions(+), 14 deletions(-) create mode 100644 website/sphinx/log.rst diff --git a/tornado/log.py b/tornado/log.py index c76d404db..988af3ac4 100644 --- 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 06d23037b..966c86064 100644 --- 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 index 000000000..719282c0b --- /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 9d2f99a9d..e851a47ea 100644 --- 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 38738085b..faf4ac7ad 100644 --- 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 775e46c29..077cfda3a 100644 --- a/website/sphinx/utilities.rst +++ b/website/sphinx/utilities.rst @@ -6,8 +6,8 @@ Utilities autoreload gen httputil + log options process stack_context testing - -- 2.47.2