logging-cookbook.po

# Copyright (C) 2001 Python Software Foundation
# This file is distributed under the same license as the Python package.
#
# Translators:
msgid ""
msgstr ""
"Project-Id-Version: Python 3.14\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2026-03-22 00:20+0000\n"
"PO-Revision-Date: 2018-05-23 14:36+0000\n"
"Last-Translator: Adrian Liaw <adrianliaw2000@gmail.com>\n"
"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-"
"tw)\n"
"Language: zh_TW\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=1; plural=0;\n"

#: ../../howto/logging-cookbook.rst:5
msgid "Logging Cookbook"
msgstr ""

#: ../../howto/logging-cookbook.rst:0
msgid "Author"
msgstr "作者"

#: ../../howto/logging-cookbook.rst:7
msgid "Vinay Sajip <vinay_sajip at red-dove dot com>"
msgstr "Vinay Sajip <vinay_sajip at red-dove dot com>"

#: ../../howto/logging-cookbook.rst:9
msgid ""
"This page contains a number of recipes related to logging, which have been "
"found useful in the past. For links to tutorial and reference information, "
"please see :ref:`cookbook-ref-links`."
msgstr ""

#: ../../howto/logging-cookbook.rst:16
msgid "Using logging in multiple modules"
msgstr ""

#: ../../howto/logging-cookbook.rst:18
msgid ""
"Multiple calls to ``logging.getLogger('someLogger')`` return a reference to "
"the same logger object.  This is true not only within the same module, but "
"also across modules as long as it is in the same Python interpreter "
"process.  It is true for references to the same object; additionally, "
"application code can define and configure a parent logger in one module and "
"create (but not configure) a child logger in a separate module, and all "
"logger calls to the child will pass up to the parent.  Here is a main "
"module::"
msgstr ""

#: ../../howto/logging-cookbook.rst:26
msgid ""
"import logging\n"
"import auxiliary_module\n"
"\n"
"# create logger with 'spam_application'\n"
"logger = logging.getLogger('spam_application')\n"
"logger.setLevel(logging.DEBUG)\n"
"# create file handler which logs even debug messages\n"
"fh = logging.FileHandler('spam.log')\n"
"fh.setLevel(logging.DEBUG)\n"
"# create console handler with a higher log level\n"
"ch = logging.StreamHandler()\n"
"ch.setLevel(logging.ERROR)\n"
"# create formatter and add it to the handlers\n"
"formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - "
"%(message)s')\n"
"fh.setFormatter(formatter)\n"
"ch.setFormatter(formatter)\n"
"# add the handlers to the logger\n"
"logger.addHandler(fh)\n"
"logger.addHandler(ch)\n"
"\n"
"logger.info('creating an instance of auxiliary_module.Auxiliary')\n"
"a = auxiliary_module.Auxiliary()\n"
"logger.info('created an instance of auxiliary_module.Auxiliary')\n"
"logger.info('calling auxiliary_module.Auxiliary.do_something')\n"
"a.do_something()\n"
"logger.info('finished auxiliary_module.Auxiliary.do_something')\n"
"logger.info('calling auxiliary_module.some_function()')\n"
"auxiliary_module.some_function()\n"
"logger.info('done with auxiliary_module.some_function()')"
msgstr ""

#: ../../howto/logging-cookbook.rst:56
msgid "Here is the auxiliary module::"
msgstr ""

#: ../../howto/logging-cookbook.rst:58
msgid ""
"import logging\n"
"\n"
"# create logger\n"
"module_logger = logging.getLogger('spam_application.auxiliary')\n"
"\n"
"class Auxiliary:\n"
"    def __init__(self):\n"
"        self.logger = logging.getLogger('spam_application.auxiliary."
"Auxiliary')\n"
"        self.logger.info('creating an instance of Auxiliary')\n"
"\n"
"    def do_something(self):\n"
"        self.logger.info('doing something')\n"
"        a = 1 + 1\n"
"        self.logger.info('done doing something')\n"
"\n"
"def some_function():\n"
"    module_logger.info('received a call to \"some_function\"')"
msgstr ""

#: ../../howto/logging-cookbook.rst:76
msgid "The output looks like this:"
msgstr ""

