Configuring esapi to use an existing logger implementation

[chuckdumont]

Our application uses java.util.logging and handles logging configuration (setting handlers, log levels, etc.). When using esapi with JUL logging, the application's configured log levels are reset by esap. How can we configure esapi to use the java.util.logging APIs to log events, but not try to set it's own logging config?

[jeremiahjstacey]

The ESAPI JavaLogFactory attempts to configure the instance through the esapi-java-logging.properties file.

An optional default configuration for that properties file is provided in the esapi configuration directory here.

Fair to assume that the esapi project default is not your system configuration.

The easiest option I see is to update the esapi-java-logging.properties file to be the configuration you're expecting. You can do that by either updating the file in-place or by creating a sim-link on your system to your preferred configuration settings.

There may be a case to create an issue in the project to make that configuration file optional, which would require a code change. I believe that would also address the problem, but I'd be interested in whether @kwwall or @xeno6696 would have concerns with that implementation change.

[chuckdumont]

The problem is, we don't want ESAPI to configure the logger. We're doing it ourselves.

I ended up copying the implementation of JavaLogFactory and removing the call to readLoggerConfiguration and pointing ESAPI.logger to our modified implementation.

[jeremiahjstacey]

Created Issue #710 for consideration in the project. I believe that change would have mitigated this use case without requiring changes on your part.

[xeno6696]

I can't see any reason why we can't do this. Obviously we'd have to keep the safe harbor idea in mind so probably best to implement with a -D property that would apply to the application runtime, and leave the default behavior as-is. If people override ESAPI defaults, we want this to be explicit.

[chuckdumont]

I don’t like the -D property idea because it affects deployment of the application. I think a better solution would be magic content in esapi-java-logging.properties (e.g. <noconfig>) or else a new config property (e.g. ESAPI.configureLogging=false).

[jeremiahjstacey]

For the reasons listed below, I strongly believe that the only change required is the code adjustment listed in #710

Removing the requirement of a log configuration property file actually adds more flexibility to the Java Logging configuration. It will not break any existing clients, and actually enables a wider range of capability including allowing for multiple configuration file formats (.properties, .xml, or in-code solutions).

If no configuration is specified, Java Logging still works and provides the default log content appropriately. If users want customization, then they may customize it through the optional configuration file in ESAPI, or by any other mechanism supported by the Java Logging API.

There is no break for backwards compatibility with this change. At this point I'm thinking of this more as a bug correction than anything else. The file requirement was/is superfluous and only adds complexity for using the ESAPI library.

Please reconsider adding another property/configuration for this adjustment.

[chuckdumont]

@jeremiahjstacey - your suggestion is fine as far as I'm concerned. I was just proposing alternatives to @xeno6696's suggestion since he didn't seem to like your proposal.

[kwwall]

Sorry arriving late to the party. I've been busy with other things.

The major problem that I see with this proposal, as outlined here and in issue #710, is when ESAPI users eventually stop using Log4J 1 for logging with ESAPI and switch to using JUL for ESAPI logging. (I figure most will switch to SLF4J, but some will just opt to go with the ESAPI default, namely JUL.)

It is not that surprising that some developers fail to read all the detailed documentation about logging in the Javadoc, our wiki pages, and in our release notes. (We have already seen this when we made changes a few years back.) But as a result of failing to pay attention to documentation details, they very likely may fail to deploy the esapi-java-logging.properties file from the ESAPI configuration jar. If iwe make the changes outlined in issue #710, there will be cases where developers will forget to deploy the esapi-java-logging.properties file, but after changes to implement issue #710, they will no longer have any ConfigurationException message and exception stack trace to guide them. Rather, it would likely result in a much more confusing exception a bit latter on, probably when JUL actually attempts to log something and finds itself not configured at all.

Also, this whole scenario is further complicated by the fact that ESAPI often does some logging of its own very early on in the application. If we rely on the application to be responsible for this, it gets complicated, because that JUL configuration by the application is going to have to be completed prior to any call of the ESAPI logger, including the (hidden) internal calls that it makes. For some JavaEE application servers, that would almost mean that the JUL configuration would have to be done in some JavaEE application startup class,; e.g., using something like the @startup annotation:

@Startup
@Singleton
public class MyJULStartupConfiguration {
    // ... my JUL configuration loaded here ...
}

