Developing Omega Logging

Omega’s logging system is built upon the spdlog logging tool.

Logging macros and custom formatters for Kokkos data types have been integrated into the Omega logging system via the Logging.h header file located in the src/infra directory. Users who wish to utilize Omega’s logging capabilities must include this header file in their code.

The src/infra/Logging.cpp file encompasses various functions related to logging. As of the current version, this file contains the OMEGA::initLogging function, which initialize the logging process. It is recommended to invoke the OMEGA::initLogging function at the beginning of an Omega application to properly initialize the logging system.

Initializing Omega Logger

The OMEGA::initLogging function, located within the src/infra/Logging.cpp file, serves as a pivotal component for initializing the Omega logging system.

The function establishes the default logger configuration, ensuring that logging messages are effectively saved to a designated file. The path to this file can be passed as the second argument to OMEGA::initLogging. When it is omitted, the path comes from the OMEGA_LOG_FILE environment variable if that is set and non-empty, and from OMEGA::OmegaDefaultLogfile (omega.log) otherwise. The log file is truncated when it is opened, so it holds only the messages from the current run.

Log files in the unit tests

Every unit test driver calls OMEGA::initLogging(DefEnv) without a file name, so without any further arrangement all of the tests would write to a single omega.log in the build’s test directory, with nothing to say which test wrote which line. To avoid this, test/CMakeLists.txt sets OMEGA_LOG_FILE per test in add_omega_test, so that each test writes to test/logs/<TEST_NAME>.log. Note that the name comes from the CTest test name rather than the source file, because several tests are built from the same source (for example TEND_PLANE_TEST and TEND_PLANE_SINGLE_PRECISION_TEST both come from TendencyTermsTest.cpp).

A new test added with add_omega_test gets its own log file automatically. A test driver that hard-codes a log file name would opt out of this, so pass no file name to initLogging unless the test manages its own log files, as LoggingTest does.

The environment variable relies on the MPI launcher passing its environment to the ranks it starts, which is true of srun. If a launcher does not, the tests fall back to writing omega.log.

Creating Logging Macros

The Omega logging macros, denoted by the prefix LOG_, are defined within the src/infra/Logging.h file. These macros constitute a main part of the logging infrastructure, enabling users to seamlessly incorporate logging functionality into their Omega applications.

Furthermore, the logging framework includes a distinct set of macros that commence with the prefix LOGGER_. These macros offer enhanced versatility by accommodating the utilization of the spdlog logger as their first argument. This approach facilitats the integration of various logger types.

Customer formatter for Kokkos

Within the same header file, you will encounter specialized spdlog formatter structs designed to accommodate Kokkos data types.

For further information on customizing the spdlog formatter, refer to Custom formatting.