logging-cookbook.po

# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2001-2022, Python Software Foundation
# This file is distributed under the same license as the Python package.
#
# Translators:
msgid ""
msgstr ""
"Project-Id-Version: Python 3.12\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2024-04-18 00:04+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:56
msgid"Here is the auxiliary module::"
msgstr""

#:../../howto/logging-cookbook.rst:76
msgid"The output looks like this:"
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:133
msgid"When run, the script should print something like the following:"
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: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:248
msgid"When you run this, on the console you will see"
msgstr""

#:../../howto/logging-cookbook.rst:257
msgid"and in the file you will see something like"
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:335
msgid""
"This configuration does *almost* what we want, except that ``sys.stdout`` "
"would show messages of severity ``ERROR`` and above 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:352
msgid"and changing the section on the ``stdout`` handler to add it:"
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: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:457
msgid"And after running it like this:"
msgstr""

#:../../howto/logging-cookbook.rst:463
msgid"We can see the results are as expected:"
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: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: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:605
msgid"which, when run, will produce:"
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:632
msgid"Sending and receiving logging events across a network"
msgstr""

#:../../howto/logging-cookbook.rst:634
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:662
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:750
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:762
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:770
msgid"Running a logging socket listener in production"
msgstr""

#:../../howto/logging-cookbook.rst:774
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:781
msgid"File"
msgstr"檔案"

#:../../howto/logging-cookbook.rst:781
msgid"Purpose"
msgstr"目的"

#:../../howto/logging-cookbook.rst:783
msgid":file:`prepare.sh`"
msgstr":file:`prepare.sh`"

#:../../howto/logging-cookbook.rst:783
msgid"A Bash script to prepare the environment for testing"
msgstr""

#:../../howto/logging-cookbook.rst:786
msgid":file:`supervisor.conf`"
msgstr":file:`supervisor.conf`"

#:../../howto/logging-cookbook.rst:786
msgid""
"The Supervisor configuration file, which has entries for the listener and a "
"multi-process web application"
msgstr""

#:../../howto/logging-cookbook.rst:790
msgid":file:`ensure_app.sh`"
msgstr":file:`ensure_app.sh`"

#:../../howto/logging-cookbook.rst:790
msgid""
"A Bash script to ensure that Supervisor is running with the above "
"configuration"
msgstr""

#:../../howto/logging-cookbook.rst:793
msgid":file:`log_listener.py`"
msgstr":file:`log_listener.py`"

#:../../howto/logging-cookbook.rst:793
msgid""
"The socket listener program which receives log events and records them to a "
"file"
msgstr""

#:../../howto/logging-cookbook.rst:796
msgid":file:`main.py`"
msgstr":file:`main.py`"

#:../../howto/logging-cookbook.rst:796
msgid""
"A simple web application which performs logging via a socket connected to "
"the listener"
msgstr""

#:../../howto/logging-cookbook.rst:799
msgid":file:`webapp.json`"
msgstr":file:`webapp.json`"

#:../../howto/logging-cookbook.rst:799
msgid"A JSON configuration file for the web application"
msgstr""

#:../../howto/logging-cookbook.rst:801
msgid":file:`client.py`"
msgstr":file:`client.py`"

#:../../howto/logging-cookbook.rst:801
msgid"A Python script to exercise the web application"
msgstr""

#:../../howto/logging-cookbook.rst:804
msgid""
"The web application uses `Gunicorn <https://gunicorn.org/>`_, which is a "
"popular web application server that starts multiple worker processes to "
"handle requests. This example setup shows how the workers can write to the "
"same log file without conflicting with one another --- they all go through "
"the socket listener."
msgstr""

#:../../howto/logging-cookbook.rst:809
msgid"To test these files, do the following in a POSIX environment:"
msgstr""

#:../../howto/logging-cookbook.rst:811
msgid""
"Download `the Gist <socket-listener-gist_>`__ as a ZIP archive using the :"
"guilabel:`Download ZIP` button."
msgstr""

#:../../howto/logging-cookbook.rst:814
msgid"Unzip the above files from the archive into a scratch directory."
msgstr""

