#####################
Logging and Debugging
#####################

In a distributed environment unified error logging and reporting is a crucial
capability for debugging and monitoring. SAGA has a configurable logging system
that  captures debug, info, warning and error messages across all of
its middelware adaptors. The logging system can be controlled in two different
ways: via :ref:`env_vars` variables, which should be sufficient in most 
scenarios, and via the :ref:`log_api`, which provides programmatic access to
the logging system for advanced use-cases.


.. _env_vars:

Environment Variables
---------------------

Several environment variables can be used to control SAGA's logging behavior from 
the command line. Obviously, this can come in handy when debugging a problem
with an existing SAGA application. Environment variables are set in the 
executing shell and evaluated by SAGA at program startup. 

.. envvar:: SAGA_VERBOSE

   Controls the log level. This controls the amount of output generated by the
   logging system. ``SAGA_VERBOSE`` expects either a numeric (0-4) value or a 
   string (case insensitive) representing the log level:

   +---------------+---------------------+------------------------------------+
   | Numeric Value | Log Level           | Type of Messages Displayed         |
   +===============+=====================+====================================+
   | 0             | ``CRITICAL``        | Only fatal events that will cause  |
   | (default)     |                     | SAGA to abort.                     | 
   |               |                     |                                    |
   +---------------+---------------------+------------------------------------+
   | 1             | ``ERROR``           | Errors that will not necessarily   |
   |               |                     | cause SAGA to abort.               | 
   |               |                     |                                    |
   +---------------+---------------------+------------------------------------+
   | 2             | ``WARNING``         | Warnings that are generated by     |
   |               |                     | SAGA and its middleware adaptors.  | 
   |               |                     |                                    |
   +---------------+---------------------+------------------------------------+
   | 3             | ``INFO``            | Useful (?) runtime information     |   
   |               |                     | that is generated by SAGA and its  | 
   |               |                     | middleware adaptors.               |
   +---------------+---------------------+------------------------------------+
   | 4             | ``DEBUG``           | Debug message added to the code    |
   |               |                     | by the developers. (Lots of output)| 
   |               |                     |                                    |
   +---------------+---------------------+------------------------------------+

   For example, if you want to see the debug messages that SAGA generates during 
   program execution, you would set :envvar:`SAGA_VERBOSE` to ``DEBUG`` before 
   you run your program::

       SAGA_VERBOSE=DEBUG python mysagaprog.py


.. envvar:: SAGA_LOG_FILTERS

   Controls the message sources displayed. SAGA uses a 
   hierarchal structure for its log sources. Starting with the root logger
   ``saga``, several sub loggers are defined for SAGA-internal logging events
   (``saga.core``) and individual middleware adaptors ``saga.adaptor.name``.
   ``SAGA_LOG_FILTERS`` expects either a single source name or a 
   comma-separated list of source names. Non-existing source names are ignored.

   For example, if you want to see only the debug messages generated by 
   ``saga.core`` and a specific middleware adaptor called ``xyz`` you would 
   set the following environment variables::

       SAGA_VERBOSE=DEBUG SAGA_LOG_FILTERS=saga.core,saga.adaptor.xyz python mysagaprog.py

.. envvar:: SAGA_LOG_TARGETS

   Controls where the log messages go. Multiple concurrent locations are 
   supported. 
   ``SAGA_LOG_TARGETS`` expects either a single location or a comma-separated 
   list of locations, where a location can either be a path/filename or
   the ``STDOUT`` keyword (case insensitive) for logging to the console. 

   For example, if you want to see debug messages on the console but also
   want to log them in a file for further analysis, you would set the the 
   following environment variables::

       SAGA_VERBOSE=DEBUG SAGA_LOG_TARGETS=STDOUT,/tmp/mysaga.log python mysagaprog.py

