In logging guide, DEBUG should not be a valid log level

[jclingan]

Describe the bug
DEBUG is not a valid log level as shown in the logging guide example. A valid log level should be shown.

In addition, the logging guide should document valid log levels: ALL, CONFIG, FINE, FINER, FINEST, INFO, OFF, SEVERE, WARNING. These should be documented in the description for each log level-related property so they also show up in the all-config guide.

[dmlloyd]

It should be valid. JBoss LogManager retrofits the Apache style levels into JUL, and our code generally uses them.

[stuartwdouglas]

The issue is that the config properties guide links to the JDK Level which does not list the JBoss logging levels. They should be documented somewhere.

[abelsromero]

Note the plugin for Intellij & and vscode marks DEBUG as error and does not show it.

[loicmathieu]

@abelsromero the issue with Intellij and VSCode autocompletion should comes to the fact that they hardcoded the list of possible levels from java.util.logging.Level and not from org.jboss.logmanager.Level that adds additional levels.

Can you report this to them ? I don't know if we can do something at Quarkus side.

[abelsromero]

Leaving plugins aside here. If I understand correctly the configuration is mapped here

quarkus/core/runtime/src/main/java/io/quarkus/runtime/logging/LogConfig.java

Line 37 in 369c6b4

public Level minLevel;

and there java.util.logging.Level is being used, not org.jboss.logmanager.Level.

quarkus/core/runtime/src/main/java/io/quarkus/runtime/logging/LogConfig.java

Line 4 in 369c6b4

import java.util.logging.Level;

[stuartwdouglas]

org.jboss.logmanager.Level extends java.util.logging.Level

[abelsromero]

I think I understand it and I am not saying is wrong, what I am tryng to express is that for someone going through the docs is really confusing. If the configuration is mapped to java.util.logging for extensibility, at least levels available should be better described.
This is my subjective experience (so take it witha grain of salt), in the Logging guide, at some point there is this list of levels described as "several" https://quarkus.io/guides/logging#log-levels with: FATAL, ERROR, WARN, INFO, DEBUG, TRACE.
But then in the description of the configuration properties below (https://quarkus.io/guides/logging#quarkus-log-logging-log-config_configuration) the type column points to java.util.logging.Level and the text mentions "JBoss Logging also adds [...] ERROR, INFO, TRACE". But in fact it adds FATAL, ERROR, DEBUG, TRACE.
Furthermore, INFO is present if both loggers and there's a WARNING and a WARN level.

So, these questions come to me:

• Is the jboss extension due to change in the future? If so, why the examples all use these levels?
• Should I stick with java.util.logging.Level just in case? If so, am I missing some feature if no using jboss?
• If on contrary, the intention is to use jboss logger, why then map the config type to utils?

[loicmathieu]

@abelsromero please see PR #10672 where I improve the logging doc, it should clarify things a little.

There is indeed two questions that worth investiguating:

• Why is there an INFO level added in JBoss Log Manager even so there is already one in JUL ?
• Why is the config type mapped to JUL, I try to change it to JBoss Log Manager and it worked (but I didn't commit that change for now).

Maybe @dmlloyd can answer those two questions ?

You cannot open issues on JBoss Log Manager Github repo so we cannot ask for the INFO level there ...

[dmlloyd]

@abelsromero please see PR #10672 where I improve the logging doc, it should clarify things a little.

There is indeed two questions that worth investiguating:

• Why is there an INFO level added in JBoss Log Manager even so there is already one in JUL ?

The answer to this question is in the essay down below.

• Why is the config type mapped to JUL, I try to change it to JBoss Log Manager and it worked (but I didn't commit that change for now).

The short answer is: CONFIG is not an Apache level. But see below.

You cannot open issues on JBoss Log Manager Github repo so we cannot ask for the INFO level there ...

That project still uses JIRA: https://issues.redhat.com/browse/LOGMGR

---

Here's the deal with log levels - a little history and context.

Way back at the dawn of time, when primitive humans were banging rocks together and the current version of the JBoss application server was 3.0, it used Log4j for logging. For various reasons, we ended up developing our own logging facade, at the time called "JBoss Commons Logging", which for this reason ended up following the Log4j standards for logging (including its levels: FATAL, ERROR, WARN, INFO, DEBUG, and TRACE).

Right around the same time, Java 1.4 was released, containing its own logging API - one which used a completely different scheme for levels (SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST). In the very, very small world of logging enthusiasts, this was quite an upheaval. When all was said and done though, most (if not all) widely used logging frameworks ended up settling on the Apache Log4j standard or a minor variation thereof.

Over time, the JBoss application server project (later to be renamed WildFly) developed a project-wide standard for logging of messages which includes i18n considerations, all still based on the Apache de-facto standard. But, a rift was opening in the form of projects originating from Sun (now Oracle) which for a while had a tendency to use the java.util.logging levels and API instead. Our initial tactic was to use a JUL-to-log4j bridge, but it had various disadvantages including having a slow/lossy tradeoff and not mapping levels very well. Eventually we changed tactics and developed the JBoss Log Manager, which did the opposite, taking all messages from every logging API and logging them through java.util.logging (but with many significant fixes and improvements), while preserving the original level.

But all of our standards (and now reams of documentation) were still based on the Apache standard, which at the time was still far more widely used than the JUL levels (and, AFAICT, still is). And this has not changed since this time. So JBoss Log Manager defines all logging, whenever possible, in terms of those standard levels. If you use the Log4j logging API, or Slf4j, or Apache Commons Logging, you're using those standard levels. The only time the standard levels aren't used is when a library uses JUL directly for whatever reason. As a result JBoss Log Manager has its own Level class which contains all of the Apache levels, which are the ones that are expected to be used in the vast majority of cases. It extends the JUL Level class only because doing so is a technical requirement in order for it to work at all.

As far as the Quarkus documentation goes: it was, in my view, an error (due to overzeal) to document anything other than the Apache levels. Those are the levels we expect users to use and configure. The JUL levels are worthy, perhaps, of a footnote, for cases where older Sun frameworks are used (for example) and the user needs to know how to map those levels on to the Apache ones for the purposes of configuring log categories. But this is one case where what is in the JDK is not really the standard that is used by the majority of developers. Documenting them as if they were serves only to add confusion.

[abelsromero]

That's far more than what I expected, thanks.
I added some totally optional comments on the PR. Mostly stylistic, I hope they don't come up as too nitpicky, feel free to dismiss them if you consider they don't apply.