folly/experimental/logging/README.md

   1 Overview
   2 --------
   3
   4 This is a flexible logging library for C++, targeted primarily at debug logging
   5 support.  It supports hierarchical log categories to easily control debug log
   6 levels.  It also aims to have minimal performance overhead for disabled log
   7 statements, making it possible to keep debug log statements throughout the code
   8 base, even in performance critical sections.  This allows debug log messages to
   9 be easily turned on for particular areas of the code at runtime when necessary
  10 to help debug an issue, without having to worry about the overhead of log
  11 messages during normal use.
  12
  13 Log Categories
  14 --------------
  15
  16 ## Log Category Names
  17
  18 All log messages get logged to a particular log category.  Log category names
  19 are hierarchical, separated by periods.  For instance, `folly.io` and
  20 `folly.futures` are both sub-categories of `folly`.  `folly.io.async` is a
  21 sub-category of `folly.io`.  The root category's name is the empty string.
  22
  23 ## Log Level Checks
  24
  25 When a message is logged to a given category, an admittance check is performed
  26 to see if the log message should be enabled.  The admittance check compares the
  27 log level of the message against the effective level of that category.
  28
  29 By default the effective level of a category is the minimum of its level and
  30 the level set for any of its parent categories.  This means that when you
  31 increase the log verbosity for a particular category you automatically turn up
  32 the verbosity for the entire tree of children categories underneath it.
  33
  34 For example, setting the log level for the `folly` category to `WARN` means
  35 that log messages to any sub-category under `folly` will be admitted if they
  36 have a level of `WARN` or higher.  If the level for `folly.io` is `DEBUG`, then
  37 messages to all categories under `folly.io` will admit `DEBUG` and higher
  38 messages, while the rest of the categories `folly` under folly would admit
  39 `WARN` and higher messages.
  40
  41 However, you can also configure specific log categories to turn off inheritance
  42 of their parent log levels.  This allows you to increase the log verbosity for
  43 a large category tree, but still use a lower verbosity for specific
  44 sub-categories.  For example, if the `folly` category's level is set to
  45 `DEBUG`, but you disable level inheritance for `folly.futures`, the
  46 `folly.futures` level will not use it's parent's `DEBUG` log level, and will
  47 only consider the level set locally on this category.
  48
  49 Once a log message is admitted, it is processed by the `LogCategory` where it
  50 was logged, as well as by all parent log categories, up to the root.
  51
  52 ## Log Handlers
  53
  54 `LogHandler` objects can be attached to a log category.  When a log message is
  55 received at a given log category it will be given to all `LogHandler` objects
  56 attached to that category.
  57
  58 `LogHandler` objects can perform arbitrary actions based on the log message.
  59 They may write the message to a local file, print it to `stderr` or `stdout`,
  60 or send the message to a remote logging service.
  61
  62 `LogHandlers` may perform their own additional log level check, but by default
  63 `LogHandlers` process all messages received at the category they are attached
  64 to.
  65
  66 Motivation
  67 ----------
  68
  69 The goal of this logging library is to provide a flexible, easy to use logging
  70 mechanism that allows debug log statements to be used liberally throughout a
  71 code base.
  72
  73 There are two primary design goals for this library:
  74
  75 1. Log statements should be cheap when disabled.
  76 2. It should be easy to control log levels for specific areas of the code base.
  77
  78 While there are a number of other logging libraries for C++, none of the ones I
  79 have seen fulfill both criteria.  The Google logging library (glog) satisfies
  80 the first goal, but not the second.  Most of the other log libraries I have
  81 examined satisfy the second goal, but not the first.
  82
  83 In particular, for item 1, disabled log statements should boil down to a single
  84 conditional check.  Arguments for the log message should not be evaluated if
  85 the log message is not enabled.  Unfortunately, this generally means that
  86 logging must be done using preprocessor macros.
  87
  88 Item 2 largely boils down to having hierarchical logging categories, to allow
  89 easily turning log levels up and down for specific sections of the code base.
  90 For instance, this allows a service to enable a higher log level for its
  91 primary functionality, while having slightly lower levels for libraries that it
  92 depends on.
  93
  94 Other Advantages
  95 ----------------
  96
  97 Beyond the primary goals mentioned above, this log library does have some other
  98 advantages over glog:
  99
 100 ## Support for using `folly::format()` to generate formatted log messages
 101
 102 Two separate mechanisms are provided for formatting log messages: basic
 103 concatenation of arguments into string (using `folly::to<std::string>()`),
 104 and more flexible formatting using `folly::format()`.  This provides convenient
 105 and type-safe mechanisms for formatting log messages.
 106
 107 ## Escapes unprintable characters in log messages by default.
 108
 109 This makes it safer to safer to log arbitrary input data, without worrying if
 110 the data may contain potentially malicious terminal escape sequences.
 111
 112 For instance, this helps avoid vulnerabilities like CVE-2013-1862 and
 113 CVE-2009-4496.
 114
 115 # Support for handling multi-line log messages
 116
 117 The LogMessage class indicates if the message contains internal newlines,
 118 making it easier for handlers to add a log header to each line of the message,
 119 avoiding subsequent lines that do not start with the correct log header.