More (and Structured) Logging in General

[ang-zeyu]

Moving the old and no longer applicable #133 over here

More examples (mostly info / debug level ones):

• When a plugin is used / registered / detected
• A page is built
• likely many more!

Also from #133:

At some point we should adopt a proper logging framework so that we can increase logging verbosity when we want to capture more info.

[kaixin-hc]

Hi! I was thinking about looking at this. What did you have in mind for a "proper logging framework" compared to what is available?

[ang-zeyu]

Hi @kaixin-hc, from what I gathered from #183 (comment), was thinking something like cli --log-level option.
"Logging framework" may be a little misleading as we currently already do use a very robust one (winston) that allows configuring individual log levels for different outputs (cli / file).

Think we could get @damithc to confirm as well!

[damithc]

Hi @kaixin-hc, from what I gathered from #183 (comment), was thinking something like cli --log-level option. "Logging framework" may be a little misleading as we currently already do use a very robust one (winston) that allows configuring individual log levels for different outputs (cli / file).

Think we could get @damithc to confirm as well!

You guys can enhance this aspect to meet the needs of devs e.g., to show debugging log messages if needed. As a user, I'm OK with the status quo.

[kaixin-hc]

I've recently seen quite a few issues raised about the logging, and with the discussions happening on the following issues I think it might be nice to make this a bigger over-arching issue that can track the progress of the other issues. Some links to consolidate the discussion happening across this repo:

• Better CLI console experience when encountering errors or other logs #1633 (Improving user experience with CLI errors)-- suggests
  • Having a progress bar that can not be visually disturbed by incoming logs (like apt-get's progress bar), pending tylt's great PR
  • reworking the organization of the logs, such as which outputs a stack trace and which doesn't
• Incorrect report of success when CLI commands actually fail #1863
  • Raises the incorrect logs which display build success when build actually fails
  • Mentions that some errors are displayed directly in the site + offers potential context for why
  • Suggests failing hard on build command

    • labelling d.hard as it requires thinking through the entire application architecture and error handling we have currently. We might also want to attempt this only after typescript migration of most files, to prevent silly regressions.

• Support more informative performance logging option for markbind serve #1008 Suggestion to implement more detailed performance logging (to help developers)
• Link reporting related (these have quite a bit of false positives):
• Moving intralink validation checks to a log file #1470 Suggestion to move logs from the CLI window to a logs file
• Improve broken link reporting #1418 (Improve broken link reporting)
  • Suggestion to document reasons for false positives as per this comment
  • Support validating #hashes for tags efficiently (not yet complete)
  • Warn users if PlantUML diagrams are found but Graphviz is not installed #1912 Related PR chooses to warn for not having graphviz, since this can potentially break puml diagrams, and follows the current link reporting idea of warning but not breaking the deployment

[tlylt]

Sharing a relevant article on writing better error messages. It's geared towards request errors but I think the explanation here is good:

https://wix-ux.com/when-life-gives-you-lemons-write-better-error-messages-46c5223e1a2f