1.3. Logging System¶
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 Environment Variables variables, which should be sufficient in most scenarios, and via the Application Level Logging, which provides programmatic access to the logging system for advanced use-cases.
1.3.1. 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.
Controls the log level. This controls the amount of output generated by the logging system.
SAGA_VERBOSEexpects either a numeric (0-4) value or a string (case insensitive) representing the log level:
Numeric Value Log Level Type of Messages Displayed 0 (default)
Only fatal events that will cause SAGA to abort. 1
Errors that will not necessarily cause SAGA to abort. 2
Warnings that are generated by SAGA and its middleware adaptors. 3
Useful (?) runtime information that is generated by SAGA and its middleware adaptors. 4
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
DEBUGbefore you run your program:
SAGA_VERBOSE=DEBUG python mysagaprog.py
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.engine) and individual middleware adaptors
SAGA_LOG_FILTERSexpects 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.engineand a specific middleware adaptor called
xyzyou would set the following environment variables:
SAGA_VERBOSE=DEBUG SAGA_LOG_FILTERS=saga.engine,saga.adaptor.xyz python mysagaprog.py
Controls where the log messages go. Multiple concurrent locations are supported.
SAGA_LOG_TARGETSexpects either a single location or a comma-separated list of locations, where a location can either be a path/filename or the
STDOUTkeyword (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
1.3.2. Application Level Logging¶
The SAGA-Python logging utilities are a thin wrapper around Python’s logging
facilities, integrated into the SAGA-Python configuration facilities.
To support the seamless integration of application level logging needs, the
saga.utils.logger.getLogger() allows to produce additional logger
facilities, which are again native Python
logging.Logger instances, but
preconfigured according to the SAGA-Python logging configuration.
Those instances can then be further customized as needed:
from saga.utils.logger import getLogger, INFO app_logger = getLogger ('application.test') app_logger.level = INFO app_logger.info ('application level log message on INFO level')