Improve documentation with configuration informaton

[google]

Improve documentation with configuration informaton

[hagbard]

Apologies for not spotting some of these lingering issues (I'm not getting the email notifications I expected for this project). To put it in perspective a bit, Flogger deliberately doesn't take on the responsibility for configuring logging. That has to remain up to the underlying system for which the backend is configured.

Using the default JDK backend, you configure logging via all the normal JDK logging mechanisms. The same is true for Log4J (which now has a backend thanks to Edwin and the Gerrit team).

I hope that answers your question (and I'll look at updating the docs accordingly).

[jbduncan]

@hagbard Hmm, good question!

I think that adding a link to the main page of the Flogger website somewhere would be a good first step (e.g. at the end of the one-line description at the top of the GitHub page), just so that the main documentation is a bit more visible. See the Truth GitHub page for an example of what I mean.

I think then doing something like the following would be good: consider adding a sentence or two to the opening paragraph of the README and the main page explaining briefly that Flogger is a "frontend" logging framework which delegates logging to JUL and other frameworks, similarly to SLF4J. So the sentence:

Flogger is a fluent logging API for Java. It supports a wide variety of features, and has many benefits over existing logging APIs.

may become:

Flogger is a fluent logging API for Java. It supports a wide variety of features, and has many benefits over existing logging APIs. But it is not its own dedicated logging framework; similarly to SLF4J, it delegates to your logging framework of choice.

I think you'd then need to clarify somewhere what Flogger not being "its own dedicated logging framework" means. Maybe a separate page of information similar to the benefits and best practices pages?

I'm admittedly unclear on what the connection between this issue and LoggerConfig is. Would you mind clarifying for me?

[fzakaria]

Yes -- I'm accustomed to structured logging (log4j / slf4j); it wasn't clear that the normal backend is "JUL".
Seems like a SLF4J bridge would be very useful to play nicely with the rest of the logging uses in the wild

[jbduncan]

@ronshapiro I'm not sure if you're the right person to ask, but is there anything that's blocking this task at the moment, or has the Guava/Flogger team just not had the time to look at it yet?

[hagbard]

@jbduncan where do you think adding new docs would make it clearest?

I've made a couple of changes in code docs for LoggerConfig (internally so far, but should be pushed in the next release). I regret making that class sound like it's a general configuration solution (it isn't).

[madorb]

Yes, what @jbduncan said, that's where i was confused when opening the initial ticket. It didn't seem to say anywhere whether it's just a frontend, or a frontend+backend - and calling it out right up front would be great IMO