Log - Logger¶
The logga
module wraps the standard Python logging
module and abstract some of the messy parts. logging
itself is
is similar to (possibly even motivated by) the
log4j facility.
Most importantly, logging
guarantees a singleton object that can be
used throughout your project.
One of the handiest features with logga
is that it
automatically detects the output stream and is able to direct the logging
ouput to STDOUT
or to a file stream (if configured).
Simplest Usage (Console)¶
Simply import the logga
log
handler object into your
project.
Note
Behind the scenes, the
logga
log
handler object is instantiated through the module-level functionlogging.getLogger(name)
. Multiple calls togetLogger()
with the same name will always return a reference to the same Logger object.
name
is defined as the highest level Python calling module. For example, in the Module Usage (File-based Configuration) sample below,name
will beyou_beaut.py
. For normal console-based output, name would be<stdin>
.
The following example demonstrates usage directly under the Python interpreter:
$ python
>>> from logga import log
>>> log.debug('This is a DEBUG level logging')
2014-06-26 10:07:59,297 DEBUG:: This is a DEBUG level logging
>>> log.info('This is a INFO level logging')
2014-06-26 10:08:12,481 INFO:: This is a INFO level logging
Note
This example demonstrates console-based usage that writes to STDOUT
Module Usage (File-based Configuration)¶
Logging from your *.py
is probably a more useful proposition.
Similarly, import the logga
to your python module.
To demonstrate, add the following code into a file called you_beaut.py
:
from logga import log
log.debug('Log from inside my Python module')
To execute:
$ python you_beaut.py
2014-06-26 10:41:15,036 DEBUG:: Log from inside my Python module
But what if you want to log to a file? In this case you will have to
provide a configuration file. The structure of the config is
standard logging
. In this case, place the following into
a the file called log.conf
in the same directory as you_beaut.py
:
[loggers]
keys=root,you_beaut.py,console
[handlers]
keys=youBeautFileHandler,consoleHandler
[formatters]
keys=simpleFormatter
[logger_root]
level=DEBUG
handlers=consoleHandler
[logger_console]
level=DEBUG
handlers=consoleHandler
qualname=console
propagate=0
[logger_you_beaut.py]
level=DEBUG
qualname=you_beaut.py
handlers=youBeautFileHandler
[handler_youBeautFileHandler]
class=handlers.TimedRotatingFileHandler
level=DEBUG
formatter=simpleFormatter
args=(os.path.join(os.sep, 'var', 'tmp', 'you_beaut.log'), 'midnight')
[handler_consoleHandler]
class=StreamHandler
level=DEBUG
formatter=simpleFormatter
args=(sys.stdout, )
[formatter_simpleFormatter]
format=%(asctime)s (%(levelname)s): %(message)s
datefmt=
Now when you $ python you_beaut.py
you will notice that output to
the console is suppressed. Instead, the output is directed to a file
stream defined by handler_youBeautFileHandler
section from the
log.conf
file. To verify:
$ cat /var/tmp/you_beaut.log
2014-06-26 11:39:34,903 (DEBUG): Log from inside my Python module
Functions¶
-
logga.
set_console
()¶ Drop back to the root logger handler. This is typically the console.
This can be used to override the logging file output stream and send log messages to the console. For example, consider the following code that has a
log.conf
that writes to the log filemy.log
:from logga import log, set_console set_console() log.debug('Log from inside my Python module')
The
set_console()
call will force the log message to writeLog from inside my Python module
to the console.
-
logga.
set_log_level
(level='INFO')¶ Set the lower threshold of logged message level. Level defaults to
INFO
. All default log levels are supportedNOTSET
,DEBUG
,INFO
,WARNING
,ERROR
andCRITICAL
in order of severity.For example:
>>> from logga import log, set_log_level >>> log.debug('This DEBUG message should display') 2014-06-30 12:50:48,407 DEBUG:: This DEBUG message should display >>> set_log_level(level='INFO') >>> log.debug('This DEBUG message should now not display') >>> log.debug('This DEBUG message should now not display') >>> log.info('This INFO message should display') 2014-06-30 12:51:44,782 INFO:: This INFO message should display
- Kwargs:
- level: the lower log level threshold. All log levels including and above this level in serverity will be logged
-
logga.
suppress_logging
()¶ Provides an overriding (to level
CRITICAL
) suppression mechanism for all loggers which takes precedence over the logger`s own level.When the need arises to temporarily throttle logging output down across the whole application, this function can be useful. Its effect is to disable all logging calls below severity level
CRITICAL
. For example:>>> from logga import log, suppress_logging >>> log.debug('This DEBUG message should display') 2014-06-30 13:00:39,882 DEBUG:: This DEBUG message should display >>> suppress_logging() >>> log.debug('This DEBUG message should now not display') >>> log.critical('But CRITICAL messages will get through') 2014-06-30 13:02:59,159 CRITICAL:: But CRITICAL messages will get through
-
logga.
enable_logging
()¶ Opposite of the
logga.suppress_logging()
function.Re-enables logging to
DEBUG
level and above:>>> from logga import log, suppress_logging, enable_logging >>> suppress_logging() >>> log.debug('This DEBUG message should now not display') >>> enable_logging() >>> log.debug('This DEBUG message should now display') 2014-06-30 13:08:22,173 DEBUG:: This DEBUG message should now display
-
logga.
autolog
(message)¶ Automatically log the current function details.
Used interchangeably with the
log
handler object. Handy for for verbose messaging during development by adding more verbose detail to the logging message, such as the calling function/method name and line number that raised the log call:>>> from logga import autolog >>> autolog('Verbose') 2014-06-30 13:13:08,063 DEBUG:: Verbose: <module> in <stdin>:1 >>> log.debug('DEBUG message') 2014-06-30 13:15:35,319 DEBUG:: DEBUG message >>> autolog('DEBUG message') 2014-06-30 13:15:41,760 DEBUG:: DEBUG message: <module> in <stdin>:1
- Args:
- message: the log message to display