logex 2.1.0

Easily log uncaught exceptions in D-Bus, thread and other functions.

logex
=====

.. contents::

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 <logex.py>`_ module.

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

.. code:: python

import logex
logex.VIEW_SOURCE = True

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

.. code:: python

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 <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 <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:

.. code:: python

#!/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:

.. code:: python

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:

.. code:: python

#!/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:

.. code:: python

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