GEOS-DEV / GEOS-DEV/GEOS

[EPIC] Log formatting improvement

Open
#2,277 11 comments 0 reactions 1 assignee View on GitHub

@MelReyCG is already working on this.

Since Feb 6, 2023.

EPIC type: feature
Dominant language
C++
Stars
287
Forks
109
Avg merge
4d 41m
Merged PRs (30d)
5

Description

What is the requested feature?
The log is hard to read by the users in our production environnement. So, in order to improve GEOS usability, we need to improve the log formatting.


Is your request related to a specific problem?

  • All messages aren't necessarily relevant to users and some of them are very repetitive,
  • logLevel practices are not uniformized nor documented,
  • It's hard to retrieve warnings and errors among all the info messages, there lack clear sections,
  • data outputting is generally done with a line per number rather than a table, sometimes we are lacking units.

Describe the solution you'd like

  1. Logger refactor :
  • Refactor logging macros and the logger namespace so we have - at least under the hood - a real class, the messages should be all equally aligned with the outputting rank (see below or in issue #3014),
  • Internally, log messages should be structured data (see below),
  • Refactor the LogLevel, it should be an enum with clear and documented labels (see below or in issue #3014,
  • Add a "message type" header for each log lines (Warning, Error, Info...),
  • Add a globalLogLevel at the <Problem> level to control general log lines (which cannot be controlled at the moment),
  • #3009
  • #3010
  • Add an indenting feature (for convergence?).
  1. Log specific improvements :
  • #3013
  • #3015
  • #3012
  • #3011
  • #3405
  • Improve convergence info clarity,
  • If possible, show convergence issues better,
  • Show well info per perforation rather than for the whole well,
  • store the log in hdf5 format (#2298)
  1. Existing messages review :
  • Review all log alignement and log levels, there should not be any std::cout in the code,
  • #3179
  • Review the numbers formatting to improve readability (add thousand separators for large integers, review the number of significant digits).

Refactored log output exemple :

INFO      : well ‘my well (myxml.xml:123)’ is shut
 RANK 170

===================================================
TIMESTEP  : Time: 0s, dt:864s, Cycle: 0
 RANK     0
===================================================

WARNING   : Time-step required will be increased based on state change.
 RANK 1

LogLevel enum proposal :

/// @brief Enumerate the logging levels from the most importants messages to the one that contain the more details.
enum class LogLevel : int16_t
{
  Silent = -1,    // Useful as a globalLogLevel for silencing the logger. shouldn't be used as a message level.
  Important = 0,  // Application level messages (help, almost blocking warnings, application informations & phases)
  Progress = 1,   // Time step attempts, newton loop progress of Solver objects
  Detailed = 2,   // More detailed info and stats that affect progress, e.g. residual norms.
  Trace = 3,      // This is intended as a user-level debugging tool. detailed info trace what each component is
                  // doing. e.g. a line for every part of the assembly process, every boundary condition that's being
                  // applied by a physics solver, etc.
  Debug = 4,      // Information that are only relevant for a developper in a debugging context.
  DebugTrace = 5, // This level is useful to have deeper debugging information (which can be potencially heavy to log).
};

Internal message data (feel free to suggest more !) :

  • Message,
  • Message type,
  • Log level,
  • Calling file / line,
  • Rank,
  • Sending Group / Wrapper if available,
  • Timestep / convergence info (if applicable).

Describe alternatives you've considered
Another solution would be to write another log for the users (and the current one would be intended for developpers).

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.