#: ../../howto/logging-cookbook.rst:78
msgid ""
"2005-03-23 23:47:11,663 - spam_application - INFO -\n"
"   creating an instance of auxiliary_module.Auxiliary\n"
"2005-03-23 23:47:11,665 - spam_application.auxiliary.Auxiliary - INFO -\n"
"   creating an instance of Auxiliary\n"
"2005-03-23 23:47:11,665 - spam_application - INFO -\n"
"   created an instance of auxiliary_module.Auxiliary\n"
"2005-03-23 23:47:11,668 - spam_application - INFO -\n"
"   calling auxiliary_module.Auxiliary.do_something\n"
"2005-03-23 23:47:11,668 - spam_application.auxiliary.Auxiliary - INFO -\n"
"   doing something\n"
"2005-03-23 23:47:11,669 - spam_application.auxiliary.Auxiliary - INFO -\n"
"   done doing something\n"
"2005-03-23 23:47:11,670 - spam_application - INFO -\n"
"   finished auxiliary_module.Auxiliary.do_something\n"
"2005-03-23 23:47:11,671 - spam_application - INFO -\n"
"   calling auxiliary_module.some_function()\n"
"2005-03-23 23:47:11,672 - spam_application.auxiliary - INFO -\n"
"   received a call to 'some_function'\n"
"2005-03-23 23:47:11,673 - spam_application - INFO -\n"
"   done with auxiliary_module.some_function()"
msgstr ""

#: ../../howto/logging-cookbook.rst:102
msgid "Logging from multiple threads"
msgstr ""

#: ../../howto/logging-cookbook.rst:104
msgid ""
"Logging from multiple threads requires no special effort. The following "
"example shows logging from the main (initial) thread and another thread::"
msgstr ""

#: ../../howto/logging-cookbook.rst:107
msgid ""
"import logging\n"
"import threading\n"
"import time\n"
"\n"
"def worker(arg):\n"
"    while not arg['stop']:\n"
"        logging.debug('Hi from myfunc')\n"
"        time.sleep(0.5)\n"
"\n"
"def main():\n"
"    logging.basicConfig(level=logging.DEBUG, format='%(relativeCreated)6d "
"%(threadName)s %(message)s')\n"
"    info = {'stop': False}\n"
"    thread = threading.Thread(target=worker, args=(info,))\n"
"    thread.start()\n"
"    while True:\n"
"        try:\n"
"            logging.debug('Hello from main')\n"
"            time.sleep(0.75)\n"
"        except KeyboardInterrupt:\n"
"            info['stop'] = True\n"
"            break\n"
"    thread.join()\n"
"\n"
"if __name__ == '__main__':\n"
"    main()"
msgstr ""

#: ../../howto/logging-cookbook.rst:133
msgid "When run, the script should print something like the following:"
msgstr ""

#: ../../howto/logging-cookbook.rst:135
msgid ""
"   0 Thread-1 Hi from myfunc\n"
"   3 MainThread Hello from main\n"
" 505 Thread-1 Hi from myfunc\n"
" 755 MainThread Hello from main\n"
"1007 Thread-1 Hi from myfunc\n"
"1507 MainThread Hello from main\n"
"1508 Thread-1 Hi from myfunc\n"
"2010 Thread-1 Hi from myfunc\n"
"2258 MainThread Hello from main\n"
"2512 Thread-1 Hi from myfunc\n"
"3009 MainThread Hello from main\n"
"3013 Thread-1 Hi from myfunc\n"
"3515 Thread-1 Hi from myfunc\n"
"3761 MainThread Hello from main\n"
"4017 Thread-1 Hi from myfunc\n"
"4513 MainThread Hello from main\n"
"4518 Thread-1 Hi from myfunc"
msgstr ""

#: ../../howto/logging-cookbook.rst:155
msgid ""
"This shows the logging output interspersed as one might expect. This "
"approach works for more threads than shown here, of course."
msgstr ""

#: ../../howto/logging-cookbook.rst:159
msgid "Multiple handlers and formatters"
msgstr ""

#: ../../howto/logging-cookbook.rst:161
msgid ""
"Loggers are plain Python objects.  The :meth:`~Logger.addHandler` method has "
"no minimum or maximum quota for the number of handlers you may add.  "
"Sometimes it will be beneficial for an application to log all messages of "
"all severities to a text file while simultaneously logging errors or above "
"to the console.  To set this up, simply configure the appropriate handlers.  "
"The logging calls in the application code will remain unchanged.  Here is a "
"slight modification to the previous simple module-based configuration "
"example::"
msgstr ""

#: ../../howto/logging-cookbook.rst:169
msgid ""
"import logging\n"
"\n"
"logger = logging.getLogger('simple_example')\n"
"logger.setLevel(logging.DEBUG)\n"
"# create file handler which logs even debug messages\n"
"fh = logging.FileHandler('spam.log')\n"
"fh.setLevel(logging.DEBUG)\n"
"# create console handler with a higher log level\n"
"ch = logging.StreamHandler()\n"
"ch.setLevel(logging.ERROR)\n"
"# create formatter and add it to the handlers\n"
"formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - "
"%(message)s')\n"
"ch.setFormatter(formatter)\n"
"fh.setFormatter(formatter)\n"
"# add the handlers to logger\n"
"logger.addHandler(ch)\n"
"logger.addHandler(fh)\n"
"\n"
"# 'application' code\n"
"logger.debug('debug message')\n"
"logger.info('info message')\n"
"logger.warning('warn message')\n"
"logger.error('error message')\n"
"logger.critical('critical message')"
msgstr ""

