[EPIC] Log formatting improvement
Open
@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,
logLevelpractices 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
- 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 anenumwith clear and documented labels (see below or in issue #3014, - Add a "message type" header for each log lines (Warning, Error, Info...),
- Add a
globalLogLevelat the<Problem>level to control general log lines (which cannot be controlled at the moment), - #3009
- #3010
- Add an indenting feature (for convergence?).
- 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)
- Existing messages review :
- Review all log alignement and log levels, there should not be any
std::coutin 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.