logex

Logex is a python module to easily add logging for unhandled exceptions in D-Bus, thread and other functions. It can also be quite helpful when developing with the new asyncio module of python 3.4. Although this module does some sort of exception logging, it can easily happen that exceptions are accidentally swallowed. Although unhandled exceptions get written to STDERR by default and most modules provide some mechanism to log these, this is not always sufficient, e.g. when inside a daemon which discards all default output. Sometimes it may also be desirable to automatically send an email if some exception occurs or at least write some kind of audit log.

This modlue comes with a decorator function which can be applied on demand. It provides advanced debugging information which gives you the most relevant information for each frame in the exception's traceback.

Settings

A description of all available settings is available in the source documentation of the log() function in the logex.py module.

All settings can be set "globally", e.g. by using:

import logex
logex.VIEW_SOURCE = True

or they can be specified when decorating a function or method:

import logex
@logex.log(view_source=True)
def f():
    pass

Currently available module variables and their defaults:

• LOGFUNCTION = logging.error
• TEMPLATE = ('Unhandled exception calling %(funcname)s(%(argsview)s):\n%(traceback)s\n%(sourceview)s')
• ADVANCED = False
• LAZY = False
• RERAISE = True
• CATCHALL = False
• VIEW_SOURCE = False
• DETECT_NESTED = True

The default behaviour of the log() decorator is to generate a log message using TEMPLATE and pass this to LOGFUNCTION. For a list of place holders that are replaced, see the generate_log_message() function in logex.py.

Setting ADVANCED to True, gives you the opportunity to use a logging function which interprets the exception data itself. For a description of the arguments to an advanced logging function, see the generate_log_message() function in logex.py.

If LAZY is True, the logging function itself must return another function object which is then used as the actual logging function.

RERAISE can be set to False to only log the exception and continue "normally". This will, of course, not resume the decorated function itself, but return to the caller of this function and resume execution there.

If CATCHALL is True, all exceptions are caught, i.e. also KeyboardInterrupt, SystemExit and GeneratorExit.

VIEW_SOURCE can be used to show the source code and local variables for every function in the exceptions traceback.

logex will usually detect if an exception occurs in a logex-decorated function which, in turn, was called by a logex-decorated function and shorten the output so you do not get the same source view twice. DETECT_NESTED can be used to disable this feature and always print the full source view.

Example

Several examples can be found in the examples directory, so we show just some simple usage here:

#!/usr/bin/python
import logex

@logex.log
def my_function():
    raise Exception("something bad happens here")

my_function()

This will simply print the exception traceback, like this:

ERROR:root:Unhandled exception calling my_function():
Traceback (most recent call last):
  File "./x.py", line 10, in my_function
    do_something_dangerous()
  File "./x.py", line 5, in do_something_dangerous
    raise Exception("something bad happens here")
Exception: something bad happens here


Traceback (most recent call last):
  File "./x.py", line 13, in <module>
    my_function()
  File "/home/tobi/repos/logex/logex.py", line 318, in wrapper_f
    template, view_source, reraise, wrapper_code=wrapper_code)
  File "/home/tobi/repos/logex/logex.py", line 306, in wrapper_f
    wrapped_f(*args, **kwargs)
  File "./x.py", line 10, in my_function
    do_something_dangerous()
  File "./x.py", line 5, in do_something_dangerous
    raise Exception("something bad happens here")
Exception: something bad happens here

The second traceback is the one generated because an unhandled exception occurs(logex reraises exceptions by default), it also contains some extra frames generated by the logex decorator. Let's make it a bit more advanced and pleasant to read:

#!/usr/bin/python
import logex

@logex.log(view_source=True, reraise=False)
def my_function():
    x = 1
    raise Exception("something bad happens here")

my_function()

This yields:

ERROR:root:Unhandled exception calling my_function():
Traceback (most recent call last):
  File "./x.py", line 10, in my_function
    do_something_dangerous()
  File "./x.py", line 5, in do_something_dangerous
    raise Exception("something bad happens here")
Exception: something bad happens here

========== sourcecode ==========
-------------------------
-- ./x.py: my_function --
-------------------------
    7   @logex.log(view_source=True, reraise=False)
    8   def my_function():
    9           x = 1
   10-->        do_something_dangerous()
...

Locals when executing line 10:
* x: 1

------------------------------------
-- ./x.py: do_something_dangerous --
------------------------------------
    4   def do_something_dangerous():
    5-->        raise Exception("something bad happens here")

================================

We have several differences here:

• the exception is not reraised, this is probably not always desired, but makes some nicer output here ;)
• a view of the sourcecode for each function in the traceback
• a list of the current values for local variables, if present