#: ../../howto/logging-cookbook.rst:194
msgid ""
"Notice that the 'application' code does not care about multiple handlers.  "
"All that changed was the addition and configuration of a new handler named "
"*fh*."
msgstr ""

#: ../../howto/logging-cookbook.rst:197
msgid ""
"The ability to create new handlers with higher- or lower-severity filters "
"can be very helpful when writing and testing an application.  Instead of "
"using many ``print`` statements for debugging, use ``logger.debug``: Unlike "
"the print statements, which you will have to delete or comment out later, "
"the logger.debug statements can remain intact in the source code and remain "
"dormant until you need them again.  At that time, the only change that needs "
"to happen is to modify the severity level of the logger and/or handler to "
"debug."
msgstr ""

#: ../../howto/logging-cookbook.rst:208
msgid "Logging to multiple destinations"
msgstr ""

#: ../../howto/logging-cookbook.rst:210
msgid ""
"Let's say you want to log to console and file with different message formats "
"and in differing circumstances. Say you want to log messages with levels of "
"DEBUG and higher to file, and those messages at level INFO and higher to the "
"console. Let's also assume that the file should contain timestamps, but the "
"console messages should not. Here's how you can achieve this::"
msgstr ""

#: ../../howto/logging-cookbook.rst:216
msgid ""
"import logging\n"
"\n"
"# set up logging to file - see previous section for more details\n"
"logging.basicConfig(level=logging.DEBUG,\n"
"                    format='%(asctime)s %(name)-12s %(levelname)-8s "
"%(message)s',\n"
"                    datefmt='%m-%d %H:%M',\n"
"                    filename='/tmp/myapp.log',\n"
"                    filemode='w')\n"
"# define a Handler which writes INFO messages or higher to the sys.stderr\n"
"console = logging.StreamHandler()\n"
"console.setLevel(logging.INFO)\n"
"# set a format which is simpler for console use\n"
"formatter = logging.Formatter('%(name)-12s: %(levelname)-8s %(message)s')\n"
"# tell the handler to use this format\n"
"console.setFormatter(formatter)\n"
"# add the handler to the root logger\n"
"logging.getLogger().addHandler(console)\n"
"\n"
"# Now, we can log to the root logger, or any other logger. First the "
"root...\n"
"logging.info('Jackdaws love my big sphinx of quartz.')\n"
"\n"
"# Now, define a couple of other loggers which might represent areas in your\n"
"# application:\n"
"\n"
"logger1 = logging.getLogger('myapp.area1')\n"
"logger2 = logging.getLogger('myapp.area2')\n"
"\n"
"logger1.debug('Quick zephyrs blow, vexing daft Jim.')\n"
"logger1.info('How quickly daft jumping zebras vex.')\n"
"logger2.warning('Jail zesty vixen who grabbed pay from quack.')\n"
"logger2.error('The five boxing wizards jump quickly.')"
msgstr ""

#: ../../howto/logging-cookbook.rst:248
msgid "When you run this, on the console you will see"
msgstr ""

#: ../../howto/logging-cookbook.rst:250
msgid ""
"root        : INFO     Jackdaws love my big sphinx of quartz.\n"
"myapp.area1 : INFO     How quickly daft jumping zebras vex.\n"
"myapp.area2 : WARNING  Jail zesty vixen who grabbed pay from quack.\n"
"myapp.area2 : ERROR    The five boxing wizards jump quickly."
msgstr ""

#: ../../howto/logging-cookbook.rst:257
msgid "and in the file you will see something like"
msgstr ""

#: ../../howto/logging-cookbook.rst:259
msgid ""
"10-22 22:19 root         INFO     Jackdaws love my big sphinx of quartz.\n"
"10-22 22:19 myapp.area1  DEBUG    Quick zephyrs blow, vexing daft Jim.\n"
"10-22 22:19 myapp.area1  INFO     How quickly daft jumping zebras vex.\n"
"10-22 22:19 myapp.area2  WARNING  Jail zesty vixen who grabbed pay from "
"quack.\n"
"10-22 22:19 myapp.area2  ERROR    The five boxing wizards jump quickly."
msgstr ""

#: ../../howto/logging-cookbook.rst:267
msgid ""
"As you can see, the DEBUG message only shows up in the file. The other "
"messages are sent to both destinations."
msgstr ""

