1:mod:`logging.config` --- Logging configuration 2=============================================== 3 4.. module:: logging.config 5 :synopsis: Configuration of the logging module. 6 7.. moduleauthor:: Vinay Sajip <vinay_sajip@red-dove.com> 8.. sectionauthor:: Vinay Sajip <vinay_sajip@red-dove.com> 9 10**Source code:** :source:`Lib/logging/config.py` 11 12.. sidebar:: Important 13 14 This page contains only reference information. For tutorials, 15 please see 16 17 * :ref:`Basic Tutorial <logging-basic-tutorial>` 18 * :ref:`Advanced Tutorial <logging-advanced-tutorial>` 19 * :ref:`Logging Cookbook <logging-cookbook>` 20 21-------------- 22 23This section describes the API for configuring the logging module. 24 25.. _logging-config-api: 26 27Configuration functions 28^^^^^^^^^^^^^^^^^^^^^^^ 29 30The following functions configure the logging module. They are located in the 31:mod:`logging.config` module. Their use is optional --- you can configure the 32logging module using these functions or by making calls to the main API (defined 33in :mod:`logging` itself) and defining handlers which are declared either in 34:mod:`logging` or :mod:`logging.handlers`. 35 36.. function:: dictConfig(config) 37 38 Takes the logging configuration from a dictionary. The contents of 39 this dictionary are described in :ref:`logging-config-dictschema` 40 below. 41 42 If an error is encountered during configuration, this function will 43 raise a :exc:`ValueError`, :exc:`TypeError`, :exc:`AttributeError` 44 or :exc:`ImportError` with a suitably descriptive message. The 45 following is a (possibly incomplete) list of conditions which will 46 raise an error: 47 48 * A ``level`` which is not a string or which is a string not 49 corresponding to an actual logging level. 50 * A ``propagate`` value which is not a boolean. 51 * An id which does not have a corresponding destination. 52 * A non-existent handler id found during an incremental call. 53 * An invalid logger name. 54 * Inability to resolve to an internal or external object. 55 56 Parsing is performed by the :class:`DictConfigurator` class, whose 57 constructor is passed the dictionary used for configuration, and 58 has a :meth:`configure` method. The :mod:`logging.config` module 59 has a callable attribute :attr:`dictConfigClass` 60 which is initially set to :class:`DictConfigurator`. 61 You can replace the value of :attr:`dictConfigClass` with a 62 suitable implementation of your own. 63 64 :func:`dictConfig` calls :attr:`dictConfigClass` passing 65 the specified dictionary, and then calls the :meth:`configure` method on 66 the returned object to put the configuration into effect:: 67 68 def dictConfig(config): 69 dictConfigClass(config).configure() 70 71 For example, a subclass of :class:`DictConfigurator` could call 72 ``DictConfigurator.__init__()`` in its own :meth:`__init__()`, then 73 set up custom prefixes which would be usable in the subsequent 74 :meth:`configure` call. :attr:`dictConfigClass` would be bound to 75 this new subclass, and then :func:`dictConfig` could be called exactly as 76 in the default, uncustomized state. 77 78 .. versionadded:: 3.2 79 80.. function:: fileConfig(fname, defaults=None, disable_existing_loggers=True, encoding=None) 81 82 Reads the logging configuration from a :mod:`configparser`\-format file. The 83 format of the file should be as described in 84 :ref:`logging-config-fileformat`. 85 This function can be called several times from an application, allowing an 86 end user to select from various pre-canned configurations (if the developer 87 provides a mechanism to present the choices and load the chosen 88 configuration). 89 90 :param fname: A filename, or a file-like object, or an instance derived 91 from :class:`~configparser.RawConfigParser`. If a 92 ``RawConfigParser``-derived instance is passed, it is used as 93 is. Otherwise, a :class:`~configparser.Configparser` is 94 instantiated, and the configuration read by it from the 95 object passed in ``fname``. If that has a :meth:`readline` 96 method, it is assumed to be a file-like object and read using 97 :meth:`~configparser.ConfigParser.read_file`; otherwise, 98 it is assumed to be a filename and passed to 99 :meth:`~configparser.ConfigParser.read`. 100 101 102 :param defaults: Defaults to be passed to the ConfigParser can be specified 103 in this argument. 104 105 :param disable_existing_loggers: If specified as ``False``, loggers which 106 exist when this call is made are left 107 enabled. The default is ``True`` because this 108 enables old behaviour in a 109 backward-compatible way. This behaviour is to 110 disable any existing non-root loggers unless 111 they or their ancestors are explicitly named 112 in the logging configuration. 113 114 :param encoding: The encoding used to open file when *fname* is filename. 115 116 .. versionchanged:: 3.4 117 An instance of a subclass of :class:`~configparser.RawConfigParser` is 118 now accepted as a value for ``fname``. This facilitates: 119 120 * Use of a configuration file where logging configuration is just part 121 of the overall application configuration. 122 * Use of a configuration read from a file, and then modified by the using 123 application (e.g. based on command-line parameters or other aspects 124 of the runtime environment) before being passed to ``fileConfig``. 125 126 .. versionadded:: 3.10 127 The *encoding* parameter is added. 128 129.. function:: listen(port=DEFAULT_LOGGING_CONFIG_PORT, verify=None) 130 131 Starts up a socket server on the specified port, and listens for new 132 configurations. If no port is specified, the module's default 133 :const:`DEFAULT_LOGGING_CONFIG_PORT` is used. Logging configurations will be 134 sent as a file suitable for processing by :func:`dictConfig` or 135 :func:`fileConfig`. Returns a :class:`~threading.Thread` instance on which 136 you can call :meth:`~threading.Thread.start` to start the server, and which 137 you can :meth:`~threading.Thread.join` when appropriate. To stop the server, 138 call :func:`stopListening`. 139 140 The ``verify`` argument, if specified, should be a callable which should 141 verify whether bytes received across the socket are valid and should be 142 processed. This could be done by encrypting and/or signing what is sent 143 across the socket, such that the ``verify`` callable can perform 144 signature verification and/or decryption. The ``verify`` callable is called 145 with a single argument - the bytes received across the socket - and should 146 return the bytes to be processed, or ``None`` to indicate that the bytes should 147 be discarded. The returned bytes could be the same as the passed in bytes 148 (e.g. when only verification is done), or they could be completely different 149 (perhaps if decryption were performed). 150 151 To send a configuration to the socket, read in the configuration file and 152 send it to the socket as a sequence of bytes preceded by a four-byte length 153 string packed in binary using ``struct.pack('>L', n)``. 154 155 .. _logging-eval-security: 156 157 .. note:: 158 159 Because portions of the configuration are passed through 160 :func:`eval`, use of this function may open its users to a security risk. 161 While the function only binds to a socket on ``localhost``, and so does 162 not accept connections from remote machines, there are scenarios where 163 untrusted code could be run under the account of the process which calls 164 :func:`listen`. Specifically, if the process calling :func:`listen` runs 165 on a multi-user machine where users cannot trust each other, then a 166 malicious user could arrange to run essentially arbitrary code in a 167 victim user's process, simply by connecting to the victim's 168 :func:`listen` socket and sending a configuration which runs whatever 169 code the attacker wants to have executed in the victim's process. This is 170 especially easy to do if the default port is used, but not hard even if a 171 different port is used. To avoid the risk of this happening, use the 172 ``verify`` argument to :func:`listen` to prevent unrecognised 173 configurations from being applied. 174 175 .. versionchanged:: 3.4 176 The ``verify`` argument was added. 177 178 .. note:: 179 180 If you want to send configurations to the listener which don't 181 disable existing loggers, you will need to use a JSON format for 182 the configuration, which will use :func:`dictConfig` for configuration. 183 This method allows you to specify ``disable_existing_loggers`` as 184 ``False`` in the configuration you send. 185 186 187.. function:: stopListening() 188 189 Stops the listening server which was created with a call to :func:`listen`. 190 This is typically called before calling :meth:`join` on the return value from 191 :func:`listen`. 192 193 194.. _logging-config-dictschema: 195 196Configuration dictionary schema 197^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 198 199Describing a logging configuration requires listing the various 200objects to create and the connections between them; for example, you 201may create a handler named 'console' and then say that the logger 202named 'startup' will send its messages to the 'console' handler. 203These objects aren't limited to those provided by the :mod:`logging` 204module because you might write your own formatter or handler class. 205The parameters to these classes may also need to include external 206objects such as ``sys.stderr``. The syntax for describing these 207objects and connections is defined in :ref:`logging-config-dict-connections` 208below. 209 210Dictionary Schema Details 211""""""""""""""""""""""""" 212 213The dictionary passed to :func:`dictConfig` must contain the following 214keys: 215 216* *version* - to be set to an integer value representing the schema 217 version. The only valid value at present is 1, but having this key 218 allows the schema to evolve while still preserving backwards 219 compatibility. 220 221All other keys are optional, but if present they will be interpreted 222as described below. In all cases below where a 'configuring dict' is 223mentioned, it will be checked for the special ``'()'`` key to see if a 224custom instantiation is required. If so, the mechanism described in 225:ref:`logging-config-dict-userdef` below is used to create an instance; 226otherwise, the context is used to determine what to instantiate. 227 228.. _logging-config-dictschema-formatters: 229 230* *formatters* - the corresponding value will be a dict in which each 231 key is a formatter id and each value is a dict describing how to 232 configure the corresponding :class:`~logging.Formatter` instance. 233 234 The configuring dict is searched for the following optional keys 235 which correspond to the arguments passed to create a 236 :class:`~logging.Formatter` object: 237 238 * ``format`` 239 * ``datefmt`` 240 * ``style`` 241 * ``validate`` (since version >=3.8) 242 243 An optional ``class`` key indicates the name of the formatter's 244 class (as a dotted module and class name). The instantiation 245 arguments are as for :class:`~logging.Formatter`, thus this key is 246 most useful for instantiating a customised subclass of 247 :class:`~logging.Formatter`. For example, the alternative class 248 might present exception tracebacks in an expanded or condensed 249 format. If your formatter requires different or extra configuration 250 keys, you should use :ref:`logging-config-dict-userdef`. 251 252* *filters* - the corresponding value will be a dict in which each key 253 is a filter id and each value is a dict describing how to configure 254 the corresponding Filter instance. 255 256 The configuring dict is searched for the key ``name`` (defaulting to the 257 empty string) and this is used to construct a :class:`logging.Filter` 258 instance. 259 260* *handlers* - the corresponding value will be a dict in which each 261 key is a handler id and each value is a dict describing how to 262 configure the corresponding Handler instance. 263 264 The configuring dict is searched for the following keys: 265 266 * ``class`` (mandatory). This is the fully qualified name of the 267 handler class. 268 269 * ``level`` (optional). The level of the handler. 270 271 * ``formatter`` (optional). The id of the formatter for this 272 handler. 273 274 * ``filters`` (optional). A list of ids of the filters for this 275 handler. 276 277 All *other* keys are passed through as keyword arguments to the 278 handler's constructor. For example, given the snippet: 279 280 .. code-block:: yaml 281 282 handlers: 283 console: 284 class : logging.StreamHandler 285 formatter: brief 286 level : INFO 287 filters: [allow_foo] 288 stream : ext://sys.stdout 289 file: 290 class : logging.handlers.RotatingFileHandler 291 formatter: precise 292 filename: logconfig.log 293 maxBytes: 1024 294 backupCount: 3 295 296 the handler with id ``console`` is instantiated as a 297 :class:`logging.StreamHandler`, using ``sys.stdout`` as the underlying 298 stream. The handler with id ``file`` is instantiated as a 299 :class:`logging.handlers.RotatingFileHandler` with the keyword arguments 300 ``filename='logconfig.log', maxBytes=1024, backupCount=3``. 301 302* *loggers* - the corresponding value will be a dict in which each key 303 is a logger name and each value is a dict describing how to 304 configure the corresponding Logger instance. 305 306 The configuring dict is searched for the following keys: 307 308 * ``level`` (optional). The level of the logger. 309 310 * ``propagate`` (optional). The propagation setting of the logger. 311 312 * ``filters`` (optional). A list of ids of the filters for this 313 logger. 314 315 * ``handlers`` (optional). A list of ids of the handlers for this 316 logger. 317 318 The specified loggers will be configured according to the level, 319 propagation, filters and handlers specified. 320 321* *root* - this will be the configuration for the root logger. 322 Processing of the configuration will be as for any logger, except 323 that the ``propagate`` setting will not be applicable. 324 325* *incremental* - whether the configuration is to be interpreted as 326 incremental to the existing configuration. This value defaults to 327 ``False``, which means that the specified configuration replaces the 328 existing configuration with the same semantics as used by the 329 existing :func:`fileConfig` API. 330 331 If the specified value is ``True``, the configuration is processed 332 as described in the section on :ref:`logging-config-dict-incremental`. 333 334* *disable_existing_loggers* - whether any existing non-root loggers are 335 to be disabled. This setting mirrors the parameter of the same name in 336 :func:`fileConfig`. If absent, this parameter defaults to ``True``. 337 This value is ignored if *incremental* is ``True``. 338 339.. _logging-config-dict-incremental: 340 341Incremental Configuration 342""""""""""""""""""""""""" 343 344It is difficult to provide complete flexibility for incremental 345configuration. For example, because objects such as filters 346and formatters are anonymous, once a configuration is set up, it is 347not possible to refer to such anonymous objects when augmenting a 348configuration. 349 350Furthermore, there is not a compelling case for arbitrarily altering 351the object graph of loggers, handlers, filters, formatters at 352run-time, once a configuration is set up; the verbosity of loggers and 353handlers can be controlled just by setting levels (and, in the case of 354loggers, propagation flags). Changing the object graph arbitrarily in 355a safe way is problematic in a multi-threaded environment; while not 356impossible, the benefits are not worth the complexity it adds to the 357implementation. 358 359Thus, when the ``incremental`` key of a configuration dict is present 360and is ``True``, the system will completely ignore any ``formatters`` and 361``filters`` entries, and process only the ``level`` 362settings in the ``handlers`` entries, and the ``level`` and 363``propagate`` settings in the ``loggers`` and ``root`` entries. 364 365Using a value in the configuration dict lets configurations to be sent 366over the wire as pickled dicts to a socket listener. Thus, the logging 367verbosity of a long-running application can be altered over time with 368no need to stop and restart the application. 369 370.. _logging-config-dict-connections: 371 372Object connections 373"""""""""""""""""" 374 375The schema describes a set of logging objects - loggers, 376handlers, formatters, filters - which are connected to each other in 377an object graph. Thus, the schema needs to represent connections 378between the objects. For example, say that, once configured, a 379particular logger has attached to it a particular handler. For the 380purposes of this discussion, we can say that the logger represents the 381source, and the handler the destination, of a connection between the 382two. Of course in the configured objects this is represented by the 383logger holding a reference to the handler. In the configuration dict, 384this is done by giving each destination object an id which identifies 385it unambiguously, and then using the id in the source object's 386configuration to indicate that a connection exists between the source 387and the destination object with that id. 388 389So, for example, consider the following YAML snippet: 390 391.. code-block:: yaml 392 393 formatters: 394 brief: 395 # configuration for formatter with id 'brief' goes here 396 precise: 397 # configuration for formatter with id 'precise' goes here 398 handlers: 399 h1: #This is an id 400 # configuration of handler with id 'h1' goes here 401 formatter: brief 402 h2: #This is another id 403 # configuration of handler with id 'h2' goes here 404 formatter: precise 405 loggers: 406 foo.bar.baz: 407 # other configuration for logger 'foo.bar.baz' 408 handlers: [h1, h2] 409 410(Note: YAML used here because it's a little more readable than the 411equivalent Python source form for the dictionary.) 412 413The ids for loggers are the logger names which would be used 414programmatically to obtain a reference to those loggers, e.g. 415``foo.bar.baz``. The ids for Formatters and Filters can be any string 416value (such as ``brief``, ``precise`` above) and they are transient, 417in that they are only meaningful for processing the configuration 418dictionary and used to determine connections between objects, and are 419not persisted anywhere when the configuration call is complete. 420 421The above snippet indicates that logger named ``foo.bar.baz`` should 422have two handlers attached to it, which are described by the handler 423ids ``h1`` and ``h2``. The formatter for ``h1`` is that described by id 424``brief``, and the formatter for ``h2`` is that described by id 425``precise``. 426 427 428.. _logging-config-dict-userdef: 429 430User-defined objects 431"""""""""""""""""""" 432 433The schema supports user-defined objects for handlers, filters and 434formatters. (Loggers do not need to have different types for 435different instances, so there is no support in this configuration 436schema for user-defined logger classes.) 437 438Objects to be configured are described by dictionaries 439which detail their configuration. In some places, the logging system 440will be able to infer from the context how an object is to be 441instantiated, but when a user-defined object is to be instantiated, 442the system will not know how to do this. In order to provide complete 443flexibility for user-defined object instantiation, the user needs 444to provide a 'factory' - a callable which is called with a 445configuration dictionary and which returns the instantiated object. 446This is signalled by an absolute import path to the factory being 447made available under the special key ``'()'``. Here's a concrete 448example: 449 450.. code-block:: yaml 451 452 formatters: 453 brief: 454 format: '%(message)s' 455 default: 456 format: '%(asctime)s %(levelname)-8s %(name)-15s %(message)s' 457 datefmt: '%Y-%m-%d %H:%M:%S' 458 custom: 459 (): my.package.customFormatterFactory 460 bar: baz 461 spam: 99.9 462 answer: 42 463 464The above YAML snippet defines three formatters. The first, with id 465``brief``, is a standard :class:`logging.Formatter` instance with the 466specified format string. The second, with id ``default``, has a 467longer format and also defines the time format explicitly, and will 468result in a :class:`logging.Formatter` initialized with those two format 469strings. Shown in Python source form, the ``brief`` and ``default`` 470formatters have configuration sub-dictionaries:: 471 472 { 473 'format' : '%(message)s' 474 } 475 476and:: 477 478 { 479 'format' : '%(asctime)s %(levelname)-8s %(name)-15s %(message)s', 480 'datefmt' : '%Y-%m-%d %H:%M:%S' 481 } 482 483respectively, and as these dictionaries do not contain the special key 484``'()'``, the instantiation is inferred from the context: as a result, 485standard :class:`logging.Formatter` instances are created. The 486configuration sub-dictionary for the third formatter, with id 487``custom``, is:: 488 489 { 490 '()' : 'my.package.customFormatterFactory', 491 'bar' : 'baz', 492 'spam' : 99.9, 493 'answer' : 42 494 } 495 496and this contains the special key ``'()'``, which means that 497user-defined instantiation is wanted. In this case, the specified 498factory callable will be used. If it is an actual callable it will be 499used directly - otherwise, if you specify a string (as in the example) 500the actual callable will be located using normal import mechanisms. 501The callable will be called with the **remaining** items in the 502configuration sub-dictionary as keyword arguments. In the above 503example, the formatter with id ``custom`` will be assumed to be 504returned by the call:: 505 506 my.package.customFormatterFactory(bar='baz', spam=99.9, answer=42) 507 508The key ``'()'`` has been used as the special key because it is not a 509valid keyword parameter name, and so will not clash with the names of 510the keyword arguments used in the call. The ``'()'`` also serves as a 511mnemonic that the corresponding value is a callable. 512 513 514.. _logging-config-dict-externalobj: 515 516Access to external objects 517"""""""""""""""""""""""""" 518 519There are times where a configuration needs to refer to objects 520external to the configuration, for example ``sys.stderr``. If the 521configuration dict is constructed using Python code, this is 522straightforward, but a problem arises when the configuration is 523provided via a text file (e.g. JSON, YAML). In a text file, there is 524no standard way to distinguish ``sys.stderr`` from the literal string 525``'sys.stderr'``. To facilitate this distinction, the configuration 526system looks for certain special prefixes in string values and 527treat them specially. For example, if the literal string 528``'ext://sys.stderr'`` is provided as a value in the configuration, 529then the ``ext://`` will be stripped off and the remainder of the 530value processed using normal import mechanisms. 531 532The handling of such prefixes is done in a way analogous to protocol 533handling: there is a generic mechanism to look for prefixes which 534match the regular expression ``^(?P<prefix>[a-z]+)://(?P<suffix>.*)$`` 535whereby, if the ``prefix`` is recognised, the ``suffix`` is processed 536in a prefix-dependent manner and the result of the processing replaces 537the string value. If the prefix is not recognised, then the string 538value will be left as-is. 539 540 541.. _logging-config-dict-internalobj: 542 543Access to internal objects 544"""""""""""""""""""""""""" 545 546As well as external objects, there is sometimes also a need to refer 547to objects in the configuration. This will be done implicitly by the 548configuration system for things that it knows about. For example, the 549string value ``'DEBUG'`` for a ``level`` in a logger or handler will 550automatically be converted to the value ``logging.DEBUG``, and the 551``handlers``, ``filters`` and ``formatter`` entries will take an 552object id and resolve to the appropriate destination object. 553 554However, a more generic mechanism is needed for user-defined 555objects which are not known to the :mod:`logging` module. For 556example, consider :class:`logging.handlers.MemoryHandler`, which takes 557a ``target`` argument which is another handler to delegate to. Since 558the system already knows about this class, then in the configuration, 559the given ``target`` just needs to be the object id of the relevant 560target handler, and the system will resolve to the handler from the 561id. If, however, a user defines a ``my.package.MyHandler`` which has 562an ``alternate`` handler, the configuration system would not know that 563the ``alternate`` referred to a handler. To cater for this, a generic 564resolution system allows the user to specify: 565 566.. code-block:: yaml 567 568 handlers: 569 file: 570 # configuration of file handler goes here 571 572 custom: 573 (): my.package.MyHandler 574 alternate: cfg://handlers.file 575 576The literal string ``'cfg://handlers.file'`` will be resolved in an 577analogous way to strings with the ``ext://`` prefix, but looking 578in the configuration itself rather than the import namespace. The 579mechanism allows access by dot or by index, in a similar way to 580that provided by ``str.format``. Thus, given the following snippet: 581 582.. code-block:: yaml 583 584 handlers: 585 email: 586 class: logging.handlers.SMTPHandler 587 mailhost: localhost 588 fromaddr: my_app@domain.tld 589 toaddrs: 590 - support_team@domain.tld 591 - dev_team@domain.tld 592 subject: Houston, we have a problem. 593 594in the configuration, the string ``'cfg://handlers'`` would resolve to 595the dict with key ``handlers``, the string ``'cfg://handlers.email`` 596would resolve to the dict with key ``email`` in the ``handlers`` dict, 597and so on. The string ``'cfg://handlers.email.toaddrs[1]`` would 598resolve to ``'dev_team@domain.tld'`` and the string 599``'cfg://handlers.email.toaddrs[0]'`` would resolve to the value 600``'support_team@domain.tld'``. The ``subject`` value could be accessed 601using either ``'cfg://handlers.email.subject'`` or, equivalently, 602``'cfg://handlers.email[subject]'``. The latter form only needs to be 603used if the key contains spaces or non-alphanumeric characters. If an 604index value consists only of decimal digits, access will be attempted 605using the corresponding integer value, falling back to the string 606value if needed. 607 608Given a string ``cfg://handlers.myhandler.mykey.123``, this will 609resolve to ``config_dict['handlers']['myhandler']['mykey']['123']``. 610If the string is specified as ``cfg://handlers.myhandler.mykey[123]``, 611the system will attempt to retrieve the value from 612``config_dict['handlers']['myhandler']['mykey'][123]``, and fall back 613to ``config_dict['handlers']['myhandler']['mykey']['123']`` if that 614fails. 615 616 617.. _logging-import-resolution: 618 619Import resolution and custom importers 620"""""""""""""""""""""""""""""""""""""" 621 622Import resolution, by default, uses the builtin :func:`__import__` function 623to do its importing. You may want to replace this with your own importing 624mechanism: if so, you can replace the :attr:`importer` attribute of the 625:class:`DictConfigurator` or its superclass, the 626:class:`BaseConfigurator` class. However, you need to be 627careful because of the way functions are accessed from classes via 628descriptors. If you are using a Python callable to do your imports, and you 629want to define it at class level rather than instance level, you need to wrap 630it with :func:`staticmethod`. For example:: 631 632 from importlib import import_module 633 from logging.config import BaseConfigurator 634 635 BaseConfigurator.importer = staticmethod(import_module) 636 637You don't need to wrap with :func:`staticmethod` if you're setting the import 638callable on a configurator *instance*. 639 640 641.. _logging-config-fileformat: 642 643Configuration file format 644^^^^^^^^^^^^^^^^^^^^^^^^^ 645 646The configuration file format understood by :func:`fileConfig` is based on 647:mod:`configparser` functionality. The file must contain sections called 648``[loggers]``, ``[handlers]`` and ``[formatters]`` which identify by name the 649entities of each type which are defined in the file. For each such entity, there 650is a separate section which identifies how that entity is configured. Thus, for 651a logger named ``log01`` in the ``[loggers]`` section, the relevant 652configuration details are held in a section ``[logger_log01]``. Similarly, a 653handler called ``hand01`` in the ``[handlers]`` section will have its 654configuration held in a section called ``[handler_hand01]``, while a formatter 655called ``form01`` in the ``[formatters]`` section will have its configuration 656specified in a section called ``[formatter_form01]``. The root logger 657configuration must be specified in a section called ``[logger_root]``. 658 659.. note:: 660 661 The :func:`fileConfig` API is older than the :func:`dictConfig` API and does 662 not provide functionality to cover certain aspects of logging. For example, 663 you cannot configure :class:`~logging.Filter` objects, which provide for 664 filtering of messages beyond simple integer levels, using :func:`fileConfig`. 665 If you need to have instances of :class:`~logging.Filter` in your logging 666 configuration, you will need to use :func:`dictConfig`. Note that future 667 enhancements to configuration functionality will be added to 668 :func:`dictConfig`, so it's worth considering transitioning to this newer 669 API when it's convenient to do so. 670 671Examples of these sections in the file are given below. 672 673.. code-block:: ini 674 675 [loggers] 676 keys=root,log02,log03,log04,log05,log06,log07 677 678 [handlers] 679 keys=hand01,hand02,hand03,hand04,hand05,hand06,hand07,hand08,hand09 680 681 [formatters] 682 keys=form01,form02,form03,form04,form05,form06,form07,form08,form09 683 684The root logger must specify a level and a list of handlers. An example of a 685root logger section is given below. 686 687.. code-block:: ini 688 689 [logger_root] 690 level=NOTSET 691 handlers=hand01 692 693The ``level`` entry can be one of ``DEBUG, INFO, WARNING, ERROR, CRITICAL`` or 694``NOTSET``. For the root logger only, ``NOTSET`` means that all messages will be 695logged. Level values are :func:`eval`\ uated in the context of the ``logging`` 696package's namespace. 697 698The ``handlers`` entry is a comma-separated list of handler names, which must 699appear in the ``[handlers]`` section. These names must appear in the 700``[handlers]`` section and have corresponding sections in the configuration 701file. 702 703For loggers other than the root logger, some additional information is required. 704This is illustrated by the following example. 705 706.. code-block:: ini 707 708 [logger_parser] 709 level=DEBUG 710 handlers=hand01 711 propagate=1 712 qualname=compiler.parser 713 714The ``level`` and ``handlers`` entries are interpreted as for the root logger, 715except that if a non-root logger's level is specified as ``NOTSET``, the system 716consults loggers higher up the hierarchy to determine the effective level of the 717logger. The ``propagate`` entry is set to 1 to indicate that messages must 718propagate to handlers higher up the logger hierarchy from this logger, or 0 to 719indicate that messages are **not** propagated to handlers up the hierarchy. The 720``qualname`` entry is the hierarchical channel name of the logger, that is to 721say the name used by the application to get the logger. 722 723Sections which specify handler configuration are exemplified by the following. 724 725.. code-block:: ini 726 727 [handler_hand01] 728 class=StreamHandler 729 level=NOTSET 730 formatter=form01 731 args=(sys.stdout,) 732 733The ``class`` entry indicates the handler's class (as determined by :func:`eval` 734in the ``logging`` package's namespace). The ``level`` is interpreted as for 735loggers, and ``NOTSET`` is taken to mean 'log everything'. 736 737The ``formatter`` entry indicates the key name of the formatter for this 738handler. If blank, a default formatter (``logging._defaultFormatter``) is used. 739If a name is specified, it must appear in the ``[formatters]`` section and have 740a corresponding section in the configuration file. 741 742The ``args`` entry, when :func:`eval`\ uated in the context of the ``logging`` 743package's namespace, is the list of arguments to the constructor for the handler 744class. Refer to the constructors for the relevant handlers, or to the examples 745below, to see how typical entries are constructed. If not provided, it defaults 746to ``()``. 747 748The optional ``kwargs`` entry, when :func:`eval`\ uated in the context of the 749``logging`` package's namespace, is the keyword argument dict to the constructor 750for the handler class. If not provided, it defaults to ``{}``. 751 752.. code-block:: ini 753 754 [handler_hand02] 755 class=FileHandler 756 level=DEBUG 757 formatter=form02 758 args=('python.log', 'w') 759 760 [handler_hand03] 761 class=handlers.SocketHandler 762 level=INFO 763 formatter=form03 764 args=('localhost', handlers.DEFAULT_TCP_LOGGING_PORT) 765 766 [handler_hand04] 767 class=handlers.DatagramHandler 768 level=WARN 769 formatter=form04 770 args=('localhost', handlers.DEFAULT_UDP_LOGGING_PORT) 771 772 [handler_hand05] 773 class=handlers.SysLogHandler 774 level=ERROR 775 formatter=form05 776 args=(('localhost', handlers.SYSLOG_UDP_PORT), handlers.SysLogHandler.LOG_USER) 777 778 [handler_hand06] 779 class=handlers.NTEventLogHandler 780 level=CRITICAL 781 formatter=form06 782 args=('Python Application', '', 'Application') 783 784 [handler_hand07] 785 class=handlers.SMTPHandler 786 level=WARN 787 formatter=form07 788 args=('localhost', 'from@abc', ['user1@abc', 'user2@xyz'], 'Logger Subject') 789 kwargs={'timeout': 10.0} 790 791 [handler_hand08] 792 class=handlers.MemoryHandler 793 level=NOTSET 794 formatter=form08 795 target= 796 args=(10, ERROR) 797 798 [handler_hand09] 799 class=handlers.HTTPHandler 800 level=NOTSET 801 formatter=form09 802 args=('localhost:9022', '/log', 'GET') 803 kwargs={'secure': True} 804 805Sections which specify formatter configuration are typified by the following. 806 807.. code-block:: ini 808 809 [formatter_form01] 810 format=F1 %(asctime)s %(levelname)s %(message)s 811 datefmt= 812 style='%' 813 validate=True 814 class=logging.Formatter 815 816The arguments for the formatter configuration are the same as the keys 817in the dictionary schema :ref:`formatters section 818<logging-config-dictschema-formatters>`. 819 820.. note:: 821 822 Due to the use of :func:`eval` as described above, there are 823 potential security risks which result from using the :func:`listen` to send 824 and receive configurations via sockets. The risks are limited to where 825 multiple users with no mutual trust run code on the same machine; see the 826 :func:`listen` documentation for more information. 827 828.. seealso:: 829 830 Module :mod:`logging` 831 API reference for the logging module. 832 833 Module :mod:`logging.handlers` 834 Useful handlers included with the logging module. 835