Using the logging framework
---------------------------

The class where you want to use logging/debug facilities have to
inherit from elisa.core.log.Loggable and have a log_category string
class variable. The most important classes in Elisa are already
inheriting from it. See the API documentation if you have any doubt.

There are 5 log levels:

1. Loggable.error(message): raises SystemExit exception; don't use it
2. Loggable.warning(message): use that when an operation failed but it
   doesn't prevent Elisa from continuing to run
3. Loggable.info(message): display a human/user readable message
4. Loggable.debug(message): display a message intended for developers
   debugging the application, can be informations about variable value
   for instance
5. Loggable.log(message): display a message

Messages are by default displayed on stderr, level based filtering is
controlled by the ELISA_DEBUG environment variable. Levels are incremental,
if you want to view LOG messages, you'll also see all other levels. If
you only want INFO, you'll see ERROR, WARNING and INFO. Examples:

::

  # very verbose output: LOG
  $ ELISA_DEBUG=5 python elisa.py

  # DEBUG level output
  $ ELISA_DEBUG=4 python elisa.py

You can filter messages by category too:

::

  # let's DEBUG the media_manager
  $ ELISA_DEBUG="media_manager:5" python elisa.py

  # let's see application INFO and config DEBUG
  $ ELISA_DEBUG="application:3,config:5" python elisa.py

As you may have guessed syntax is quite simple:

::

  ELISA_DEBUG="log_category_name:int[,...]"

log_category_name is the value of one of the Loggable.log_category
variables. By convention:

- Component.log_category = "comp_%s" % Component.name
- SomeElisaObject.log_category = SomeElisaObject.name = "some_elisa_object"




