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

In a distributed environment unified error logging and reporting is a crucial
capability for debugging and monitoring. BigJob has a configurable logging system
that  captures debug, info, warning and error messages across its runtime and SAGA's middleware 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 :code:`bigjob.conf` file.


.. _env_vars:
---------------------
Environment Variables
---------------------

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

.. envvar:: BIGJOB_VERBOSE

   Controls the log level. This controls the amount of output generated by the
   logging system. ``BIGJOB_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)     |                     | BigJob to abort.                   | 
   |               |                     |                                    |
   +---------------+---------------------+------------------------------------+
   | 1             | ``ERROR``           | Errors that will not necessarily   |
   |               |                     | cause BigJob to abort.             | 
   |               |                     |                                    |
   +---------------+---------------------+------------------------------------+
   | 2             | ``WARNING``         | Warnings that are generated by     |
   |               |                     | BigJob			      | 
   |               |                     |                                    |
   +---------------+---------------------+------------------------------------+
   | 3             | ``INFO``            | Useful runtime information         |   
   |               |                     | that is generated by BigJob	      | 
   |               |                     | 			              |
   +---------------+---------------------+------------------------------------+
   | 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 BigJob generates during 
   program execution, you would set :envvar:`BIGJOB_VERBOSE` to ``DEBUG`` before 
   you run your program::

       BIGJOB_VERBOSE=DEBUG python mysagaprog.py

-------------------------
BigJob Configuration File
-------------------------

BigJob utilizes a configuration file named :code:`bigjob.conf` located in the root of the BigJob installation (e.g. :code:`$HOME/.bigjob/python/lib/python2.<PYTHON_MINOR_VERSION>/site-packages/BigJob-<BIGJOB_VERSION>-py2.X.egg/)::

	# logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR, logging.CRITICAL
	logging.level=logging.INFO

------------------------
BigJob Logger
-------------------------
The log level can also be set inside the BigJob script that you are running as follows::

	import logging
	from bigjob import logger
	logger.setLevel(logging.FATAL)

**Q: How can I control BigJob log messages from the application it is executing?**

BigJob logger can be obtained and handlers can be added to the logger object. For example, with the below set of instructions, the application and BigJob debug messages are written to the :code:`namd_bigwork.log` file::

	logger = logging.getLogger('bigjob')
	fileHandle = logging.FileHandler('namd_bigwork.log',mode='w')
	fileHandle.setLevel(logging.DEBUG)
	logger.addHandler(fileHandle)
	logger.debug("Logging to namd_bigwork.log at DEBUG level")