#: ../../howto/logging-cookbook.rst:270
msgid ""
"This example uses console and file handlers, but you can use any number and "
"combination of handlers you choose."
msgstr ""

#: ../../howto/logging-cookbook.rst:273
msgid ""
"Note that the above choice of log filename ``/tmp/myapp.log`` implies use of "
"a standard location for temporary files on POSIX systems. On Windows, you "
"may need to choose a different directory name for the log - just ensure that "
"the directory exists and that you have the permissions to create and update "
"files in it."
msgstr ""

#: ../../howto/logging-cookbook.rst:282
msgid "Custom handling of levels"
msgstr ""

#: ../../howto/logging-cookbook.rst:284
msgid ""
"Sometimes, you might want to do something slightly different from the "
"standard handling of levels in handlers, where all levels above a threshold "
"get processed by a handler. To do this, you need to use filters. Let's look "
"at a scenario where you want to arrange things as follows:"
msgstr ""

#: ../../howto/logging-cookbook.rst:289
msgid "Send messages of severity ``INFO`` and ``WARNING`` to ``sys.stdout``"
msgstr ""

#: ../../howto/logging-cookbook.rst:290
msgid "Send messages of severity ``ERROR`` and above to ``sys.stderr``"
msgstr ""

#: ../../howto/logging-cookbook.rst:291
msgid "Send messages of severity ``DEBUG`` and above to file ``app.log``"
msgstr ""

#: ../../howto/logging-cookbook.rst:293
msgid "Suppose you configure logging with the following JSON:"
msgstr ""

#: ../../howto/logging-cookbook.rst:295
msgid ""
"{\n"
"    \"version\": 1,\n"
"    \"disable_existing_loggers\": false,\n"
"    \"formatters\": {\n"
"        \"simple\": {\n"
"            \"format\": \"%(levelname)-8s - %(message)s\"\n"
"        }\n"
"    },\n"
"    \"handlers\": {\n"
"        \"stdout\": {\n"
"            \"class\": \"logging.StreamHandler\",\n"
"            \"level\": \"INFO\",\n"
"            \"formatter\": \"simple\",\n"
"            \"stream\": \"ext://sys.stdout\"\n"
"        },\n"
"        \"stderr\": {\n"
"            \"class\": \"logging.StreamHandler\",\n"
"            \"level\": \"ERROR\",\n"
"            \"formatter\": \"simple\",\n"
"            \"stream\": \"ext://sys.stderr\"\n"
"        },\n"
"        \"file\": {\n"
"            \"class\": \"logging.FileHandler\",\n"
"            \"formatter\": \"simple\",\n"
"            \"filename\": \"app.log\",\n"
"            \"mode\": \"w\"\n"
"        }\n"
"    },\n"
"    \"root\": {\n"
"        \"level\": \"DEBUG\",\n"
"        \"handlers\": [\n"
"            \"stderr\",\n"
"            \"stdout\",\n"
"            \"file\"\n"
"        ]\n"
"    }\n"
"}"
msgstr ""

#: ../../howto/logging-cookbook.rst:335
msgid ""
"This configuration does *almost* what we want, except that ``sys.stdout`` "
"would show messages of severity ``ERROR`` and only events of this severity "
"and higher will be tracked as well as ``INFO`` and ``WARNING`` messages. To "
"prevent this, we can set up a filter which excludes those messages and add "
"it to the relevant handler. This can be configured by adding a ``filters`` "
"section parallel to ``formatters`` and ``handlers``:"
msgstr ""

#: ../../howto/logging-cookbook.rst:341
msgid ""
"{\n"
"    \"filters\": {\n"
"        \"warnings_and_below\": {\n"
"            \"()\" : \"__main__.filter_maker\",\n"
"            \"level\": \"WARNING\"\n"
"        }\n"
"    }\n"
"}"
msgstr ""

#: ../../howto/logging-cookbook.rst:352
msgid "and changing the section on the ``stdout`` handler to add it:"
msgstr ""

#: ../../howto/logging-cookbook.rst:354
msgid ""
"{\n"
"    \"stdout\": {\n"
"        \"class\": \"logging.StreamHandler\",\n"
"        \"level\": \"INFO\",\n"
"        \"formatter\": \"simple\",\n"
"        \"stream\": \"ext://sys.stdout\",\n"
"        \"filters\": [\"warnings_and_below\"]\n"
"    }\n"
"}"
msgstr ""

#: ../../howto/logging-cookbook.rst:366
msgid ""
"A filter is just a function, so we can define the ``filter_maker`` (a "
"factory function) as follows:"
msgstr ""

