Logging and exceptions reporting
================================

There are specific situations in which it might be helpful a reporting system, to report an error state or to provide debug information in development stage. According to this, PyHP offers essentially two logging operation types: an automatic error and exception logging and a manual logging instruction.

-----------------------------
Manually sending log messages
-----------------------------

While developing your web application, you might want to send some notification messages to a common destination, for example to check pages behaviour and do some debug operations. PyHP lets you generate those messages and manage their destination and level reporting.

----------------------
Choosing a destination
----------------------

PyHP offers three destinations for your log messages:
 - to the ''Apache log system'' ("apache")
 - directly to the ''web page rendering'' ("web")
 - to ''nowhere'' ("none")

Sending log messages natively to the ''Apache log system'' will print out your messages to the Apache2's log file, usually located in a position like ''/var/log/apache2/error.log'' in your file system. Selecting the ''web page rendering'' will send the visualization directly of the output web page. Choosing to send them to ''nowhere'' instead will cause a total abortion of log visualization.

These three destinations are usually selected as a configuration option (see the ConfigurationOptions page). Anyway, you can decide to redirect the logging output to another destination dinamically during the execution of your Python script, using the ``set()`` method exposed by the ``pyhp.log`` object:
::

	pyhp.log.set("apache")
	pyhp.log.set("web")
	pyhp.log.set("none")

This setting will be valid until a new invocation of the ``pyhp.log.set()`` method or until the end of the script execution, then the default destination defined into the configuration options will be reset.

-------------------------------------
Filtering log message types as levels
-------------------------------------

In the PyHP log system, each log message is defined with a certain category. Available categories (and relative types) are:
 - Debug (pyhp.log.DEBUG)
 - Information (pyhp.log.INFO)
 - Warning (pyhp.log.WARN)
 - Error (pyhp.log.ERR)

To create a message, use the ``log()`` method of the ``pyhp.log`` object, giving the category and the message in string form. Examples:
::

	pyhp.log.log(pyhp.log.WARN, "Malformed form request detected")
	pyhp.log.log(pyhp.log.INFO, "Message has been sent")
	pyhp.log.log(pyhp.log.DEBUG, "MY_APP: entered true branch of #2 if statement")


You can then select which categories should be sent (or not) to the log system, using the ``set_level()`` method. Specifying a certain category level will cause the visualization of the selected category and all the others at an higher gravity grade. For example, selecting the ''debug'' grade will cause the visualization of every type of log message, choosing ''information'' will provide every message except ''debug'' ones, and so on. This is the use of the ``set_level()`` method:
::

	pyhp.log.set_level("debug")
	pyhp.log.set_level("info")
	pyhp.log.set_level("warn")
	pyhp.log.set_level("err")


As for the destination of the log messages, this setting will override the default one specified in the configuration options (see ConfigurationOptions) until the end of the script execution.

-----------------------------
Automatic exception reporting
-----------------------------

Whenever an exception occurs, PyHP automatically prints a traceback on the set log destination. Working in production mode will generate a basic traceback indication, showing the exception name and the module and function in which it is involved. Working in development mode will instead generate a more detailed traceback information set, showing the line of the instruction that caused the error state too. For information about operation modes, see the ConfigurationOptions page.

This is an example of an exception traceback log running in development mode, with ``web`` set as the log messages destination:
::

	Traceback (most recent call last):
	  File "/tmp/filepv0qn9", line 108, in <module>
	  function_name()
	NameError: name 'function_name' is not defined