#:../../howto/logging-cookbook.rst:816
msgid""
"In the scratch directory, run ``bash prepare.sh`` to get things ready. This "
"creates a :file:`run` subdirectory to contain Supervisor-related and log "
"files, and a :file:`venv` subdirectory to contain a virtual environment into "
"which ``bottle``, ``gunicorn`` and ``supervisor`` are installed."
msgstr""

#:../../howto/logging-cookbook.rst:821
msgid""
"Run ``bash ensure_app.sh`` to ensure that Supervisor is running with the "
"above configuration."
msgstr""

#:../../howto/logging-cookbook.rst:824
msgid""
"Run ``venv/bin/python client.py`` to exercise the web application, which "
"will lead to records being written to the log."
msgstr""

#:../../howto/logging-cookbook.rst:827
msgid""
"Inspect the log files in the :file:`run` subdirectory. You should see the "
"most recent log lines in files matching the pattern :file:`app.log*`. They "
"won't be in any particular order, since they have been handled concurrently "
"by different worker processes in a non-deterministic way."
msgstr""

#:../../howto/logging-cookbook.rst:832
msgid""
"You can shut down the listener and the web application by running ``venv/bin/"
"supervisorctl -c supervisor.conf shutdown``."
msgstr""

#:../../howto/logging-cookbook.rst:835
msgid""
"You may need to tweak the configuration files in the unlikely event that the "
"configured ports clash with something else in your test environment."
msgstr""

#:../../howto/logging-cookbook.rst:843
msgid"Adding contextual information to your logging output"
msgstr""

#:../../howto/logging-cookbook.rst:845
msgid""
"Sometimes you want logging output to contain contextual information in "
"addition to the parameters passed to the logging call. For example, in a "
"networked application, it may be desirable to log client-specific "
"information in the log (e.g. remote client's username, or IP address). "
"Although you could use the *extra* parameter to achieve this, it's not "
"always convenient to pass the information in this way. While it might be "
"tempting to create :class:`Logger` instances on a per-connection basis, this "
"is not a good idea because these instances are not garbage collected. While "
"this is not a problem in practice, when the number of :class:`Logger` "
"instances is dependent on the level of granularity you want to use in "
"logging an application, it could be hard to manage if the number of :class:"
"`Logger` instances becomes effectively unbounded."
msgstr""

#:../../howto/logging-cookbook.rst:860
msgid"Using LoggerAdapters to impart contextual information"
msgstr""

#:../../howto/logging-cookbook.rst:862
msgid""
"An easy way in which you can pass contextual information to be output along "
"with logging event information is to use the :class:`LoggerAdapter` class. "
"This class is designed to look like a :class:`Logger`, so that you can call :"
"meth:`debug`, :meth:`info`, :meth:`warning`, :meth:`error`, :meth:"
"`exception`, :meth:`critical` and :meth:`log`. These methods have the same "
"signatures as their counterparts in :class:`Logger`, so you can use the two "
"types of instances interchangeably."
msgstr""

#:../../howto/logging-cookbook.rst:870
msgid""
"When you create an instance of :class:`LoggerAdapter`, you pass it a :class:"
"`Logger` instance and a dict-like object which contains your contextual "
"information. When you call one of the logging methods on an instance of :"
"class:`LoggerAdapter`, it delegates the call to the underlying instance of :"
"class:`Logger` passed to its constructor, and arranges to pass the "
"contextual information in the delegated call. Here's a snippet from the code "
"of :class:`LoggerAdapter`::"
msgstr""

#:../../howto/logging-cookbook.rst:886
msgid""
"The :meth:`~LoggerAdapter.process` method of :class:`LoggerAdapter` is where "
"the contextual information is added to the logging output. It's passed the "
"message and keyword arguments of the logging call, and it passes back "
"(potentially) modified versions of these to use in the call to the "
"underlying logger. The default implementation of this method leaves the "
"message alone, but inserts an 'extra' key in the keyword argument whose "
"value is the dict-like object passed to the constructor. Of course, if you "
"had passed an 'extra' keyword argument in the call to the adapter, it will "
"be silently overwritten."
msgstr""

