Better documentation of advantages of Flogger compared to JDK and other logging APIs

[google]

Better documentation of advantages of Flogger compared to JDK and other logging APIs

[kevinb9n]

If that information is hard to find, then we still have a bug here.

However, it appears to me that the main flogger page links to that page 5 times in its first two short sections. I usually am reluctant to conclude "we're already doing enough", but that does seem to be the case.

[deadmoose]

since even against a no-op call site, you are still creating the Object[] for the invocation? Or am I missing something fundamental here?

It's addressed in more detail in the docs: https://google.github.io/flogger/anatomy.html#avoiding-varargs

But TLDR: The API really does enumerate a giant pile of signatures so you're almost certainly calling one of those instead of needing to fallback to varargs

With the fluent api, you're able to have "only" those eleventy billion log() methods versus adding another dimension and having eleventy billion logFine()s plus another eleventy billion logInfo()s plus... (And then any other dimensions you want to bring into the mix like including a causing Throwable, the rate limiting, etc)

[netdpb]

There's documentation of this here: https://google.github.io/flogger/benefits

[cpovirk]

Reopening to argue that we could do more here -- which is not to say that it needs to be a priority.

First, to reemphasize the last part of this sentence: I don't see any need to justify Flogger's existence: It solves problems that Google has, and by open sourcing it, we've made it available to both Google-run open-source projects and other potential users. That's a huge accomplishment for the past 8+ years.

So my framing, again, is that, if we do want to make the case to casual users for wider use, then we could take some actions to better highlight what Flogger has to offer. For example:

• We do link to /benefits from many places, but one particular place that we don't link to it from is Yet another logging API? That would make a natural point for yet another link :)
• We refer to Flogger as a "logging API." That is of course accurate :) It is also deceptively precise: It means that Flogger is not a backend. This distinguishes Flogger from many other logging "libraries" or "frameworks" -- terms that readers might casually think of as no different from "APIs."
• The distinction between "API" and "backend" probably leads to other questions: Why all the talk about varargs and boxing when other logging frameworks talk about things like asynchrony (LMAX Disruptor!)?
• Our main comparison is to the JDK logger. That's a comparison that is useful to have (compare our comparison of Truth to plain assertEquals), but if we want to answer the question "Yet another logging API?" then I think we should additionally include comparisons to slf4j and log4j APIs, which avoid the JDK's Throwable/not-Throwable ambiguity and provide lazy Supplier-based message construction (which I assume is still often slower and less convenient than Flogger's many overloads -- and that would be great to say!).

[jaredstehler]

Apologies for a tangential nit, please feel free to ignore this, but I am struggling to wrap my head around how the fluent api avoids for varargs (from the "benefits" doc):

Vararg methods require a new Object[] to be allocated and filled before the method can be invoked

since even against a no-op call site, you are still creating the Object[] for the invocation? Or am I missing something fundamental here?

[cpovirk]

A teammate just shared https://tersesystems.com/blog/2022/01/02/echopraxia-a-better-java-logging-api/. For purposes of this thread, there may be some things to mine out of that post and its links. The one that caught my eye was https://github.com/obsidiandynamics/zerolog#okay-arent-there-enough-fa%C3%A7ades-already