CAMS

h1. Logging

Critical information about the execution of CAMS should be displayed to the user through the Graphical User Interface. Nevertheless, less important pieces of information that are only useful to developers to diagnose the system can be recorded in logs. Messages can be also displayed in the terminal window.

p{border: solid 1px #00008B; padding: 1em; margin: 1em; background: #EEF}. %{color:darkblue; font-weight: bold; font-size: large}Note:% *_print_ statements must not be used* to issue messages about the state of CAMS. This is because *1)* Standard text output cannot be traced back to the file and line of code where it has been created; *2)* Messages can not be shown or hidden according to their severity *3)* Messages cannot be easily recorded for further analysis.

h2. CAMS logging configuration

Logging in CAMS uses python "logging library":https://docs.python.org/3/library/logging.html

Python loggers are typically named after the module they are defined in (i.e.: nephelae.database.CloudData) From the "advanced python logging tutorial":https://docs.python.org/3/howto/logging.html#logging-advanced-tutorial

bq. A good convention to use when naming loggers is to use a module-level logger, in each module which uses logging, named as follows:

<pre><code class="python">

logger = logging.getLogger(__name__)

</code></pre>

This means that logger names track the package/module hierarchy, and it’s intuitively obvious where events are logged just from the logger name.

CAMS uses this scheme with loggers defined per module/file. *Because the CAMS code base layout is one class = one module, the number of logger objects can be big. Check if this extensive logging approach has in impact in performance*

The recommended logger initialization in CAMS is to run the following code *before any module imports*:

<pre><code class="python">

import logger

_logger = logging.getLogger(__name__)

</code></pre>

Single leading underscore indicates that the object is not part of the public API.

The python logging guide recommends adding the empty handler be default to prevent "No handlers could be found for logger X.Y.Z" messages from appearing. 

<pre><code class="python">

import logging

logging.getLogger(__name__).addHandler(logging.NullHandler())

</code></pre>

Django configures handlers by default so there is no risk for CAMS unless libraries are used independently.

h3. Setup the log level

Environment variables control the log level by setting them to one of <code class="shell">DEBUG</code>, <code class="shell">INFO</code>, <code class="shell">WARNING</code>, <code class="shell">ERROR</code> :

* <code class="shell">DJANGO_LOG_LEVEL</code> django related loggers

* <code class="shell">CAMS_LOG_LEVEL</code> general log level (cams libraries and external)

Detailed configuration options are found in the django settings for the gui project (<code class="shell">settings.py</code>)

h2. See also

"Configuring Logging for a Library":https://docs.python.org/3/howto/logging.html#library-config

"Good logging practice in Python":https://fangpenlin.com/posts/2012/08/26/good-logging-practice-in-python/