#:../../howto/logging-cookbook.rst:895
msgid""
"The advantage of using 'extra' is that the values in the dict-like object "
"are merged into the :class:`LogRecord` instance's __dict__, allowing you to "
"use customized strings with your :class:`Formatter` instances which know "
"about the keys of the dict-like object. If you need a different method, e.g. "
"if you want to prepend or append the contextual information to the message "
"string, you just need to subclass :class:`LoggerAdapter` and override :meth:"
"`~LoggerAdapter.process` to do what you need. Here is a simple example::"
msgstr""

#:../../howto/logging-cookbook.rst:911
msgid"which you can use like this::"
msgstr""

#:../../howto/logging-cookbook.rst:916
msgid""
"Then any events that you log to the adapter will have the value of "
"``some_conn_id`` prepended to the log messages."
msgstr""

#:../../howto/logging-cookbook.rst:920
msgid"Using objects other than dicts to pass contextual information"
msgstr""

#:../../howto/logging-cookbook.rst:922
msgid""
"You don't need to pass an actual dict to a :class:`LoggerAdapter` - you "
"could pass an instance of a class which implements ``__getitem__`` and "
"``__iter__`` so that it looks like a dict to logging. This would be useful "
"if you want to generate values dynamically (whereas the values in a dict "
"would be constant)."
msgstr""

#:../../howto/logging-cookbook.rst:931
msgid"Using Filters to impart contextual information"
msgstr""

#:../../howto/logging-cookbook.rst:933
msgid""
"You can also add contextual information to log output using a user-defined :"
"class:`Filter`. ``Filter`` instances are allowed to modify the "
"``LogRecords`` passed to them, including adding additional attributes which "
"can then be output using a suitable format string, or if needed a custom :"
"class:`Formatter`."
msgstr""

#:../../howto/logging-cookbook.rst:938
msgid""
"For example in a web application, the request being processed (or at least, "
"the interesting parts of it) can be stored in a threadlocal (:class:"
"`threading.local`) variable, and then accessed from a ``Filter`` to add, "
"say, information from the request - say, the remote IP address and remote "
"user's username - to the ``LogRecord``, using the attribute names 'ip' and "
"'user' as in the ``LoggerAdapter`` example above. In that case, the same "
"format string can be used to get similar output to that shown above. Here's "
"an example script::"
msgstr""

#:../../howto/logging-cookbook.rst:984
msgid"which, when run, produces something like:"
msgstr""

#:../../howto/logging-cookbook.rst:1002
msgid"Use of ``contextvars``"
msgstr""

#:../../howto/logging-cookbook.rst:1004
msgid""
"Since Python 3.7, the :mod:`contextvars` module has provided context-local "
"storage which works for both :mod:`threading` and :mod:`asyncio` processing "
"needs. This type of storage may thus be generally preferable to thread-"
"locals. The following example shows how, in a multi-threaded environment, "
"logs can populated with contextual information such as, for example, request "
"attributes handled by web applications."
msgstr""

#:../../howto/logging-cookbook.rst:1010
msgid""
"For the purposes of illustration, say that you have different web "
"applications, each independent of the other but running in the same Python "
"process and using a library common to them. How can each of these "
"applications have their own log, where all logging messages from the library "
"(and other request processing code) are directed to the appropriate "
"application's log file, while including in the log additional contextual "
"information such as client IP, HTTP request method and client username?"
msgstr""

#:../../howto/logging-cookbook.rst:1017
msgid"Let's assume that the library can be simulated by the following code:"
msgstr""

#:../../howto/logging-cookbook.rst:1033
msgid""
"We can simulate the multiple web applications by means of two simple "
"classes, ``Request`` and ``WebApp``. These simulate how real threaded web "
"applications work - each request is handled by a thread:"
msgstr""

#:../../howto/logging-cookbook.rst:1177
msgid""
"If you run the above, you should find that roughly half the requests go "
"into :file:`app1.log` and the rest into :file:`app2.log`, and the all the "
"requests are logged to :file:`app.log`. Each webapp-specific log will "
"contain only log entries for only that webapp, and the request information "
"will be displayed consistently in the log (i.e. the information in each "
"dummy request will always appear together in a log line). This is "
"illustrated by the following shell output:"
msgstr""

#:../../howto/logging-cookbook.rst:1224
msgid"Imparting contextual information in handlers"
msgstr""

