search

google / flogger

A Fluent Logging API for Java
Apache License 2.0
1.45k stars 123 forks source link

Improve documentation with configuration informaton #16

Open madorb opened 6 years ago

madorb commented 6 years ago

From the existing documentation it is not clear to me if flogger is intended mostly as a replacement for the logging api (slf4j) or also for the logging backend (logback/log4j), or both.

The documentation focuses quite convincingly on why this is a better API, but does not seem to give any information about how to configure the backend (log appenders, formatting, MDC etc.). It also doesn't mention anything about whether it's recommended to use an alternate backend, and if so, how it would be accomplished.

Perhaps I've missed something, but could you possibly either point me to the existing docs i missed, or clarify some of the above? Thanks much!

fzakaria commented 6 years ago

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 commented 6 years ago

@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 commented 5 years ago

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).

hagbard commented 5 years ago

@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).

jbduncan commented 5 years ago

@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.

image

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?

madorb commented 5 years ago

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