How To Change Log Into Exponential Form
Basic Logging Tutorial¶
Logging is a means of tracking events that happen when some software runs. The software's programmer adds logging calls to their code to point that certain events have occurred. An event is described by a descriptive message which tin optionally contain variable data (i.e. data that is potentially dissimilar for each occurrence of the event). Events also accept an importance which the programmer ascribes to the consequence; the importance can also be called the level or severity.
When to use logging¶
Logging provides a set of convenience functions for simple logging usage. These are debug() , info() , warning() , error() and critical() . To determine when to employ logging, see the table beneath, which states, for each of a fix of common tasks, the best tool to use for it.
| Task you want to perform | The best tool for the task |
|---|---|
| Brandish console output for ordinary usage of a control line script or program | |
| Study events that occur during normal operation of a program (e.one thousand. for status monitoring or mistake investigation) | |
| Issue a alert regarding a item runtime consequence | |
| Report an error regarding a particular runtime outcome | Enhance an exception |
| Study suppression of an fault without raising an exception (e.g. mistake handler in a long-running server process) | |
The logging functions are named afterward the level or severity of the events they are used to runway. The standard levels and their applicability are described below (in increasing lodge of severity):
| Level | When information technology's used |
|---|---|
| | Detailed information, typically of involvement just when diagnosing problems. |
| | Confirmation that things are working as expected. |
| | An indication that something unexpected happened, or indicative of some problem in the near time to come (e.1000. 'disk infinite low'). The software is still working as expected. |
| | Due to a more serious problem, the software has non been able to perform some function. |
| | A serious fault, indicating that the program itself may be unable to go along running. |
The default level is Warning , which means that simply events of this level and in a higher place volition be tracked, unless the logging package is configured to do otherwise.
Events that are tracked tin be handled in different ways. The simplest way of handling tracked events is to impress them to the console. Another mutual way is to write them to a deejay file.
A unproblematic example¶
A very elementary example is:
import logging logging . warning ( 'Watch out!' ) # volition print a message to the panel logging . info ( 'I told you and then' ) # will not impress anything If you type these lines into a script and run information technology, you'll see:
printed out on the console. The INFO bulletin doesn't appear considering the default level is WARNING . The printed message includes the indication of the level and the description of the issue provided in the logging call, i.e. 'Watch out!'. Don't worry about the 'root' role for now: it will exist explained after. The actual output tin be formatted quite flexibly if y'all need that; formatting options volition also exist explained later.
Logging to a file¶
A very common state of affairs is that of recording logging events in a file, so permit's look at that side by side. Be certain to effort the following in a newly-started Python interpreter, and don't just go along from the session described above:
import logging logging . basicConfig ( filename = 'case.log' , encoding = 'utf-8' , level = logging . DEBUG ) logging . debug ( 'This message should go to the log file' ) logging . info ( 'Then should this' ) logging . warning ( 'And this, as well' ) logging . error ( 'And non-ASCII stuff, likewise, like Øresund and Malmö' ) Inverse in version 3.nine: The encoding argument was added. In earlier Python versions, or if not specified, the encoding used is the default value used by open() . While not shown in the above instance, an errors argument can besides now be passed, which determines how encoding errors are handled. For available values and the default, run into the documentation for open() .
And now if we open the file and wait at what we have, we should observe the log messages:
DEBUG:root:This message should go to the log file INFO:root:So should this Warning:root:And this, too Mistake:root:And non-ASCII stuff, too, like Øresund and Malmö This example also shows how yous can gear up the logging level which acts every bit the threshold for tracking. In this case, because we set the threshold to DEBUG , all of the messages were printed.
If you want to set the logging level from a command-line pick such as:
and you have the value of the parameter passed for --log in some variable loglevel, you can use:
getattr ( logging , loglevel . upper ()) to get the value which you'll pass to basicConfig() via the level argument. Y'all may want to fault check whatever user input value, perhaps as in the following example:
# bold loglevel is bound to the string value obtained from the # command line argument. Convert to upper example to allow the user to # specify --log=DEBUG or --log=debug numeric_level = getattr ( logging , loglevel . upper (), None ) if not isinstance ( numeric_level , int ): raise ValueError ( 'Invalid log level: %s ' % loglevel ) logging . basicConfig ( level = numeric_level , ... ) The call to basicConfig() should come before whatsoever calls to debug() , info() etc. Every bit information technology's intended as a one-off unproblematic configuration facility, only the first telephone call will really do annihilation: subsequent calls are effectively no-ops.
If you run the higher up script several times, the letters from successive runs are appended to the file example.log. If yous desire each run to start afresh, not remembering the letters from earlier runs, you can specify the filemode argument, by changing the call in the in a higher place example to:
logging . basicConfig ( filename = 'example.log' , filemode = 'w' , level = logging . DEBUG ) The output will be the same as before, but the log file is no longer appended to, and so the messages from earlier runs are lost.
Logging from multiple modules¶
If your program consists of multiple modules, hither's an example of how y'all could organize logging in information technology:
# myapp.py import logging import mylib def main (): logging . basicConfig ( filename = 'myapp.log' , level = logging . INFO ) logging . info ( 'Started' ) mylib . do_something () logging . info ( 'Finished' ) if __name__ == '__main__' : main () # mylib.py import logging def do_something (): logging . info ( 'Doing something' ) If you run myapp.py, yous should see this in myapp.log:
INFO:root:Started INFO:root:Doing something INFO:root:Finished which is hopefully what you were expecting to see. Yous tin can generalize this to multiple modules, using the design in mylib.py. Notation that for this simple usage pattern, you won't know, by looking in the log file, where in your application your letters came from, apart from looking at the event description. If you want to track the location of your messages, you'll need to refer to the documentation beyond the tutorial level – see Advanced Logging Tutorial.
Logging variable information¶
To log variable data, utilize a format string for the event description message and append the variable data as arguments. For example:
import logging logging . alert ( ' %s earlier y'all %southward ' , 'Expect' , 'leap!' ) will display:
Alarm:root:Wait before you leap! As you tin can run into, merging of variable data into the event description bulletin uses the erstwhile, %-style of string formatting. This is for backwards compatibility: the logging package pre-dates newer formatting options such every bit str.format() and string.Template . These newer formatting options are supported, only exploring them is outside the scope of this tutorial: see Using particular formatting styles throughout your application for more information.
Changing the format of displayed messages¶
To change the format which is used to display letters, you need to specify the format you want to apply:
import logging logging . basicConfig ( format = ' %(levelname)southward : %(message)s ' , level = logging . DEBUG ) logging . debug ( 'This message should appear on the console' ) logging . info ( 'So should this' ) logging . warning ( 'And this, besides' ) which would print:
DEBUG:This message should appear on the console INFO:And so should this Alert:And this, too Observe that the 'root' which appeared in earlier examples has disappeared. For a total set of things that tin can announced in format strings, y'all tin refer to the documentation for LogRecord attributes, but for simple usage, you lot but need the levelname (severity), message (event description, including variable data) and maybe to display when the issue occurred. This is described in the next section.
Displaying the date/time in letters¶
To brandish the date and time of an event, yous would place '%(asctime)due south' in your format string:
import logging logging . basicConfig ( format = ' %(asctime)s %(message)s ' ) logging . alert ( 'is when this event was logged.' ) which should impress something similar this:
2010-12-12 11:41:42,612 is when this outcome was logged. The default format for appointment/time display (shown to a higher place) is like ISO8601 or RFC 3339. If you demand more command over the formatting of the engagement/time, provide a datefmt argument to basicConfig , as in this example:
import logging logging . basicConfig ( format = ' %(asctime)s %(message)southward ' , datefmt = '%grand/ %d /%Y %I:%1000:%S %p' ) logging . warning ( 'is when this event was logged.' ) which would display something similar this:
12/12/2010 xi:46:36 AM is when this event was logged. The format of the datefmt argument is the same as supported by time.strftime() .
Adjacent Steps¶
That concludes the basic tutorial. It should be enough to get you up and running with logging. There'southward a lot more that the logging package offers, but to get the best out of it, you'll demand to invest a piffling more of your time in reading the post-obit sections. If you lot're gear up for that, grab some of your favourite beverage and comport on.
If your logging needs are uncomplicated, and then use the higher up examples to comprise logging into your own scripts, and if you lot come across problems or don't understand something, please post a question on the comp.lang.python Usenet group (available at https://groups.google.com/forum/#!forum/comp.lang.python) and you should receive help before also long.
Still here? You can carry on reading the next few sections, which provide a slightly more than avant-garde/in-depth tutorial than the bones one above. Later on that, you tin take a look at the Logging Cookbook.
Advanced Logging Tutorial¶
The logging library takes a modular approach and offers several categories of components: loggers, handlers, filters, and formatters.
-
Loggers expose the interface that application code directly uses.
-
Handlers ship the log records (created past loggers) to the appropriate destination.
-
Filters provide a finer grained facility for determining which log records to output.
-
Formatters specify the layout of log records in the final output.
Log outcome information is passed between loggers, handlers, filters and formatters in a LogRecord instance.
Logging is performed by calling methods on instances of the Logger form (future called loggers). Each instance has a name, and they are conceptually arranged in a namespace hierarchy using dots (periods) as separators. For example, a logger named 'scan' is the parent of loggers 'scan.text', 'scan.html' and 'scan.pdf'. Logger names can be anything yous want, and point the area of an application in which a logged bulletin originates.
A skilful convention to use when naming loggers is to apply a module-level logger, in each module which uses logging, named every bit follows:
logger = logging . getLogger ( __name__ ) This means that logger names runway the packet/module hierarchy, and it's intuitively obvious where events are logged just from the logger name.
The root of the bureaucracy of loggers is called the root logger. That's the logger used by the functions debug() , info() , warning() , error() and critical() , which simply phone call the aforementioned-named method of the root logger. The functions and the methods take the aforementioned signatures. The root logger'south name is printed every bit 'root' in the logged output.
It is, of form, possible to log messages to different destinations. Support is included in the bundle for writing log messages to files, HTTP Go/POST locations, email via SMTP, generic sockets, queues, or Os-specific logging mechanisms such as syslog or the Windows NT event log. Destinations are served by handler classes. Yous tin create your ain log destination course if you have special requirements not met past any of the built-in handler classes.
By default, no destination is set up for any logging messages. You tin can specify a destination (such every bit console or file) past using basicConfig() equally in the tutorial examples. If you lot call the functions debug() , info() , warning() , error() and critical() , they volition check to see if no destination is set; and if 1 is not prepare, they will prepare a destination of the panel ( sys.stderr ) and a default format for the displayed bulletin before delegating to the root logger to do the actual message output.
The default format fix by basicConfig() for messages is:
severity:logger name:bulletin Y'all can change this by passing a format string to basicConfig() with the format keyword argument. For all options regarding how a format string is synthetic, come across Formatter Objects.
Logging Flow¶
The flow of log event information in loggers and handlers is illustrated in the following diagram.
Loggers¶
Logger objects have a threefold chore. First, they expose several methods to application code then that applications tin can log messages at runtime. 2nd, logger objects determine which log letters to deed upon based upon severity (the default filtering facility) or filter objects. 3rd, logger objects pass along relevant log messages to all interested log handlers.
The most widely used methods on logger objects autumn into two categories: configuration and message sending.
These are the most common configuration methods:
-
Logger.setLevel()specifies the everyman-severity log message a logger will handle, where debug is the lowest built-in severity level and critical is the highest congenital-in severity. For case, if the severity level is INFO, the logger will handle only INFO, WARNING, ERROR, and Critical messages and will ignore DEBUG messages. -
Logger.addHandler()andLogger.removeHandler()add and remove handler objects from the logger object. Handlers are covered in more particular in Handlers. -
Logger.addFilter()andLogger.removeFilter()add together and remove filter objects from the logger object. Filters are covered in more than detail in Filter Objects.
Y'all don't need to always phone call these methods on every logger you create. Run across the concluding two paragraphs in this department.
With the logger object configured, the following methods create log messages:
-
Logger.debug(),Logger.info(),Logger.warning(),Logger.fault(), andLogger.critical()all create log records with a message and a level that corresponds to their corresponding method names. The message is actually a format cord, which may incorporate the standard string substitution syntax of%s,%d,%f, then on. The rest of their arguments is a list of objects that correspond with the substitution fields in the message. With regard to**kwargs, the logging methods care only most a keyword ofexc_infoand apply information technology to determine whether to log exception data. -
Logger.exception()creates a log bulletin similar toLogger.fault(). The departure is thatLogger.exception()dumps a stack trace along with information technology. Call this method only from an exception handler. -
Logger.log()takes a log level as an explicit argument. This is a little more verbose for logging messages than using the log level convenience methods listed above, simply this is how to log at custom log levels.
getLogger() returns a reference to a logger example with the specified name if information technology is provided, or root if not. The names are catamenia-separated hierarchical structures. Multiple calls to getLogger() with the same name volition return a reference to the same logger object. Loggers that are further down in the hierarchical listing are children of loggers college upwards in the list. For example, given a logger with a proper name of foo , loggers with names of foo.bar , foo.bar.baz , and foo.bam are all descendants of foo .
Loggers have a concept of effective level. If a level is not explicitly set on a logger, the level of its parent is used instead as its effective level. If the parent has no explicit level prepare, its parent is examined, and so on - all ancestors are searched until an explicitly set level is found. The root logger always has an explicit level set ( Alarm by default). When deciding whether to procedure an consequence, the effective level of the logger is used to determine whether the event is passed to the logger's handlers.
Child loggers propagate messages up to the handlers associated with their ancestor loggers. Considering of this, information technology is unnecessary to ascertain and configure handlers for all the loggers an application uses. Information technology is sufficient to configure handlers for a peak-level logger and create child loggers as needed. (You tin, however, turn off propagation by setting the propagate aspect of a logger to False .)
Handlers¶
Handler objects are responsible for dispatching the appropriate log messages (based on the log messages' severity) to the handler'due south specified destination. Logger objects tin add cipher or more handler objects to themselves with an addHandler() method. Every bit an example scenario, an application may desire to send all log letters to a log file, all log messages of error or college to stdout, and all messages of critical to an email address. This scenario requires three private handlers where each handler is responsible for sending messages of a specific severity to a specific location.
The standard library includes quite a few handler types (see Useful Handlers); the tutorials use mainly StreamHandler and FileHandler in its examples.
At that place are very few methods in a handler for awarding developers to concern themselves with. The but handler methods that seem relevant for application developers who are using the built-in handler objects (that is, not creating custom handlers) are the following configuration methods:
-
The
setLevel()method, but as in logger objects, specifies the lowest severity that will be dispatched to the appropriate destination. Why are at that place iisetLevel()methods? The level ready in the logger determines which severity of messages it will pass to its handlers. The level set in each handler determines which messages that handler volition send on. -
setFormatter()selects a Formatter object for this handler to employ. -
addFilter()andremoveFilter()respectively configure and deconfigure filter objects on handlers.
Awarding code should not directly instantiate and utilize instances of Handler . Instead, the Handler form is a base class that defines the interface that all handlers should have and establishes some default beliefs that child classes tin can use (or override).
Formatters¶
Formatter objects configure the final order, structure, and contents of the log message. Dissimilar the base of operations logging.Handler class, awarding code may instantiate formatter classes, although you could likely bracket the formatter if your application needs special behavior. The constructor takes three optional arguments – a message format string, a appointment format string and a style indicator.
-
logging.Formatter.__init__( fmt = None , datefmt = None , style = '%' )¶
If there is no message format string, the default is to utilize the raw message. If there is no date format string, the default appointment format is:
with the milliseconds tacked on at the end. The mode is one of %, '{' or '$'. If ane of these is non specified, then '%' will be used.
If the style is '%', the message format string uses %(<lexicon key>)s styled string exchange; the possible keys are documented in LogRecord attributes. If the way is '{', the message format string is assumed to be compatible with str.format() (using keyword arguments), while if the fashion is '$' and so the message format string should arrange to what is expected past string.Template.substitute() .
Changed in version three.2: Added the fashion parameter.
The following message format string will log the time in a man-readable format, the severity of the bulletin, and the contents of the message, in that club:
' %(asctime)s - %(levelname)s - %(message)southward ' Formatters use a user-configurable function to convert the creation time of a record to a tuple. Past default, time.localtime() is used; to alter this for a item formatter case, gear up the converter attribute of the example to a function with the aforementioned signature as time.localtime() or time.gmtime() . To change it for all formatters, for example if you want all logging times to be shown in GMT, set the converter attribute in the Formatter class (to time.gmtime for GMT display).
Configuring Logging¶
Programmers can configure logging in three ways:
-
Creating loggers, handlers, and formatters explicitly using Python code that calls the configuration methods listed in a higher place.
-
Creating a logging config file and reading it using the
fileConfig()function. -
Creating a lexicon of configuration information and passing it to the
dictConfig()function.
For the reference documentation on the last two options, meet Configuration functions. The post-obit case configures a very simple logger, a panel handler, and a simple formatter using Python code:
import logging # create logger logger = logging . getLogger ( 'simple_example' ) logger . setLevel ( logging . DEBUG ) # create console handler and set level to debug ch = logging . StreamHandler () ch . setLevel ( logging . DEBUG ) # create formatter formatter = logging . Formatter ( ' %(asctime)s - %(proper name)south - %(levelname)s - %(message)s ' ) # add formatter to ch ch . setFormatter ( formatter ) # add ch to logger logger . addHandler ( ch ) # 'application' lawmaking logger . debug ( 'debug message' ) logger . info ( 'info message' ) logger . warning ( 'warn message' ) logger . error ( 'fault message' ) logger . disquisitional ( 'critical message' ) Running this module from the control line produces the following output:
$ python simple_logging_module.py 2005-03-xix 15:x:26,618 - simple_example - DEBUG - debug message 2005-03-19 15:ten:26,620 - simple_example - INFO - info message 2005-03-nineteen 15:10:26,695 - simple_example - WARNING - warn message 2005-03-nineteen 15:x:26,697 - simple_example - Fault - mistake message 2005-03-19 xv:ten:26,773 - simple_example - Disquisitional - critical message The post-obit Python module creates a logger, handler, and formatter nearly identical to those in the example listed above, with the but difference beingness the names of the objects:
import logging import logging.config logging . config . fileConfig ( 'logging.conf' ) # create logger logger = logging . getLogger ( 'simpleExample' ) # 'application' lawmaking logger . debug ( 'debug bulletin' ) logger . info ( 'info message' ) logger . warning ( 'warn bulletin' ) logger . fault ( 'error message' ) logger . disquisitional ( 'disquisitional message' ) Here is the logging.conf file:
[loggers] keys = root,simpleExample [handlers] keys = consoleHandler [formatters] keys = simpleFormatter [logger_root] level = DEBUG handlers = consoleHandler [logger_simpleExample] level = DEBUG handlers = consoleHandler qualname = simpleExample propagate = 0 [handler_consoleHandler] class = StreamHandler level = DEBUG formatter = simpleFormatter args = (sys.stdout,) [formatter_simpleFormatter] format = %(asctime)southward - %(name)s - %(levelname)south - %(bulletin)s The output is nigh identical to that of the non-config-file-based example:
$ python simple_logging_config.py 2005-03-19 15:38:55,977 - simpleExample - DEBUG - debug message 2005-03-19 fifteen:38:55,979 - simpleExample - INFO - info message 2005-03-19 15:38:56,054 - simpleExample - WARNING - warn message 2005-03-xix 15:38:56,055 - simpleExample - Error - error message 2005-03-xix 15:38:56,130 - simpleExample - CRITICAL - critical message Y'all tin come across that the config file approach has a few advantages over the Python code approach, mainly separation of configuration and code and the ability of noncoders to easily alter the logging properties.
Warning
The fileConfig() role takes a default parameter, disable_existing_loggers , which defaults to Truthful for reasons of backward compatibility. This may or may not be what you want, since it will crusade any non-root loggers existing before the fileConfig() call to exist disabled unless they (or an ancestor) are explicitly named in the configuration. Please refer to the reference documentation for more information, and specify False for this parameter if y'all wish.
The lexicon passed to dictConfig() can also specify a Boolean value with cardinal disable_existing_loggers , which if not specified explicitly in the lexicon also defaults to being interpreted as True . This leads to the logger-disabling behaviour described above, which may not be what you want - in which case, provide the key explicitly with a value of False .
Note that the course names referenced in config files demand to be either relative to the logging module, or absolute values which can be resolved using normal import mechanisms. Thus, you could use either WatchedFileHandler (relative to the logging module) or mypackage.mymodule.MyHandler (for a grade defined in bundle mypackage and module mymodule , where mypackage is available on the Python import path).
In Python 3.ii, a new means of configuring logging has been introduced, using dictionaries to agree configuration data. This provides a superset of the functionality of the config-file-based arroyo outlined above, and is the recommended configuration method for new applications and deployments. Because a Python dictionary is used to concur configuration information, and since you can populate that lexicon using different ways, you accept more options for configuration. For case, yous can utilize a configuration file in JSON format, or, if you accept admission to YAML processing functionality, a file in YAML format, to populate the configuration dictionary. Or, of grade, you can construct the dictionary in Python code, receive information technology in pickled class over a socket, or apply any approach makes sense for your application.
Here'due south an example of the same configuration as in a higher place, in YAML format for the new lexicon-based approach:
version : 1 formatters : uncomplicated : format : '%(asctime)s - %(name)s - %(levelname)s - %(message)s' handlers : console : class : logging.StreamHandler level : DEBUG formatter : simple stream : ext://sys.stdout loggers : simpleExample : level : DEBUG handlers : [ console ] propagate : no root : level : DEBUG handlers : [ panel ] For more data about logging using a lexicon, see Configuration functions.
What happens if no configuration is provided¶
If no logging configuration is provided, it is possible to have a situation where a logging event needs to be output, merely no handlers can be institute to output the event. The behaviour of the logging bundle in these circumstances is dependent on the Python version.
For versions of Python prior to 3.2, the behaviour is as follows:
-
If logging.raiseExceptions is
Faux(production mode), the consequence is silently dropped. -
If logging.raiseExceptions is
True(evolution mode), a bulletin 'No handlers could be found for logger Ten.Y.Z' is printed in one case.
In Python three.two and after, the behaviour is as follows:
-
The issue is output using a 'handler of last resort', stored in
logging.lastResort. This internal handler is not associated with whatever logger, and acts like aStreamHandlerwhich writes the event description bulletin to the current value ofsys.stderr(therefore respecting any redirections which may be in effect). No formatting is done on the message - just the bare event description message is printed. The handler's level is set toAlarm, so all events at this and greater severities will exist output.
To obtain the pre-3.2 behaviour, logging.lastResort can be set up to None .
Configuring Logging for a Library¶
When developing a library which uses logging, you should accept intendance to document how the library uses logging - for instance, the names of loggers used. Some consideration too needs to exist given to its logging configuration. If the using application does not employ logging, and library code makes logging calls, and then (equally described in the previous section) events of severity WARNING and greater will be printed to sys.stderr . This is regarded every bit the best default behaviour.
If for some reason you don't want these messages printed in the absenteeism of any logging configuration, you can attach a do-naught handler to the height-level logger for your library. This avoids the message existence printed, since a handler volition ever be constitute for the library's events: it just doesn't produce any output. If the library user configures logging for application utilize, presumably that configuration volition add some handlers, and if levels are suitably configured and then logging calls fabricated in library code will send output to those handlers, as normal.
A do-nothing handler is included in the logging package: NullHandler (since Python 3.i). An instance of this handler could exist added to the peak-level logger of the logging namespace used by the library (if yous want to prevent your library's logged events being output to sys.stderr in the absence of logging configuration). If all logging by a library foo is washed using loggers with names matching 'foo.x', 'foo.x.y', etc. and then the code:
import logging logging . getLogger ( 'foo' ) . addHandler ( logging . NullHandler ()) should have the desired effect. If an organisation produces a number of libraries, and so the logger name specified can be 'orgname.foo' rather than only 'foo'.
Note
Information technology is strongly advised that y'all do non add any handlers other than NullHandler to your library's loggers. This is because the configuration of handlers is the prerogative of the application developer who uses your library. The application developer knows their target audience and what handlers are about appropriate for their application: if you add handlers 'nether the hood', you might well interfere with their ability to carry out unit tests and deliver logs which adjust their requirements.
Logging Levels¶
The numeric values of logging levels are given in the following table. These are primarily of interest if you want to define your own levels, and need them to have specific values relative to the predefined levels. If y'all ascertain a level with the same numeric value, it overwrites the predefined value; the predefined name is lost.
| Level | Numeric value |
|---|---|
| | 50 |
| | 40 |
| | 30 |
| | 20 |
| | 10 |
| | 0 |
Levels can too exist associated with loggers, being set either past the developer or through loading a saved logging configuration. When a logging method is called on a logger, the logger compares its ain level with the level associated with the method call. If the logger's level is higher than the method call's, no logging message is actually generated. This is the basic mechanism controlling the verbosity of logging output.
Logging messages are encoded as instances of the LogRecord course. When a logger decides to actually log an event, a LogRecord instance is created from the logging message.
Logging messages are subjected to a dispatch mechanism through the utilise of handlers, which are instances of subclasses of the Handler form. Handlers are responsible for ensuring that a logged message (in the form of a LogRecord ) ends upwardly in a detail location (or gear up of locations) which is useful for the target audience for that message (such as finish users, support desk staff, system administrators, developers). Handlers are passed LogRecord instances intended for particular destinations. Each logger tin can take null, one or more handlers associated with information technology (via the addHandler() method of Logger ). In addition to any handlers straight associated with a logger, all handlers associated with all ancestors of the logger are called to dispatch the message (unless the propagate flag for a logger is prepare to a false value, at which bespeak the passing to ancestor handlers stops).
Just as for loggers, handlers can accept levels associated with them. A handler's level acts equally a filter in the same way as a logger's level does. If a handler decides to really acceleration an outcome, the emit() method is used to ship the message to its destination. Most user-defined subclasses of Handler volition need to override this emit() .
Custom Levels¶
Defining your own levels is possible, but should not exist necessary, equally the existing levels accept been chosen on the basis of practical experience. Yet, if yous are convinced that yous need custom levels, great intendance should be exercised when doing this, and it is possibly a very bad idea to ascertain custom levels if you are developing a library. That's because if multiple library authors all ascertain their ain custom levels, in that location is a chance that the logging output from such multiple libraries used together volition be difficult for the using programmer to control and/or interpret, because a given numeric value might mean unlike things for different libraries.
Useful Handlers¶
In addition to the base Handler class, many useful subclasses are provided:
-
StreamHandlerinstances send messages to streams (file-similar objects). -
FileHandlerinstances send letters to disk files. -
BaseRotatingHandleris the base of operations class for handlers that rotate log files at a certain signal. It is not meant to exist instantiated direct. Instead, useRotatingFileHandlerorTimedRotatingFileHandler. -
RotatingFileHandlerinstances send messages to disk files, with support for maximum log file sizes and log file rotation. -
TimedRotatingFileHandlerinstances send messages to disk files, rotating the log file at sure timed intervals. -
SocketHandlerinstances transport messages to TCP/IP sockets. Since three.4, Unix domain sockets are also supported. -
DatagramHandlerinstances ship messages to UDP sockets. Since 3.4, Unix domain sockets are also supported. -
SMTPHandlerinstances send messages to a designated email accost. -
SysLogHandlerinstances send letters to a Unix syslog daemon, possibly on a remote machine. -
NTEventLogHandlerinstances send letters to a Windows NT/2000/XP event log. -
MemoryHandlerinstances send messages to a buffer in memory, which is flushed whenever specific criteria are met. -
HTTPHandlerinstances send letters to an HTTP server using eitherGetorPostsemantics. -
WatchedFileHandlerinstances scout the file they are logging to. If the file changes, it is airtight and reopened using the file name. This handler is just useful on Unix-like systems; Windows does not back up the underlying machinery used. -
QueueHandlerinstances send messages to a queue, such as those implemented in thequeueormultiprocessingmodules. -
NullHandlerinstances practise naught with error messages. They are used by library developers who want to use logging, but want to avert the 'No handlers could exist institute for logger XXX' message which can be displayed if the library user has non configured logging. See Configuring Logging for a Library for more data.
The NullHandler , StreamHandler and FileHandler classes are divers in the core logging package. The other handlers are defined in a sub-module, logging.handlers . (There is also another sub-module, logging.config , for configuration functionality.)
Logged messages are formatted for presentation through instances of the Formatter course. They are initialized with a format string suitable for employ with the % operator and a dictionary.
For formatting multiple messages in a batch, instances of BufferingFormatter tin can be used. In addition to the format string (which is applied to each message in the batch), there is provision for header and trailer format strings.
When filtering based on logger level and/or handler level is not enough, instances of Filter can be added to both Logger and Handler instances (through their addFilter() method). Before deciding to process a bulletin further, both loggers and handlers consult all their filters for permission. If whatever filter returns a false value, the bulletin is not processed further.
The bones Filter functionality allows filtering by specific logger name. If this feature is used, letters sent to the named logger and its children are allowed through the filter, and all others dropped.
Exceptions raised during logging¶
The logging package is designed to swallow exceptions which occur while logging in production. This is so that errors which occur while handling logging events - such equally logging misconfiguration, network or other like errors - do not crusade the application using logging to terminate prematurely.
SystemExit and KeyboardInterrupt exceptions are never swallowed. Other exceptions which occur during the emit() method of a Handler subclass are passed to its handleError() method.
The default implementation of handleError() in Handler checks to see if a module-level variable, raiseExceptions , is set. If set, a traceback is printed to sys.stderr . If not ready, the exception is swallowed.
Note
The default value of raiseExceptions is True . This is because during evolution, y'all typically desire to exist notified of any exceptions that occur. It'due south advised that you fix raiseExceptions to Faux for production usage.
Using arbitrary objects every bit messages¶
In the preceding sections and examples, it has been assumed that the message passed when logging the upshot is a string. Withal, this is non the simply possibility. You can pass an arbitrary object as a message, and its __str__() method will exist chosen when the logging system needs to catechumen it to a cord representation. In fact, if y'all desire to, yous can avoid computing a cord representation altogether - for example, the SocketHandler emits an result past pickling it and sending it over the wire.
Optimization¶
Formatting of message arguments is deferred until information technology cannot be avoided. Even so, computing the arguments passed to the logging method tin likewise exist expensive, and y'all may desire to avert doing it if the logger will just throw away your result. To decide what to do, you tin call the isEnabledFor() method which takes a level argument and returns truthful if the result would be created by the Logger for that level of call. You tin can write code similar this:
if logger . isEnabledFor ( logging . DEBUG ): logger . debug ( 'Message with %s , %s ' , expensive_func1 (), expensive_func2 ()) then that if the logger'south threshold is ready to a higher place DEBUG , the calls to expensive_func1() and expensive_func2() are never fabricated.
Note
In some cases, isEnabledFor() tin itself be more expensive than you'd like (e.g. for deeply nested loggers where an explicit level is only gear up high up in the logger hierarchy). In such cases (or if you want to avoid calling a method in tight loops), you lot can cache the result of a telephone call to isEnabledFor() in a local or case variable, and use that instead of calling the method each time. Such a buried value would simply demand to be recomputed when the logging configuration changes dynamically while the application is running (which is not all that common).
There are other optimizations which can be made for specific applications which demand more precise control over what logging information is nerveless. Hither's a list of things you can do to avoid processing during logging which y'all don't need:
| What you don't want to collect | How to avoid collecting information technology |
|---|---|
| Information about where calls were made from. | Set |
| Threading information. | Set up |
| Current process ID ( | Gear up |
| Current process proper name when using | Set |
Also note that the core logging module just includes the basic handlers. If you don't import logging.handlers and logging.config , they won't take upwardly any memory.
Source: https://docs.python.org/3/howto/logging.html
Posted by: kingtordese.blogspot.com
0 Response to "How To Change Log Into Exponential Form"
Post a Comment