#:../../howto/logging-cookbook.rst:1226
msgid""
"Each :class:`~Handler` has its own chain of filters. If you want to add "
"contextual information to a :class:`LogRecord` without leaking it to other "
"handlers, you can use a filter that returns a new :class:`~LogRecord` "
"instead of modifying it in-place, as shown in the following script::"
msgstr""

#:../../howto/logging-cookbook.rst:1253
msgid"Logging to a single file from multiple processes"
msgstr""

#:../../howto/logging-cookbook.rst:1255
msgid""
"Although logging is thread-safe, and logging to a single file from multiple "
"threads in a single process *is* supported, logging to a single file from "
"*multiple processes* is *not* supported, because there is no standard way to "
"serialize access to a single file across multiple processes in Python. If "
"you need to log to a single file from multiple processes, one way of doing "
"this is to have all the processes log to a :class:`~handlers.SocketHandler`, "
"and have a separate process which implements a socket server which reads "
"from the socket and logs to file. (If you prefer, you can dedicate one "
"thread in one of the existing processes to perform this function.) :ref:"
"`This section <network-logging>` documents this approach in more detail and "
"includes a working socket receiver which can be used as a starting point for "
"you to adapt in your own applications."
msgstr""

#:../../howto/logging-cookbook.rst:1268
msgid""
"You could also write your own handler which uses the :class:"
"`~multiprocessing.Lock` class from the :mod:`multiprocessing` module to "
"serialize access to the file from your processes. The existing :class:"
"`FileHandler` and subclasses do not make use of :mod:`multiprocessing` at "
"present, though they may do so in the future. Note that at present, the :mod:"
"`multiprocessing` module does not provide working lock functionality on all "
"platforms (see https://bugs.python.org/issue3770)."
msgstr""

#:../../howto/logging-cookbook.rst:1278
msgid""
"Alternatively, you can use a ``Queue`` and a :class:`QueueHandler` to send "
"all logging events to one of the processes in your multi-process "
"application. The following example script demonstrates how you can do this; "
"in the example a separate listener process listens for events sent by other "
"processes and logs them according to its own logging configuration. Although "
"the example only demonstrates one way of doing it (for example, you may want "
"to use a listener thread rather than a separate listener process -- the "
"implementation would be analogous) it does allow for completely different "
"logging configurations for the listener and the other processes in your "
"application, and can be used as the basis for code meeting your own specific "
"requirements::"
msgstr""

#:../../howto/logging-cookbook.rst:1394
msgid""
"A variant of the above script keeps the logging in the main process, in a "
"separate thread::"
msgstr""

#:../../howto/logging-cookbook.rst:1489
msgid""
"This variant shows how you can e.g. apply configuration for particular "
"loggers - e.g. the ``foo`` logger has a special handler which stores all "
"events in the ``foo`` subsystem in a file ``mplog-foo.log``. This will be "
"used by the logging machinery in the main process (even though the logging "
"events are generated in the worker processes) to direct the messages to the "
"appropriate destinations."
msgstr""

#:../../howto/logging-cookbook.rst:1496
msgid"Using concurrent.futures.ProcessPoolExecutor"
msgstr""

#:../../howto/logging-cookbook.rst:1498
msgid""
"If you want to use :class:`concurrent.futures.ProcessPoolExecutor` to start "
"your worker processes, you need to create the queue slightly differently. "
"Instead of"
msgstr""

#:../../howto/logging-cookbook.rst:1506
msgid"you should use"
msgstr""

#:../../howto/logging-cookbook.rst:1512
msgid"and you can then replace the worker creation from this::"
msgstr""

#:../../howto/logging-cookbook.rst:1523
msgid"to this (remembering to first import :mod:`concurrent.futures`)::"
msgstr""

#:../../howto/logging-cookbook.rst:1530
msgid"Deploying Web applications using Gunicorn and uWSGI"
msgstr""

#:../../howto/logging-cookbook.rst:1532
msgid""
"When deploying Web applications using `Gunicorn <https://gunicorn.org/>`_ or "
"`uWSGI <https://uwsgi-docs.readthedocs.io/en/latest/>`_ (or similar), "
"multiple worker processes are created to handle client requests. In such "
"environments, avoid creating file-based handlers directly in your web "
"application. Instead, use a :class:`SocketHandler` to log from the web "
"application to a listener in a separate process. This can be set up using a "
"process management tool such as Supervisor - see `Running a logging socket "
"listener in production`_ for more details."
msgstr""