So documenting that (and more so, expecting developers using ESAPI to read and heed it) is going to be non-intuitive and I think it is likely to cause lots of confusion in the future.

The other thing that I don't like about this proposal is that it makes it different than how we approach configuration for both Log4J and SLF4J logging. Those differences in code make the code marginally harder to maintain, especially if we don't carefully document the reasons for those differences. So ideally, whatever we do in one of the loggers, it should operate in a similar manner with the other loggers. That makes it easier for developers to learn and transition from using one logger to another.

The bottom line is, just because it is easy to code doesn't mean it is the right thing to do. I think we need to worry about the edge cases here and in particular how developers not named @chuckdumont might accidentally misconfigure something and be left without a potentially helpful Exception message.

I do think that @jeremiahjstacey was spot-on in his initial analysis, that you should just make sure that you either rename or link or symlink your JUL configuration file so that ESAPI can find the esapi-java-logging.properties file. In my opinion, the only rationale of why this might not work is if there is some sort of JUL configuration that can't be done via a configuration file and can only be accomplished programmatically. (@chuckdumont - If that is the case, let us know what it can't do that you are attempting, but so far, you have not communicated such.) Short of that, we could add a new property in the ESAPI properties file indicate for each of ESAPI's Logger types where it can find its configuration file (in case people want to rename it), but at least that would allow it to be consistent across all the loggers to some degree. (By default, that property would default to whatever it is now if it is not set in ESAPI.properties.)

[chuckdumont]

@kwwall - our application configures JUL per our own configuration file well before esapi is ever loaded. Currently, loading esapi causes our logging configuration to be overwritten by esapi's logging configuration. This is clearly not desirable. We want esapi to use the JUL api to log events, but to use the logging configuration that we have already set up.

I propose a new property in ESAPI.properties to configure this (e.g. ESAPI.configureLogging=false). The default value can be true so that current behavior will not change. Only users who don't want ESAPI messing with the logging configuration would specify this property.

This option should be easy to implement for all logging frameworks.

[kwwall]

@chuckdumont - I didn't say that what was occurring was desirable and certainly didn't mean to imply that. But most developers would solve this by either copying their JUL configuration file to esapi-java-logging.properties in the same directory where your ESAPI.properties file gets picked up, OR by making esapi-java-logging.properties a symbolic or hard link to point to your JUL configuration file. That approach requires ZERO code changes. That is essentially what Jeremiah suggested originally.

So why will that approach not work for you?

[chuckdumont]

@kwwall - our logging config file is user editable and we frequently instruct customers to set logging levels in the config file to help diagnose problems. Following your suggestion, we would need to instruct them to edit two files instead of just one. The symlink approach is not desirable because it unnecessarily complicates deployment.

Since the feature in our app that uses esapi is optional and installed separately, we cannot (and don't want to) rely on esapi to configure the logger for us. We want to control the logger configuration ourselves with our own logging config file and don't want third-party libraries trying to take over that role.

[jeremiahjstacey]

We've done a bit more looking into the Java LogManager, and I believe a path forward has been identified.

Per the javadoc on the LogManager class, two existing properties may be used to centralize the log configuration:

In addition, the LogManager uses two optional system properties that allow more control over reading the initial configuration:

• "java.util.logging.config.class"
• "java.util.logging.config.file"

These two properties may be set via the Preferences API, or as command line property definitions to the "java" command, or as system property definitions passed to JNI_CreateJavaVM.

The ESAPI JavaLogFactory should not conflict with those settings, if they are defined.

#710 is being updated to account for this intent. If the LogManager property exists in the environment, then the ESAPI configuration will not be applied.

@chuckdumont, I believe this will fulfill the use case you're wanting in future releases while still allowing ESAPI to enforce behavior if none is defined.

Specifically identifying the intent such that:
If either supported configuration property for the LogManager class exists in the runtime, ESAPI will not apply configuration settings from the esapi-java-logging.properties file

[chuckdumont]

@jeremiahjstacey - this sounds fine, but please also support an ESAPI.properties setting for doing this as well. That way, applications can consume esapi without having to change the way they configure logging. Thanks.

[kwwall]

@chuckdumont wrote:

@jeremiahjstacey - this sounds fine, but please also support an ESAPI.properties setting for doing this as well. That way, applications can consume esapi without having to change the way they configure logging. Thanks.

See reply in #710 (comment)