folly/experimental/logging/docs/Overview.md

   1 # The Folly Logging Library
   2
   3 `folly::logging` is a logging library for C++.
   4
   5 It allows configurable logging of text-based messages, and pays special
   6 attention to supporting debug logging.
   7
   8 It has two primary goals:
   9
  10 1. Very cheap debug log statements
  11 2. Configurable, hierarchical log categories
  12
  13 Together these two features make it possible to leave lots of debug log
  14 statements present in production code with little overhead, and to then easily
  15 turn on debug messages for specific parts of the code base at runtime when
  16 troubleshooting.
  17
  18 # Usage
  19
  20 The [Usage](Usage.md) document provides a overview of how to use the logging
  21 library.  The [Log Categories](LogCategories.md) document describes the basic
  22 behavior of log categories.
  23
  24 # Features
  25
  26 ## Very cheap debug log statements
  27
  28 Folly logging statements normally boil down to a single conditional `if` check
  29 when the log message is disabled.  The arguments to be logged are evaluated
  30 lazily, and are never evaluated if the log message is disabled.
  31
  32 This makes it possible to leave debug log statements present even in fairly hot
  33 code paths with minimal performance impact.
  34
  35 ## Hierarchical log categories
  36
  37 Folly logging uses a hierarchical log category model, similar to the one
  38 popularized by [Apache Log4j](https://logging.apache.org/log4j/)
  39
  40 See the [Log Categories](LogCategories.md) document for a more complete
  41 description of how log categories work.
  42
  43 This model makes it easy to control the logging levels for specific portions of
  44 the code.  Specific category settings can be changed to enable log messages in
  45 specific files or specific sections of the code, and settings on higher level
  46 categories can be adjusted to easily enable or disable log messages for larger
  47 sections of the code.
  48
  49 This also makes it easy for teams to run their programs with elevated log
  50 levels for code they maintain, while turning down potentially noisy messages
  51 from libraries they depend on.
  52
  53 ## Automatically chosen log category names
  54
  55 Picking good log category names and consistently using them throughout the code
  56 base can sometimes be a challenge with log4j-style logging libraries.  Folly
  57 logging provides an `XLOG()` macro that automatically picks a log category name
  58 based on the current filename, eliminating the need for programmers to worry
  59 about log category names in most cases.
  60
  61 The `XLOG()` macro chooses a log category name based on the source file path,
  62 with directory separators replaced by `.`.  This allows log categories to
  63 re-use the directory hierarchy decisions that have already been made.
  64
  65 ## Asynchronous I/O
  66
  67 Folly logging provide log handlers that perform I/O asynchronously in a
  68 separate thread, to avoid slowing down your main program threads if log
  69 messages are being generated faster than they can be written to the output file
  70 or stream.  These asynchronous log writers will drop messages rather than
  71 slowing down your main processing threads if log messages are being generated
  72 faster than they can be consumed.
  73
  74 Performing I/O directly in the thread that generated the log message can often
  75 be problematic, particularly if an unexpected event or configuration change
  76 suddenly makes your code log more messages than normal.
  77
  78 This behavior is easily configurable, so that you can choose the best trade-off
  79 for your program (possibly dropping some messages vs possibly blocking threads
  80 on logging I/O).
  81
  82 ## Support for folly::format()
  83
  84 The `XLOGF()` and `FB_LOGF()` macros format their arguments using
  85 `folly::format()`.  This allows log statements to use the powerful Python-like
  86 format syntax supported by
  87 [`folly::format()`](https://github.com/facebook/folly/blob/master/folly/docs/Format.md)
  88
  89 Additionally he `XLOG()` and `FB_LOG()` macros concatenate any log arguments
  90 using `folly::to<string>()`, and also accept arguments via iostream-style `<<`
  91 syntax.
  92
  93 ## Safe handling of unprintable characters
  94
  95 The folly logging framework automatically escapes unprintable characters in log
  96 messages by default.  This helps avoid security vulnerabilities such as
  97 [CVE-2013-1862](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2013-1862)
  98 and
  99 [CVE-2009-4496](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2009-4496).