#:../../howto/logging-cookbook.rst:1542
msgid"Using file rotation"
msgstr""

#:../../howto/logging-cookbook.rst:1547
msgid""
"Sometimes you want to let a log file grow to a certain size, then open a new "
"file and log to that. You may want to keep a certain number of these files, "
"and when that many files have been created, rotate the files so that the "
"number of files and the size of the files both remain bounded. For this "
"usage pattern, the logging package provides a :class:`RotatingFileHandler`::"
msgstr""

#:../../howto/logging-cookbook.rst:1579
msgid""
"The result should be 6 separate files, each with part of the log history for "
"the application:"
msgstr""

#:../../howto/logging-cookbook.rst:1591
msgid""
"The most current file is always :file:`logging_rotatingfile_example.out`, "
"and each time it reaches the size limit it is renamed with the suffix "
"``.1``. Each of the existing backup files is renamed to increment the suffix "
"(``.1`` becomes ``.2``, etc.) and the ``.6`` file is erased."
msgstr""

#:../../howto/logging-cookbook.rst:1596
msgid""
"Obviously this example sets the log length much too small as an extreme "
"example. You would want to set *maxBytes* to an appropriate value."
msgstr""

#:../../howto/logging-cookbook.rst:1604
msgid"Use of alternative formatting styles"
msgstr""

#:../../howto/logging-cookbook.rst:1606
msgid""
"When logging was added to the Python standard library, the only way of "
"formatting messages with variable content was to use the %-formatting "
"method. Since then, Python has gained two new formatting approaches: :class:"
"`string.Template` (added in Python 2.4) and :meth:`str.format` (added in "
"Python 2.6)."
msgstr""

#:../../howto/logging-cookbook.rst:1612
msgid""
"Logging (as of 3.2) provides improved support for these two additional "
"formatting styles. The :class:`Formatter` class been enhanced to take an "
"additional, optional keyword parameter named ``style``. This defaults to "
"``'%'``, but other possible values are ``'{'`` and ``'$'``, which correspond "
"to the other two formatting styles. Backwards compatibility is maintained by "
"default (as you would expect), but by explicitly specifying a style "
"parameter, you get the ability to specify format strings which work with :"
"meth:`str.format` or :class:`string.Template`. Here's an example console "
"session to show the possibilities:"
msgstr""

#:../../howto/logging-cookbook.rst:1646
msgid""
"Note that the formatting of logging messages for final output to logs is "
"completely independent of how an individual logging message is constructed. "
"That can still use %-formatting, as shown here::"
msgstr""

#:../../howto/logging-cookbook.rst:1654
msgid""
"Logging calls (``logger.debug()``, ``logger.info()`` etc.) only take "
"positional parameters for the actual logging message itself, with keyword "
"parameters used only for determining options for how to handle the actual "
"logging call (e.g. the ``exc_info`` keyword parameter to indicate that "
"traceback information should be logged, or the ``extra`` keyword parameter "
"to indicate additional contextual information to be added to the log). So "
"you cannot directly make logging calls using :meth:`str.format` or :class:"
"`string.Template` syntax, because internally the logging package uses %-"
"formatting to merge the format string and the variable arguments. There "
"would be no changing this while preserving backward compatibility, since all "
"logging calls which are out there in existing code will be using %-format "
"strings."
msgstr""

#:../../howto/logging-cookbook.rst:1667
msgid""
"There is, however, a way that you can use {}- and $- formatting to construct "
"your individual log messages. Recall that for a message you can use an "
"arbitrary object as a message format string, and that the logging package "
"will call ``str()`` on that object to get the actual format string. Consider "
"the following two classes::"
msgstr""

