Logging

polaris does not have its own module for logging, instead making use of mpas_tools.logging. This is because a common strategy for logging to either stdout/stderr or to a log file is needed between polaris and mpas_tools. To get details on how this module works in general, see MPAS-Tools’ Logging as well as the APIs for mpas_tools.logging.LoggingContext and mpas_tools.logging.check_call().

For the most part, the polaris framework handles logging for you, so task developers won’t have to create their own logger objects. They are attributes that belong to the step or task. If you run a step on its own, no log file is created and logging happens to stdout/stderr. If you run a full task, each step gets logged to its own log file within the task’s work directory. If you run a suite, each task and its steps get logged to a file in the case_output directory of the suite’s work directory.

Although the logger will capture print statements, anywhere with a run() function or the functions called inside that function, it is a good idea to call logger.info instead of print to be explicit about the expectation that the output may go to a log file.

Even more important, subprocesses that produce output should always be called with mpas_tools.logging.check_call(), passing in the logger that belongs to the step. Otherwise, output will go to stdout/stderr even when the intention is to write all output to a log file. Whereas logging can capture stdout/stderr to make sure that the print statements actually go to log files when desired, there is no similar trick for automatically capturing the output from direct calls to subprocess functions. Here is a code snippet from polaris.landice.tasks.dome.setup_mesh.SetupMesh.run():

from mpas_tools.logging import check_call


def run(self):
    ...
    section = config['dome']
    ...
    levels = section.getfloat('levels')
    args = ['create_landice_grid_from_generic_MPAS_grid.py',
            '-i', 'mpas_grid.nc',
            '-o', 'landice_grid.nc',
            '-l', levels]

    check_call(args, logger)
    ...

This example calls the script create_landice_grid_from_generic_MPAS_grid.py from mpas_tools with several arguments, making use of the logger.