#: ../../howto/logging-cookbook.rst:369
msgid ""
"def filter_maker(level):\n"
"    level = getattr(logging, level)\n"
"\n"
"    def filter(record):\n"
"        return record.levelno <= level\n"
"\n"
"    return filter"
msgstr ""
"def filter_maker(level):\n"
"    level = getattr(logging, level)\n"
"\n"
"    def filter(record):\n"
"        return record.levelno <= level\n"
"\n"
"    return filter"

#: ../../howto/logging-cookbook.rst:379
msgid ""
"This converts the string argument passed in to a numeric level, and returns "
"a function which only returns ``True`` if the level of the passed in record "
"is at or below the specified level. Note that in this example I have defined "
"the ``filter_maker`` in a test script ``main.py`` that I run from the "
"command line, so its module will be ``__main__`` - hence the ``__main__."
"filter_maker`` in the filter configuration. You will need to change that if "
"you define it in a different module."
msgstr ""

#: ../../howto/logging-cookbook.rst:387
msgid "With the filter added, we can run ``main.py``, which in full is:"
msgstr ""

#: ../../howto/logging-cookbook.rst:389
msgid ""
"import json\n"
"import logging\n"
"import logging.config\n"
"\n"
"CONFIG = '''\n"
"{\n"
"    \"version\": 1,\n"
"    \"disable_existing_loggers\": false,\n"
"    \"formatters\": {\n"
"        \"simple\": {\n"
"            \"format\": \"%(levelname)-8s - %(message)s\"\n"
"        }\n"
"    },\n"
"    \"filters\": {\n"
"        \"warnings_and_below\": {\n"
"            \"()\" : \"__main__.filter_maker\",\n"
"            \"level\": \"WARNING\"\n"
"        }\n"
"    },\n"
"    \"handlers\": {\n"
"        \"stdout\": {\n"
"            \"class\": \"logging.StreamHandler\",\n"
"            \"level\": \"INFO\",\n"
"            \"formatter\": \"simple\",\n"
"            \"stream\": \"ext://sys.stdout\",\n"
"            \"filters\": [\"warnings_and_below\"]\n"
"        },\n"
"        \"stderr\": {\n"
"            \"class\": \"logging.StreamHandler\",\n"
"            \"level\": \"ERROR\",\n"
"            \"formatter\": \"simple\",\n"
"            \"stream\": \"ext://sys.stderr\"\n"
"        },\n"
"        \"file\": {\n"
"            \"class\": \"logging.FileHandler\",\n"
"            \"formatter\": \"simple\",\n"
"            \"filename\": \"app.log\",\n"
"            \"mode\": \"w\"\n"
"        }\n"
"    },\n"
"    \"root\": {\n"
"        \"level\": \"DEBUG\",\n"
"        \"handlers\": [\n"
"            \"stderr\",\n"
"            \"stdout\",\n"
"            \"file\"\n"
"        ]\n"
"    }\n"
"}\n"
"'''\n"
"\n"
"def filter_maker(level):\n"
"    level = getattr(logging, level)\n"
"\n"
"    def filter(record):\n"
"        return record.levelno <= level\n"
"\n"
"    return filter\n"
"\n"
"logging.config.dictConfig(json.loads(CONFIG))\n"
"logging.debug('A DEBUG message')\n"
"logging.info('An INFO message')\n"
"logging.warning('A WARNING message')\n"
"logging.error('An ERROR message')\n"
"logging.critical('A CRITICAL message')"
msgstr ""

#: ../../howto/logging-cookbook.rst:457
msgid "And after running it like this:"
msgstr ""

#: ../../howto/logging-cookbook.rst:459
msgid "python main.py 2>stderr.log >stdout.log"
msgstr ""

#: ../../howto/logging-cookbook.rst:463
msgid "We can see the results are as expected:"
msgstr ""

#: ../../howto/logging-cookbook.rst:465
msgid ""
"$ more *.log\n"
"::::::::::::::\n"
"app.log\n"
"::::::::::::::\n"
"DEBUG    - A DEBUG message\n"
"INFO     - An INFO message\n"
"WARNING  - A WARNING message\n"
"ERROR    - An ERROR message\n"
"CRITICAL - A CRITICAL message\n"
"::::::::::::::\n"
"stderr.log\n"
"::::::::::::::\n"
"ERROR    - An ERROR message\n"
"CRITICAL - A CRITICAL message\n"
"::::::::::::::\n"
"stdout.log\n"
"::::::::::::::\n"
"INFO     - An INFO message\n"
"WARNING  - A WARNING message"
msgstr ""

#: ../../howto/logging-cookbook.rst:489
msgid "Configuration server example"
msgstr ""

#: ../../howto/logging-cookbook.rst:491
msgid "Here is an example of a module using the logging configuration server::"
msgstr ""