#:../../howto/logging-cookbook.rst:1691
msgid""
"Either of these can be used in place of a format string, to allow {}- or $-"
"formatting to be used to build the actual \"message\" part which appears in "
"the formatted log output in place of \"%(message)s\" or \"{message}\" or "
"\"$message\". It's a little unwieldy to use the class names whenever you "
"want to log something, but it's quite palatable if you use an alias such as "
"__ (double underscore --- not to be confused with _, the single underscore "
"used as a synonym/alias for :func:`gettext.gettext` or its brethren)."
msgstr""

#:../../howto/logging-cookbook.rst:1699
msgid""
"The above classes are not included in Python, though they're easy enough to "
"copy and paste into your own code. They can be used as follows (assuming "
"that they're declared in a module called ``wherever``):"
msgstr""

#:../../howto/logging-cookbook.rst:1721
msgid""
"While the above examples use ``print()`` to show how the formatting works, "
"you would of course use ``logger.debug()`` or similar to actually log using "
"this approach."
msgstr""

#:../../howto/logging-cookbook.rst:1725
msgid""
"One thing to note is that you pay no significant performance penalty with "
"this approach: the actual formatting happens not when you make the logging "
"call, but when (and if) the logged message is actually about to be output to "
"a log by a handler. So the only slightly unusual thing which might trip you "
"up is that the parentheses go around the format string and the arguments, "
"not just the format string. That's because the __ notation is just syntax "
"sugar for a constructor call to one of the :samp:`{XXX}Message` classes."
msgstr""

#:../../howto/logging-cookbook.rst:1733
msgid""
"If you prefer, you can use a :class:`LoggerAdapter` to achieve a similar "
"effect to the above, as in the following example::"
msgstr""

#:../../howto/logging-cookbook.rst:1762
msgid""
"The above script should log the message ``Hello, world!`` when run with "
"Python 3.8 or later."
msgstr""

#:../../howto/logging-cookbook.rst:1771
msgid"Customizing ``LogRecord``"
msgstr""

#:../../howto/logging-cookbook.rst:1773
msgid""
"Every logging event is represented by a :class:`LogRecord` instance. When an "
"event is logged and not filtered out by a logger's level, a :class:"
"`LogRecord` is created, populated with information about the event and then "
"passed to the handlers for that logger (and its ancestors, up to and "
"including the logger where further propagation up the hierarchy is "
"disabled). Before Python 3.2, there were only two places where this creation "
"was done:"
msgstr""

#:../../howto/logging-cookbook.rst:1780
msgid""
":meth:`Logger.makeRecord`, which is called in the normal process of logging "
"an event. This invoked :class:`LogRecord` directly to create an instance."
msgstr""

#:../../howto/logging-cookbook.rst:1783
msgid""
":func:`makeLogRecord`, which is called with a dictionary containing "
"attributes to be added to the LogRecord. This is typically invoked when a "
"suitable dictionary has been received over the network (e.g. in pickle form "
"via a :class:`~handlers.SocketHandler`, or in JSON form via an :class:"
"`~handlers.HTTPHandler`)."
msgstr""

#:../../howto/logging-cookbook.rst:1789
msgid""
"This has usually meant that if you need to do anything special with a :class:"
"`LogRecord`, you've had to do one of the following."
msgstr""

#:../../howto/logging-cookbook.rst:1792
msgid""
"Create your own :class:`Logger` subclass, which overrides :meth:`Logger."
"makeRecord`, and set it using :func:`~logging.setLoggerClass` before any "
"loggers that you care about are instantiated."
msgstr""

#:../../howto/logging-cookbook.rst:1795
msgid""
"Add a :class:`Filter` to a logger or handler, which does the necessary "
"special manipulation you need when its :meth:`~Filter.filter` method is "
"called."
msgstr""

#:../../howto/logging-cookbook.rst:1799
msgid""
"The first approach would be a little unwieldy in the scenario where (say) "
"several different libraries wanted to do different things. Each would "
"attempt to set its own :class:`Logger` subclass, and the one which did this "
"last would win."
msgstr""

#:../../howto/logging-cookbook.rst:1804
msgid""
"The second approach works reasonably well for many cases, but does not allow "
"you to e.g. use a specialized subclass of :class:`LogRecord`. Library "
"developers can set a suitable filter on their loggers, but they would have "
"to remember to do this every time they introduced a new logger (which they "
"would do simply by adding new packages or modules and doing ::"
msgstr""

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