[EPIC] Log formatting improvement

[MelReyCG]

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),
• Add a data table logging feature, #3009
• Add a log section feature, #3010
• Add an indenting feature (for convergence?).

2. Log specific improvements :

• Add PVT data tables in the log (density, saturation...), #3013
• Add wells / perforations (with cell / perfo transmissibility) data tables, #3015
• Add a cell / cell transmissibility data table #3012
• Output SourceFlux statistics, #3011
• Use data tables for log, and CSV / HDF5 to output statistics #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)

3. Existing messages review :

• Review all log alignement and log levels, there should not be any std::cout in the code,
• Review all log level Wrapper documentation (Wrapper::appendDescription()), #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).

[herve-gross]

@MelReyCG can you prepare a 15-min simple presentation before you code in a branch of what you think the log should look like? It will be easier for us to help you and give you advice.

[MelReyCG]

Sure, I will do this presentation when I will have a more precise definition of the log format desired by the users.

[TotoGaz]

Chat back with @jeannepellerin about this 😉

[TotoGaz]

You should also be aware of #1613 and #2298

[jeannepellerin]

@rrsettgast

[MelReyCG]

Any suggestion @paveltomin @CusiniM @castelletto1 @klevzoff ?

[paveltomin]

Any suggestion @paveltomin @CusiniM @castelletto1 @klevzoff ?

Good initiative!
So many things, as already suggested a presentation/discussion session would be great.
General suggestion: keep it as simple as possible.

[herve-gross]

If I can chime in, it is important for logs to be human-readable, but we should also make machine-parsing (with Python, for instance) as straightforward as possible.

[TotoGaz]

If I can chime in, it is important for logs to be human-readable, but we should also make machine-parsing (with Python, for instance) as straightforward as possible.

Yes, this is very true. We can do anything we want on the log as long as there's another source of information aside that is meant to be parsed.
Otherwise, tables like in #2984 will be a challenge. Maybe you think that we should use tools like https://docs.astropy.org/en/latest/io/ascii/read.html, but still that would commit us to using this python module.

[victorapm]

This is a nice initiative. If I may chime in as well, one option that makes parsing with Python easier and it is still human readable is Markdown, e.g.:

| Element no. | CoordX | CoordY | CoordZ             | Prev Element | Next Element |
|-------------|--------|--------|--------------------|--------------|--------------|
| 0           | 9.5    | 0.2    | 11.958333333333334 | 1            |              |
| 1           | 9.5    | 0.2    | 11.875             | 2            | 0            |
| 2           | 9.5    | 0.2    | 11.791666666666666 | 3            | 1            |
| 3           | 9.5    | 0.2    | 11.708333333333334 | 4            | 2            |
| 4           | 9.5    | 0.2    | 11.625             | 5            | 3            |

[MelReyCG]

I can see 3 strategies that could solve this need for machine & human readability :

1. As this work is already started by @paveltomin, we can dump all lines that is replaced by tables in a CSV file with a writeCSV option, waiting for hdf5 support later (new tables too).
2. We can keep the legacy logs just below the new human readable line, like I did with the timestep. In this case we will need to provide a table format that is easy to parse (like @victorapm suggested). We could add an option to show the legacy logs (like -l / --legacyLogs).
3. We can provide a human readable log only with tables that are not too hard to parse (like the one @victorapm suggested), but I think that is the strategy that will need the more work to the log reader developers.

I will prepare a presentation with more insight on what I planned, so we will be able to talk about the strategy to implement.

@victorapm
What do you think of this to support the title name, and to provide an easy to parse starting & ending ?

------------------------------------------------------------------------------------
|                             WellGeneration myWell                                |
|----------------------------------------------------------------------------------|
| Element no. | CoordX | CoordY | CoordZ             | Next Element | Prev Element |
|-------------|--------|--------|--------------------|--------------|--------------|
| 0           | 9.5    | 0.2    | 11.958333333333334 | 1            |              |
| 1           | 9.5    | 0.2    | 11.875             | 2            | 0            |
| 2           | 9.5    | 0.2    | 11.791666666666666 |              | 1            |
------------------------------------------------------------------------------------