#: ../../howto/logging-cookbook.rst:493
msgid ""
"import logging\n"
"import logging.config\n"
"import time\n"
"import os\n"
"\n"
"# read initial config file\n"
"logging.config.fileConfig('logging.conf')\n"
"\n"
"# create and start listener on port 9999\n"
"t = logging.config.listen(9999)\n"
"t.start()\n"
"\n"
"logger = logging.getLogger('simpleExample')\n"
"\n"
"try:\n"
"    # loop through logging calls to see the difference\n"
"    # new configurations make, until Ctrl+C is pressed\n"
"    while True:\n"
"        logger.debug('debug message')\n"
"        logger.info('info message')\n"
"        logger.warning('warn message')\n"
"        logger.error('error message')\n"
"        logger.critical('critical message')\n"
"        time.sleep(5)\n"
"except KeyboardInterrupt:\n"
"    # cleanup\n"
"    logging.config.stopListening()\n"
"    t.join()"
msgstr ""

#: ../../howto/logging-cookbook.rst:522
msgid ""
"And here is a script that takes a filename and sends that file to the "
"server, properly preceded with the binary-encoded length, as the new logging "
"configuration::"
msgstr ""

#: ../../howto/logging-cookbook.rst:526
msgid ""
"#!/usr/bin/env python\n"
"import socket, sys, struct\n"
"\n"
"with open(sys.argv[1], 'rb') as f:\n"
"    data_to_send = f.read()\n"
"\n"
"HOST = 'localhost'\n"
"PORT = 9999\n"
"s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\n"
"print('connecting...')\n"
"s.connect((HOST, PORT))\n"
"print('sending config...')\n"
"s.send(struct.pack('>L', len(data_to_send)))\n"
"s.send(data_to_send)\n"
"s.close()\n"
"print('complete')"
msgstr ""
"#!/usr/bin/env python\n"
"import socket, sys, struct\n"
"\n"
"with open(sys.argv[1], 'rb') as f:\n"
"    data_to_send = f.read()\n"
"\n"
"HOST = 'localhost'\n"
"PORT = 9999\n"
"s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\n"
"print('connecting...')\n"
"s.connect((HOST, PORT))\n"
"print('sending config...')\n"
"s.send(struct.pack('>L', len(data_to_send)))\n"
"s.send(data_to_send)\n"
"s.close()\n"
"print('complete')"

#: ../../howto/logging-cookbook.rst:547
msgid "Dealing with handlers that block"
msgstr ""

#: ../../howto/logging-cookbook.rst:551
msgid ""
"Sometimes you have to get your logging handlers to do their work without "
"blocking the thread you're logging from. This is common in web applications, "
"though of course it also occurs in other scenarios."
msgstr ""

#: ../../howto/logging-cookbook.rst:555
msgid ""
"A common culprit which demonstrates sluggish behaviour is the :class:"
"`SMTPHandler`: sending emails can take a long time, for a number of reasons "
"outside the developer's control (for example, a poorly performing mail or "
"network infrastructure). But almost any network-based handler can block: "
"Even a :class:`SocketHandler` operation may do a DNS query under the hood "
"which is too slow (and this query can be deep in the socket library code, "
"below the Python layer, and outside your control)."
msgstr ""

#: ../../howto/logging-cookbook.rst:563
msgid ""
"One solution is to use a two-part approach. For the first part, attach only "
"a :class:`QueueHandler` to those loggers which are accessed from performance-"
"critical threads. They simply write to their queue, which can be sized to a "
"large enough capacity or initialized with no upper bound to their size. The "
"write to the queue will typically be accepted quickly, though you will "
"probably need to catch the :exc:`queue.Full` exception as a precaution in "
"your code. If you are a library developer who has performance-critical "
"threads in their code, be sure to document this (together with a suggestion "
"to attach only ``QueueHandlers`` to your loggers) for the benefit of other "
"developers who will use your code."
msgstr ""

#: ../../howto/logging-cookbook.rst:574
msgid ""
"The second part of the solution is :class:`QueueListener`, which has been "
"designed as the counterpart to :class:`QueueHandler`.  A :class:"
"`QueueListener` is very simple: it's passed a queue and some handlers, and "
"it fires up an internal thread which listens to its queue for LogRecords "
"sent from ``QueueHandlers`` (or any other source of ``LogRecords``, for that "
"matter). The ``LogRecords`` are removed from the queue and passed to the "
"handlers for processing."
msgstr ""

#: ../../howto/logging-cookbook.rst:582
msgid ""
"The advantage of having a separate :class:`QueueListener` class is that you "
"can use the same instance to service multiple ``QueueHandlers``. This is "
"more resource-friendly than, say, having threaded versions of the existing "
"handler classes, which would eat up one thread per handler for no particular "
"benefit."
msgstr ""

