folly/experimental/logging/docs/Comparisons.md

   1 # Comparing `folly::logging` to other log libraries
   2
   3 This document attempts to briefly describe the differences between the folly
   4 logging library and other C++ logging libraries.  This is not necessarily
   5 comprehensive, and may become out of date as libraries change.
   6
   7 ## [Google Logging (glog)](https://github.com/google/glog)
   8
   9 The folly logging library is similar to glog in many ways.
  10
  11 Like folly logging, glog also provides very cheap debug log messages with its
  12 `VLOG` macro.  (However, the glog `LOG` macro is not lazy, and always evaluates
  13 its arguments, even if the log message is disabled.)
  14
  15 The primary difference between folly logging and glog is that folly offers more
  16 flexibility in turning debug messages on or off.  The `VLOG()` macros can be
  17 enabled or disabled on per-file basis through a `--vmodule` command line flag
  18 on non-Windows platforms.  This flag does support regular expressions to match
  19 groups of files, but the expression only applies to the last component of the
  20 file name.  This makes it more difficult to control logging for specific
  21 libraries and subcomponents of a project.
  22
  23 Other advantages of folly logging over glog:
  24
  25 * Logging I/O can be performed in a separate thread.  glog performs all logging
  26   I/O in the thread that generated the log message.  This can block processing
  27   while waiting for logging I/O to complete.
  28 * Unprintable characters in multi-line log messages are escaped by default.
  29   This helps avoid problematic or dangerous terminal escape sequences from
  30   appearing in log messages.
  31 * Better support for multi-line log messages.  Folly logging adds a log message
  32   header after each internal new line in log messages.
  33 * Full functionality on Windows.  The `VLOG()` macro from `glog` has somewhat
  34   diminished functionality on Windows, since it cannot be controlled on a
  35   per-module basis.
  36
  37 Advantages of glog over folly logging:
  38
  39 * Smaller generated code size.  Due to automatically picking a log category
  40   name, folly logging's `XLOG()` macros currently result in slightly larger
  41   generated code compared to `VLOG()`.
  42
  43 ## Log4j Clones
  44
  45 There are a number of Log4j-like libraries for C++ (log4cxx, log4cpp,
  46 log4cplus).
  47
  48 Conceptually folly logging behaves similarly to most of these libraries.  Much
  49 of folly logging's hierarchical log category behavior was modeled after log4j
  50 functionality, like these libraries.
  51
  52 The main difference between folly logging and most of these libraries is
  53 low overhead for disabled log messages.  The folly logging code ensures that
  54 disabled log messages boil down to a single conditional level check.  Most of
  55 the other C++ log4j clones always evaluate log message arguments, and some also
  56 perform more complex hierarchical log level checks at log time.