Hi Piotr,
In general, talking about API signatures without (pseudo)-Javadoc is not great,
there is too much wrong for miscommunication or plain old guesing.
> Set<String> getSupportedLevels();
It is not helpful to return a set IMO . This should be a list in a documented
order from one min or max level of specificity to the other end.
> Object getLoggerContext();
Returning Object is not helpful but I don't know how to solve that or if the
API is needed at all.
I'm not a fan of Optional in general FWIW.
> Optional<String> getLoggerLevel(String loggerName);
> void setLoggerLevel(String loggerName, @Nullable String level);
Since you can only set the level on a Logger, using "Logger" in the API names
is superfluous.
> static LoggingConfigurationAdmin getInstance(Object token,
> ClassLoader classLoader);
> static LoggingConfigurationAdmin getInstance(Object token);
Why do I need those AND getLoggerContext()?
I though the point of this interface was a one-stop-shop. What's
LoggingConfigurationAdmin doing for me?
> 1. How should this API be called? I think that the name should NOT
> contain "Log4j", which would cause the same confusion as with Log4j API.
> Users would assume that the API only works with Log4j Core.
Do you mean the Maven artifact ID? How about "logging-admin"?
> 2. How do we prevent users from abusing this API?
You don't. Or, you don't deliver the JAR with your app. You can't stop users
from hacking, formally or informally. Reflection is always around the corner to
boot.
> 4. What should be the lifecycle of this API and where should it live?
KISS 101: Not ANOTHER repo and version numbering system. Match Log4j and be
done with it. Unless... you want to make this a new component as a sibling to
Apache Logging Services Log4j: Apache Logging Services Admin.
HTH,
Gary
On 2024/11/02 19:42:15 "Piotr P. Karwasz" wrote:
> Hi all,
>
> On 31.10.2024 16:11, Piotr P. Karwasz wrote:
> > Currently we have `o.a.l.l.c.config.Configurator` that allows level
> > manipulation, but this is a Log4j Core specific class, which only
> > works with Log4j Core. We could publish a small API (e.g. called
> > LogAdmin) that allows to:
> >
> > * list the configured level of all loggers,
> >
> > * get the configured level of a single logger,
> >
> > * set the configured level of a single logger.
> >
> I have attempted a first sketch of the Apache Logging Admin API in my
> personal repo[1], which ended up having the following methods (the
> Javadoc is in the repo):
>
> public interface LoggingConfigurationAdmin {
> Object getLoggerContext();
> Set<String> getSupportedLevels();
> Map<String, Optional<String>> getLoggerLevels();
> Optional<String> getLoggerLevel(String loggerName);
> void setLoggerLevel(String loggerName, @Nullable String level);
> static LoggingConfigurationAdmin getInstance(Object token,
> ClassLoader classLoader);
> static LoggingConfigurationAdmin getInstance(Object token);
> }
>
> While the implementation is rather straightforward, there are some
> aspects we should think about:
>
> 1. How should this API be called? I think that the name should NOT
> contain "Log4j", which would cause the same confusion as with Log4j API.
> Users would assume that the API only works with Log4j Core.
>
> 2. How do we prevent users from abusing this API? I call "abuse" the
> kind of help some libraries provide to application developers, by
> "improving" the logging configuration behind the application developer's
> back. As an attempt to solve this problem I added a "security token" to
> the `getInstance` method. It works like the token used in Tomcat's JNDI
> implementation[2]: the first caller chooses the token, all subsequent
> calls to `getInstance` must provide the same token.
>
> 3. Should we provide some parameters (in the example above
> `ClassLoader`) to help implementations choose the correct logger context
> to modify? Only the Log4j API offers such a parameter to retrieve the
> appropriate `LoggerContext` and in practice the parameter is only used
> by `ClassLoaderContextSelector`, which usually infers the value of the
> parameter anyway.
>
> 4. What should be the lifecycle of this API and where should it live? I
> would prefer to keep it in a separate repo, with a separate lifecycle
> (start with version `0.1.0`, so we can make breaking changes in the
> incubating phase) and possibly use a different Maven `groupId` (e.g.
> `org.apache.logging.admin`).
>
> 5. Where should the implementations of this API live? It would be nice
> to add implementations of this API directly to the logging
> implementation artifacts (Log4j Core and Logback), but there is a JPMS
> catch: if a JPMS module exports a service, the dependency that defines
> the service type can NOT be optional! Therefore Log4j Core (and maybe
> Logback) would need to have a hard dependency on this API.
>
> What do you think?
>
> Piotr
>
> [1] https://github.com/ppkarwasz/logging-admin
>
> [2]
> https://tomcat.apache.org/tomcat-11.0-doc/api/org/apache/naming/ContextBindings.html
>
>
>
