log4j-core: Name/description not so clear

[Chealer]

log4j-core has the following name and description:

  <name>Apache Log4j Core</name>
  <description>The Apache Log4j Implementation</description>

Software products often call a component core when that component is essential to all other components. This pattern can be seen in numerous Debian packages, notably in the nginx source package, which generates binary packages nginx-core and nginx-full, the latter depending on the former.

My understanding is that this is not really the case with Log4j Core, since log4j-api does not need log4j-core, which means its name could be misleading (I believe it did confuse me for one). I would therefore recommend setting a name and a description as clear as possible, focusing on "implementation" rather than "core".

I would suggest the following, but this comes from someone who is not knowledgeable about either Log4j or its ecosystem. My suggestion is based on my understanding that "core" means "core of the implementation" but considering that the API Separation page refers repeatedly to the "core implementation", that may be wrong.

  <name>Apache Log4j Implementation Core</name>
  <description>Core of Apache Log4j's reference implementation of the Log4j facade API. This implementation provides a full-featured logging library which can also serve as a Simple Logging Facade for Java (SLF4J) provider or as a logging implementation of another logging API.</description>

[rgoers]

Log4j API is the interface applications code to and will use its built in SimpleLogger implementation if none is provided, but that implementation is too simplistic for the vast majority of users.

Log4j Core is the implementation of the API. It is really the only dependency you need to perform logging for a large portion of the Log4j user base. All the other components are add-on functionality that provides enhancements for special use cases.

As such, I don't really see anything wrong with its name. Calling it the "implementation core" is misleading as it gives the impression that something else might be required. Log4j Core also cannot act as a provider for SLF4J by itself. It requires for log4j-slf4j-impl or log4j-sfl4j2-impl and log4j-api to do that.

I'm inclined to close this as I don't see how it provides any benefit.

[vy]

Thanks for the heads up @Chealer! :bow: Please keep these feedback coming! :100: I have improved the artifact description in f4da84f8004519bbe43a8ecf7655d735a13fcbe1. We will further improve the situation in #1468.

[Chealer]

My pleasure @vy, thank you very much for this great improvement. Here is a suggestion based on your version:

This package contains the core of the Log4j API's reference implementation. That implementation provides an industrial-grade and versatile library bundling a rich set of components to assist various logging use cases and environments. It notably allows:

• writing to files, network sockets and databases and sending emails;
• formatting output as CSV, HTML, JSON, etc;
• event filtering, which can be configured using frequency, time, regular expressions, scripts, etc.

While this implementation contains other packages extending this one, the core alone generally suffices. It also contains several extension points to introduce custom components, if needed.

I left Syslog out because I believe it's a protocol, but I don't know much about it, so feel free to re-add it. Otherwise, I mostly simplified, streamlined, slightly rectified the language and explained the meaning of "core".

[Chealer]

@rgoers I am sorry for replying so late. Thank you for your reply.

As such, I don't really see anything wrong with its name. Calling it the "implementation core" is misleading as it gives the impression that something else might be required.

The issue is non-trivial and I have limited capacity to advise (I haven't worked with Log4j at all this year), but if my understanding is correct, something else might indeed be required in some cases, although that depends on how "require" is defined. If logging to MongoDB is considered required in some contexts, then such users do require log4j-mongodb.

I cannot make sense of the name "core" if it isn't for these extensions. I guess the fundamental problem here is that the meaning of "core" is not documented anywhere.

Once that's done, it should also be verified that the terminology is coherent. For example, if log4j-mongodb is considered as part of the RI, then the MongoDB appender's documentation shouldn't state that "The MongoDB Appender is dependent on the Log4j 2 API and implementation". It should rather say it depends on the implementation's core.

That being said, my suggestion to change the name element was wrong. Unless the project itself is renamed, the name should stay as it is. I guess I was confusing the name field with a short description, but I see that the POM (version 4) doesn't support distinguishing between short and extended descriptions. Sorry about that

[ppkarwasz]

I cannot make sense of the name "core" if it isn't for these extensions. I guess the fundamental problem here is that the meaning of "core" is not documented anywhere.

As far as I understand log4j-core was named after logback-core. We discussed renaming it many times (e.g. in this thread), but we never reached a consensus.

Personally I use "Log4j Core" as name of the reference implementation.

[Chealer]

Thank you very much for all this information as well as for starting that most interesting―albeit unfortunate―thread @ppkarwasz . It's a shame if renaming the artifact identifier is so challenging in this case, but I think @jvz's suggestion to change the actual name should be considered.

I recommend to either:

1. rename
2. or document what "Log4j Core"/log4j-core is...
   1. and probably remove the name element from the POM

[vy]

pom.xml description is not intended to be a fully-fledged documentation, but a high-level overview. I think we strike a good balance in being-short-yet-still-informative, thanks to your feedback. I am happy with the current state. I suggest, if deemed necessary, we move the discussion of further improvements to the website once we start working on the referenced tickets.

[Chealer]

Of course @vy The above was not saying that documentation should be in pom.xml. It can be documented in there, but for sure it is more important to document on the website.

pom.xml's description does dig into a few details though, so if the definition of Log4j Core is short, it would make a lot of sense to put it there.