# SOME DESCRIPTIVE TITLE.

# Copyright (C) 2001 Python Software Foundation

# This file is distributed under the same license as the Python package.

# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.

#

#, fuzzy

msgid ""

msgstr ""

"Project-Id-Version: Python 3.14\n"

"Report-Msgid-Bugs-To: \n"

"POT-Creation-Date: 2026-09-15 09:12+0000\n"

"PO-Revision-Date: 2025-09-16 00:00+0000\n"

"Language-Team: German (https://app.transifex.com/python-doc/teams/5390/de/)\n"

"Language: de\n"

"MIME-Version: 1.0\n"

"Content-Type: text/plain; charset=UTF-8\n"

"Content-Transfer-Encoding: 8bit\n"

"Plural-Forms: nplurals=2; plural=(n != 1);\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 ""

#: ../../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 ""

#: ../../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 ""

#: ../../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

msgid ""

"To run a logging listener in production, you may need to use a process-"

"management tool such as `Supervisor <http://supervisord.org/>`_. `Here is a "

"Gist <socket-listener-gist_>`__ which provides the bare-bones files to run "

"the above functionality using Supervisor. It consists of the following files:"

msgstr ""

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

msgid "File"

msgstr ""

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

msgid "Purpose"

msgstr ""

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

msgid ":file:`prepare.sh`"

msgstr ""

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

msgid "A Bash script to prepare the environment for testing"

msgstr ""