What should Mill's logging framework do?

[lihaoyi]

Opening this as a follow up from #3603, so we can have a place for continued discussion not limited to the original cleanup. The basic question is: various logging frameworks have a range of different features, which features should we copy in Mill's logging API?

1. @lolgab already mentioned filtering by log levels. We basically have a rudimentary version of that via --debug, but filtering by other log levels makes sense too?

2. Should there be a TRACE level separate from ERROR? Or user configurable log levels?

3. Should we have special handling for JSON logging or other structured logs?

4. Should log lines have timestamps? On one hand it's convenient when looking at historical logs, on the other hand it's super verbose and irrelevant in environments where timestamps are available separately (e.g. iTerm lets you pull up timestamps on the right for any console output, some CI systems automatically make timestamps available for any stored logs)

5. Should log lines automatically capture file/class names and line numbers like pprint.log does?

6. Should colors be configurable, as discussed on Configurable colors #471 from @lefou?

   • On this topic, should logs to files preserve colors, not-add-colors (but keep the ones that users add to logs), or actively strip colors even colors that users add themselves?

Are there any other things that logging frameworks do that Mill is missing? And perhaps at a high level, how do we make a decision about what logging features Mill should or shouldn't support?

[lolgab]

@lolgab already mentioned filtering by log levels. We basically have a rudimentary version of that via --debug, but filtering by other log levels makes sense too?

I have one use case that I can share. Sometimes, working with legacy codebases updated to newer Scala versions, you get thousands of warnings. When you have one error and 1000 warnings it's hard to read the error from the command line.
In Sbt I do set Global / logLevel := Level.Error and then I can see only the one error from the command line and have a clean output.

[lefou]

I think we want to separate two things here:

• logging
• build output

Where is the distinction?

Logging

Logging is everything you might need once you need to debug some code. It can become pretty verbose and might need to contain data that nobody wants to see on the cli. Hence we typically log into a file. Depending on the use-case we log to a server. And to avoid any kind of log injection or to be able to further process logs, we want to log as JSON. Since this is all pretty standard tooling, we should use standard tooling for it. The Standard API of Slf4j. There are some Scala wrappers around it, my most favorite is log4s. But I think we should provide our own wrapper (maybe mirror log4s), using macros to avoid any extra overhead. Beside the API, there needs to be a logging backend. We should bundle and pre-configure one by default and allow users to re-configure it or replace it. I'd opt for logback, since that what I used most of the time. It has a good security record and good performance. It has many options like capturing the locations of the log messages, diagnostic contexts or enhancing stack traces with jar/version information. We should by default log into a file under out. Any user-configuration need to be applied to a log config file. I'd not provide any CLI options for now.

Once we properly setup a the logging API, we also benefit for it being a standard and will collect all the log messages of the used libraries in our log file, which can help to better understand what's going on.

Since we do a lot of classloaders, we need to find out some way, to collect those log messages too. Maybe it's enough to load the log API from the parent classloader.

Build Output

This is the output meant to be visible on the CLI. Message are typically printed into context, so no timestamps, log levels, stack traces or other stuff is really needed. It should be stable and pregnant. This is, what we have our current T.log API for. (We should forward all user-visible output to the loggging API too, so we can navigate more easily in the log files.) Technically, we don't need any changes for this API. Maybe we want to discuss the name, as we are going to provide another log API and having two log APIs with different semantics isn't nice. We probably want to have a cli switch to let the user select the levels. Either as a threshold, e.g. show everything with warn-level and above, or an option to enable each level separately. I think a threshold is enough. --log-level info could be the default. Our current --debug would be equivalent to log-level debug.

I still think we should have configurable colors, and it's on my TO-DO list for this year, if nobody else tackles it. I need to run Mill in a light console, since when I use a dark one, which I would prefer, I can't read the dark blue output which we use for progress-count and info messages.