= S3Log =
[[TOC]]

== Purpose ==

S3Log is a simple global logging facility for Sahana Eden.

== Logger ==

The logger is called like:
{{{#!python
current.log.error("Something went wrong", value="Example")
}}}
Which gives a log entry like:
{{{
2014-02-16 11:58:41 S3LOG ERROR: Something went wrong: Example
}}}

The logger functions correspond to the severity level of the message:
 - current.log.critical() (highest)
 - current.log.error()
 - current.log.warning()
 - current.log.info()
 - current.log.debug() (lowest)
The call signature of all logger functions is identical with the example above.
The "value" parameter is optional.

== Configuration ==

The logger can be configured in models/000_config:
{{{#!python
# Configure the log level ("DEBUG", "INFO", "WARNING", "ERROR" or "CRITICAL"), None = turn off logging
#settings.log.level = None
# Uncomment to write log messages to the console (sys.stderr)
#settings.log.console = True
# Configure a log file (file name)
#settings.log.logfile = None
# Uncomment to get detailed caller information
#settings.log.caller_info = True
}}}

=== Log Level ===

{{{#!python
settings.log.level = "DEBUG"
}}}
determines the minimum severity level at which messages will be logged.

Severity levels:
 - CRITICAL (highest)
 - ERROR
 - WARNING
 - INFO
 - DEBUG (lowest)
 - None turns all logging off.

=== Console ===

{{{#!python
settings.log.console = True 
}}}
enables logging to the system error console (sys.stderr).
False disables console logging.

Console logging can be enabled in parallel with file logging. Console logs on remote servers are not easily accessible, though.
=== Log File ===

{{{#!python
settings.log.logfile = "/var/log/eden.log"
}}}
enables logging to the specified file. The logger rotates 3 log files with a maximum size of 1MB: /var/log/eden.log, /var/log/eden.log.1 and /var/log/eden.log.2
None disables logging to file.

File logging can be enabled in parallel with console logging.
=== Caller Info ===

With 
{{{#!python
settings.log.caller_info = True
}}}
the log messages will include information about the origin of the log message (file name, line number, function name):
{{{
2014-02-16 11:58:23 (applications/eden/modules/s3/s3rest.py 477 __init__) ERROR: Something went wrong: Example
}}}