#: ../../howto/logging-cookbook.rst:587
msgid "An example of using these two classes follows (imports omitted)::"
msgstr ""

#: ../../howto/logging-cookbook.rst:589
msgid ""
"que = queue.Queue(-1)  # no limit on size\n"
"queue_handler = QueueHandler(que)\n"
"handler = logging.StreamHandler()\n"
"listener = QueueListener(que, handler)\n"
"root = logging.getLogger()\n"
"root.addHandler(queue_handler)\n"
"formatter = logging.Formatter('%(threadName)s: %(message)s')\n"
"handler.setFormatter(formatter)\n"
"listener.start()\n"
"# The log output will display the thread which generated\n"
"# the event (the main thread) rather than the internal\n"
"# thread which monitors the internal queue. This is what\n"
"# you want to happen.\n"
"root.warning('Look out!')\n"
"listener.stop()"
msgstr ""

#: ../../howto/logging-cookbook.rst:605
msgid "which, when run, will produce:"
msgstr ""

#: ../../howto/logging-cookbook.rst:607
msgid "MainThread: Look out!"
msgstr ""

#: ../../howto/logging-cookbook.rst:611
msgid ""
"Although the earlier discussion wasn't specifically talking about async "
"code, but rather about slow logging handlers, it should be noted that when "
"logging from async code, network and even file handlers could lead to "
"problems (blocking the event loop) because some logging is done from :mod:"
"`asyncio` internals. It might be best, if any async code is used in an "
"application, to use the above approach for logging, so that any blocking "
"code runs only in the ``QueueListener`` thread."
msgstr ""

#: ../../howto/logging-cookbook.rst:619
msgid ""
"Prior to Python 3.5, the :class:`QueueListener` always passed every message "
"received from the queue to every handler it was initialized with. (This was "
"because it was assumed that level filtering was all done on the other side, "
"where the queue is filled.) From 3.5 onwards, this behaviour can be changed "
"by passing a keyword argument ``respect_handler_level=True`` to the "
"listener's constructor. When this is done, the listener compares the level "
"of each message with the handler's level, and only passes a message to a "
"handler if it's appropriate to do so."
msgstr ""

#: ../../howto/logging-cookbook.rst:629
msgid ""
"The :class:`QueueListener` can be started (and stopped) via the :keyword:"
"`with` statement. For example:"
msgstr ""

#: ../../howto/logging-cookbook.rst:633
msgid ""
"with QueueListener(que, handler) as listener:\n"
"    # The queue listener automatically starts\n"
"    # when the 'with' block is entered.\n"
"    pass\n"
"# The queue listener automatically stops once\n"
"# the 'with' block is exited."
msgstr ""

#: ../../howto/logging-cookbook.rst:645
msgid "Sending and receiving logging events across a network"
msgstr ""

#: ../../howto/logging-cookbook.rst:647
msgid ""
"Let's say you want to send logging events across a network, and handle them "
"at the receiving end. A simple way of doing this is attaching a :class:"
"`SocketHandler` instance to the root logger at the sending end::"
msgstr ""

#: ../../howto/logging-cookbook.rst:651
msgid ""
"import logging, logging.handlers\n"
"\n"
"rootLogger = logging.getLogger()\n"
"rootLogger.setLevel(logging.DEBUG)\n"
"socketHandler = logging.handlers.SocketHandler('localhost',\n"
"                    logging.handlers.DEFAULT_TCP_LOGGING_PORT)\n"
"# don't bother with a formatter, since a socket handler sends the event as\n"
"# an unformatted pickle\n"
"rootLogger.addHandler(socketHandler)\n"
"\n"
"# Now, we can log to the root logger, or any other logger. First the "
"root...\n"
"logging.info('Jackdaws love my big sphinx of quartz.')\n"
"\n"
"# Now, define a couple of other loggers which might represent areas in your\n"
"# application:\n"
"\n"
"logger1 = logging.getLogger('myapp.area1')\n"
"logger2 = logging.getLogger('myapp.area2')\n"
"\n"
"logger1.debug('Quick zephyrs blow, vexing daft Jim.')\n"
"logger1.info('How quickly daft jumping zebras vex.')\n"
"logger2.warning('Jail zesty vixen who grabbed pay from quack.')\n"
"logger2.error('The five boxing wizards jump quickly.')"
msgstr ""

#: ../../howto/logging-cookbook.rst:675
msgid ""
"At the receiving end, you can set up a receiver using the :mod:"
"`socketserver` module. Here is a basic working example::"
msgstr ""

