usablity feedback of absl logging and flag

[Ming Zhao]

Hi,

Thank you for making absl available to the open source world. 

A few suggestions about the documentation and the overall design:

1. It will be nice to have more comprehensive example in the guide, for example:

https://abseil.io/docs/cpp/guides/logging, it will be nice to add:

  * which header to include

  * how to build it with bazel or cmake.

2. For logging, compared to the original glog, it's unclear where the log goes when --stderrthreshold=0 is not set.

3. I like the finegrained modules absl provides. However it will be also nice to provide some scaffolding to give the external users an easier time, without tribe knowledge you folks may take for granted, it could non trivial effort to put together this:

#include "absl/flags/flag.h"
#include "absl/flags/parse.h"
#include "absl/log/initialize.h"
#include "absl/log/log.h"
#include "absl/strings/str_format.h"

ABSL_FLAG(std::string, foo, "world", "Whom to greet");

int main(int argc, char *argv[]) {
  absl::ParseCommandLine(argc, argv);
  absl::InitializeLog();
  LOG(INFO) << "Hello " << absl::GetFlag(FLAGS_foo);
  return 0;
}

As well as a bunch of deps to use in bazel BUILD:

    deps = [
      "@com_google_absl//absl/flags:flag",
      "@com_google_absl//absl/flags:parse",
      "@com_google_absl//absl/log",
      "@com_google_absl//absl/log:flags",      
      "@com_google_absl//absl/log:initialize",
    ]

Apprecaite that abseil is keeping getting better.

Ming

[Tom Manshreck (ШРЭК)]

Hi Ming,

Thanks for your feedback. We do read it! 

Regarding the headers, we did intentionally decide at one point not to specify the exact headers in all of our code samples for a few reasons. One reason is that we don't necessarily want the samples to be meant as standalone, runnable code samples. Another is because they rapidly become out of date when code is shifted around. This has been especially obvious around logging and flags, because those libraries have been refactored relatively recently. However, we have thought about noting the included headers in the body of the documentation (in this case at https://abseil.io/docs/cpp/guides/logging). But we are certainly open to the idea and are exploring it.

Another reason is that we more often rely on tooling to make these checks. Check out https://include-what-you-use.org/ for tooling that can identify which headers to include.

Including build targets is more problematic, because we support two different build systems (Bazel and CMake) while also allowing other build systems. In this case, we think the actual build files (be they a BUILD.bazel or a CMakeLists.txt file) are better documentation for that sort of thing.

Regarding your second question, if --stderrthreshold=0 is not set, the default behavior is to log ERROR and FATAL logs to stderr. If you use the default LogSink, that is the behavior you will get. (If you set up any additional LogSinks, you will of course get the behavior you configure with those as well.)

We should make this clearer in the docs, btw. So thanks for raising this. I will be updating those docs in the next few months.

-Tom

--
You received this message because you are subscribed to the Google Groups "Abseil.io" group.
To unsubscribe from this group and stop receiving emails from it, send an email to abseil-io+...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/abseil-io/CAN0GiO2zqS8cTvtid8uxtacL%2BAAYv1GBnX4G5XCH%2B12GrqxP3Q%40mail.gmail.com.

--

Tom Manshreck
Google Cambridge

355 Main St

4CC-4A130C

Cambridge, MA 02142