Logs¶

Logging in fractal-server is based on the standard logging library, and its logging levels are defined here. For a more detailed view on fractal-server logging, see the logger module documentation.

The logger module exposes the functions to set/get/close a logger, and it defines where the records are sent to (e.g. the fractal-server console or a specific file). The logging levels of a logger created with set_logger are defined as follows:

The minimum logging level for logs to appear in the console is set by FRACTAL_LOGGING_LEVEL;
The FileHandler logger handlers are alwasy set at the DEBUG level, that is, they write all log records.

This means that the FRACTAL_LOGGING_LEVEL offers a quick way to switch to very verbose console logging (setting it e.g. to 10, that is, DEBUG level) and to switch back to less verbose logging (e.g. FRACTAL_LOGGING_LEVEL=20 or 30), without ever modifying the on-file logs. Note that the typical reason for having on-file logs in fractal-server is to log information about background tasks, that are not executed as part of an API endpoint.

Example use cases¶

Module-level logs that should only appear in the fractal-server console

from fractal_server.logger import set_logger

module_logger = set_logger(__name__)

def my_function():
    module_logger.debug("This is an DEBUG log, from my_function")
    module_logger.info("This is an INFO log, from my_function")
    module_logger.warning("This is a WARNING log, from my_function")

Note that only logs with level equal or higher to FRACTAL_LOGGING_LEVEL will be shown.

Function-level logs that should only appear in the fractal-server console

from fractal_server.logger import set_logger

def my_function():
    function_logger = set_logger("my_function")
    function_logger.debug("This is an DEBUG log, from my_function")
    function_logger.info("This is an INFO log, from my_function")
    function_logger.warning("This is a WARNING log, from my_function")

Note that only logs with level equal or higher to FRACTAL_LOGGING_LEVEL will be shown.

Custom logs that should appear both in the fractal-server console and in a log file

from fractal_server.logger import set_logger
from fractal_server.logger import close_logger

def my_function():
    this_logger = set_logger("this_logger", log_file_path="/tmp/this.log")
    this_logger.debug("This is an DEBUG log, from my_function")
    this_logger.info("This is an INFO log, from my_function")
    this_logger.warning("This is a WARNING log, from my_function")
    close_logger(this_logger)

Note that only logs with level equal or higher to FRACTAL_LOGGING_LEVEL will be shown in the console, but all logs will be written to "/tmp/this.log".

Future plans¶

The current page concerns the logs that are emitted from fractal-sever, but not the ones coming from other sources (e.g. fastapi or uvicorn/gunicorn). In a future refactor we may address this point, with the twofold goal of

Integrating different log sources, so that they can be shown in a homogeneous way (e.g. all with same format);
Redirecting all console logs (from different sources) to a rotating file (e.g. via a RotatingFileHandler).