Set log levels#

EMOD simulations output several files, including log files. For more information on the logging files that are created by a simulation, see Error and logging files for generic, Error and logging files for HIV, or Error and logging files for malaria. By default, logging is at the “INFO” level, but you can set the level at which you want logging information generated. If you see redundant log messages, you can also throttle logging to eliminate them.

There are five log levels. The level chosen will log messages for that level and all higher levels (levels of smaller numeric value). You can set default log levels across the entire Eradication.exe or for individual files in the Eradication.exe; individual file settings will override the default. For example, if you want to increase logging for a particular file you are debugging without increasing logging across the entire Eradication.exe, you can set the default log level to “WARNING” and set the log level for the file to “DEBUG”. The standard output will reflect the default log level for all settings except “ERROR” or “WARNING”. For example:

Log-levels:
        Default -> INFO
        Eradication -> INFO

The following log levels are available:

ERROR (1): This is the highest level. Only errors, including critical errors, are logged to standard output.
WARNING (2): Warnings and errors are logged to standard output.
INFO (3): This is the default logging level for the executable and is set implicitly. Informational messages, warnings, and errors are logged to standard output.
DEBUG (4): Debug information, informational messages, warnings, and errors are logged to standard output. Debug level logging messages do not require a debug build of Eradication.exe. This setting will generate a large number of messages and may impact performance. If you need the debugging messages, we recommend that you limit the number of files with this setting and not set it as the default across the entire Eradication.exe.
VALID (5): This is the lowest level. Validation information, debug information, informational messages, warnings, and errors are logged to standard output. This log level is for very low-level debugging of specific values, including values in tight loops. Because it could severely impact performance, this level will only output to standard output during a debug build of Eradication.exe.

Set default Eradication.exe level#

To set the default log level across the entire Eradication.exe, add the parameter logLevel_default to your configuration file and set it to the log level desired. For example:

{
    "logLevel_default": "WARNING"
}

Set level for individual files#

You can set the log level for an individual file, if it supports the ability. This is typically only used for debugging after making source code changes. This setting will override the default set using logLevel_default, whether set to a higher or lower level.

In the C++ files that make up the EMOD source code, open the file for which you want to set the log level.
Search for static const char * _module.

“Module” refers to the C++ file and is not the same as an EMODule. If this string isn’t present, you cannot set a log level for the file.
Look for logging macros in the file, such as LOG_WARN(x).

If macros are present, this indicates that the file supports that log level setting. The file may not support all log levels. Logging macros can be found in utils/Log.h. You can also add your own logging messages to the file using the logging macros.
In the configuration file, add the logLevel_<FileName> parameter with the log level desired. For example:
```
{
    "logLevel_SimulationVectorExport":"DEBUG"
}
```

Throttle redundant logging#

It’s possible that multiple identical logging messages are generated by a file of Eradication.exe. This is normal behavior, but the verbosity can be unwanted or unnecessary. You can eliminate duplicate messages by turning on “throttling”, which retains only one logging message instead of a series of duplicate messages from each file.

Only one copy of the message will be generated when it is one of a series of duplicates from the same file. The identical messages need not be output one right after one another to be throttled. If an identical message is output from a different file, it will still be generated. Throttling can only be enabled across the entire Eradication.exe, not per file. It is off by default.

To enable throttling, add the following parameter and value to your configuration file:

{
    "Enable_Log_Throttling": 1
}

For example, the following log messages are seen with throttling turned off:

00:00 [0] [D] [FileA] identical message: I'm in FileA
00:00 [0] [D] [FileB] another message from B
00:00 [0] [D] [FileA] identical message: I'm in FileA
00:00 [0] [D] [FileB] different message from B
00:00 [0] [D] [FileA] identical message: I'm in FileA
00:00 [0] [D] [FileB] yet another message from B.
00:00 [0] [D] [FileA] identical message: I'm in FileA

With throttling on, the repeated messages from file A are removed, even though they are intermixed with other log messages from file B:

00:00 [0] [D] [FileA] identical message: I'm in FileA
00:00 [0] [D] [FileB] another message from B
00:00 [0] [D] [FileB] different message from B
00:00 [0] [D] [FileB] yet another message from B.