#: ../../howto/logging-cookbook.rst:678
msgid ""
"import pickle\n"
"import logging\n"
"import logging.handlers\n"
"import socketserver\n"
"import struct\n"
"\n"
"\n"
"class LogRecordStreamHandler(socketserver.StreamRequestHandler):\n"
"    \"\"\"Handler for a streaming logging request.\n"
"\n"
"    This basically logs the record using whatever logging policy is\n"
"    configured locally.\n"
"    \"\"\"\n"
"\n"
"    def handle(self):\n"
"        \"\"\"\n"
"        Handle multiple requests - each expected to be a 4-byte length,\n"
"        followed by the LogRecord in pickle format. Logs the record\n"
"        according to whatever policy is configured locally.\n"
"        \"\"\"\n"
"        while True:\n"
"            chunk = self.connection.recv(4)\n"
"            if len(chunk) < 4:\n"
"                break\n"
"            slen = struct.unpack('>L', chunk)[0]\n"
"            chunk = self.connection.recv(slen)\n"
"            while len(chunk) < slen:\n"
"                chunk = chunk + self.connection.recv(slen - len(chunk))\n"
"            obj = self.unPickle(chunk)\n"
"            record = logging.makeLogRecord(obj)\n"
"            self.handleLogRecord(record)\n"
"\n"
"    def unPickle(self, data):\n"
"        return pickle.loads(data)\n"
"\n"
"    def handleLogRecord(self, record):\n"
"        # if a name is specified, we use the named logger rather than the "
"one\n"
"        # implied by the record.\n"
"        if self.server.logname is not None:\n"
"            name = self.server.logname\n"
"        else:\n"
"            name = record.name\n"
"        logger = logging.getLogger(name)\n"
"        # N.B. EVERY record gets logged. This is because Logger.handle\n"
"        # is normally called AFTER logger-level filtering. If you want\n"
"        # to do filtering, do it at the client end to save wasting\n"
"        # cycles and network bandwidth!\n"
"        logger.handle(record)\n"
"\n"
"class LogRecordSocketReceiver(socketserver.ThreadingTCPServer):\n"
"    \"\"\"\n"
"    Simple TCP socket-based logging receiver suitable for testing.\n"
"    \"\"\"\n"
"\n"
"    allow_reuse_address = True\n"
"\n"
"    def __init__(self, host='localhost',\n"
"                 port=logging.handlers.DEFAULT_TCP_LOGGING_PORT,\n"
"                 handler=LogRecordStreamHandler):\n"
"        socketserver.ThreadingTCPServer.__init__(self, (host, port), "
"handler)\n"
"        self.abort = 0\n"
"        self.timeout = 1\n"
"        self.logname = None\n"
"\n"
"    def serve_until_stopped(self):\n"
"        import select\n"
"        abort = 0\n"
"        while not abort:\n"
"            rd, wr, ex = select.select([self.socket.fileno()],\n"
"                                       [], [],\n"
"                                       self.timeout)\n"
"            if rd:\n"
"                self.handle_request()\n"
"            abort = self.abort\n"
"\n"
"def main():\n"
"    logging.basicConfig(\n"
"        format='%(relativeCreated)5d %(name)-15s %(levelname)-8s "
"%(message)s')\n"
"    tcpserver = LogRecordSocketReceiver()\n"
"    print('About to start TCP server...')\n"
"    tcpserver.serve_until_stopped()\n"
"\n"
"if __name__ == '__main__':\n"
"    main()"
msgstr ""

#: ../../howto/logging-cookbook.rst:763
msgid ""
"First run the server, and then the client. On the client side, nothing is "
"printed on the console; on the server side, you should see something like:"
msgstr ""

#: ../../howto/logging-cookbook.rst:766
msgid ""
"About to start TCP server...\n"
"   59 root            INFO     Jackdaws love my big sphinx of quartz.\n"
"   59 myapp.area1     DEBUG    Quick zephyrs blow, vexing daft Jim.\n"
"   69 myapp.area1     INFO     How quickly daft jumping zebras vex.\n"
"   69 myapp.area2     WARNING  Jail zesty vixen who grabbed pay from quack.\n"
"   69 myapp.area2     ERROR    The five boxing wizards jump quickly."
msgstr ""

#: ../../howto/logging-cookbook.rst:775
msgid ""
"Note that there are some security issues with pickle in some scenarios. If "
"these affect you, you can use an alternative serialization scheme by "
"overriding the :meth:`~SocketHandler.makePickle` method and implementing "
"your alternative there, as well as adapting the above script to use your "
"alternative serialization."
msgstr ""

#: ../../howto/logging-cookbook.rst:783
msgid "Running a logging socket listener in production"
msgstr ""

#: ../../howto/logging-cookbook.rst:787