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.

SAGA_VERBOSE

Controls the log level. This controls the amount of output generated by the logging system. SAGA_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 (default) CRITICAL Only fatal events that will cause SAGA to abort.
1 ERROR Errors that will not necessarily cause SAGA to abort.
2 WARNING Warnings that are generated by SAGA and its middleware adaptors.
3 INFO Useful (?) runtime information that is generated by SAGA and its middleware adaptors.
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 SAGA generates during program execution, you would set SAGA_VERBOSE to DEBUG before you run your program:

SAGA_VERBOSE=DEBUG python mysagaprog.py
SAGA_LOG_FILTERS

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.adaptor.name. SAGA_LOG_FILTERS expects 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.engine and a specific middleware adaptor called xyz you would set the following environment variables:

SAGA_VERBOSE=DEBUG SAGA_LOG_FILTERS=saga.engine,saga.adaptor.xyz python mysagaprog.py
SAGA_LOG_TARGETS

Controls where the log messages go. Multiple concurrent locations are supported. SAGA_LOG_TARGETS expects either a single location or a comma-separated list of locations, where a location can either be a path/filename or the STDOUT keyword (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')