folly/experimental/logging/docs/Usage.md

   1 # Usage
   2
   3 Logging messages with the folly logging library is done with one of a handful
   4 of log macros.  Macros are used to allow lazily evaluating the log arguments:
   5 if the log message is disabled the log message expression will not be executed.
   6
   7 # Logging Macros
   8
   9 ## `XLOG()`
  10
  11 In most cases, if you want to log a message you will use the `XLOG()` macro:
  12
  13 ```
  14 XLOG(INFO) << "hello world!";
  15 ```
  16
  17 This macro is defined in `folly/logging/xlog.h`
  18
  19 ## `FB_LOG()`
  20
  21 The `XLOG()` macro automatically chooses the log category based on the current
  22 file name.  However, if you want to log to an explicit log category, you can
  23 use `FB_LOG()`.  It behaves like `XLOG()`, except that it requires a
  24 `folly::Logger` as is first argument to specify the log category:
  25
  26 ```
  27 folly::Logger eventLogger("eden.events");
  28
  29 FB_LOG(eventLogger, INFO) << "something happened";
  30 ```
  31
  32 `FB_LOG()` is defined in `folly/logging/Logger.h`
  33
  34 ## Macro Arguments
  35
  36 The `XLOG()` macro takes a log level as its first argument.  See the
  37 [Log Levels](LogLevels.md) document for a list of available log levels.
  38
  39 If you supply additional arguments they will be converted to strings using
  40 `folly::to<std::string>()` and concatenated together as part of the log
  41 message.  For example:
  42
  43 ```
  44 XLOG(INFO, "the number is ", 2 + 2);
  45 ```
  46
  47 will result in the message "the number is 4".
  48
  49 If desired, you can specify both function argument style and `ostream` style
  50 streaming log arguments together:
  51
  52 ```
  53 XLOG(INFO, "the number is ") <<  2 + 2);
  54 ```
  55
  56 The `FB_LOG()` macro accepts requires a `Logger` object as its first argument,
  57 and all subsequent arguments behave the same as the arguments to `XLOG()`.
  58
  59 ## Python-style string formatting
  60
  61 The `XLOGF()` and `FB_LOGF()` macros allow log messages to be formatted using
  62 format strings similar to python's
  63 [str.format()](https://docs.python.org/3/library/string.html#formatspec)
  64 mechanism.
  65
  66 ```
  67 XLOGF(DBG1, "cannot engage {} thruster: {}", thruster.name(), err.what());
  68 ```
  69
  70 This uses [`folly::format()`](https://github.com/facebook/folly/blob/master/folly/docs/Format.md)
  71 to perform the formatting internally.
  72
  73 ## `printf`-style string formatting
  74
  75 To help existing projects convert from older logging APIs, `XLOGC()` and
  76 `FB_LOGC()` macros exist to support C-style `printf()` format strings.
  77 You must include `folly/logging/printf.h` to access these macros.
  78
  79 ```
  80 XLOGC(DBG1, "failed to engage thruster %d: %s", thruster.number(), err.what());
  81 ```
  82
  83 # Log Category Selection
  84
  85 The `XLOG()` macro automatically selects a log category to log to based on the
  86 current source file name.  Directory separators in the path are replaced with
  87 `.` characters to compute the log category name.
  88
  89 For instance, in a source file named `src/tiefighter/thruster.cpp` the default
  90 `XLOG()` category will be `src.tiefighter.thruster.cpp`
  91
  92 Inside `.cpp` files the default `XLOG()` category name can be overridden using
  93 the `XLOG_SET_CATEGORY_NAME()` macro.  `XLOG_SET_CATEGORY_NAME()` can be
  94 specified at top-level scope in the `.cpp` file to specify an alternate
  95 category name for all `XLOG()` statements in this file.
  96 `XLOG_SET_CATEGORY_NAME()` should not be used in header files, since it would
  97 end up affecting all `.cpp` files that include that header.
  98
  99 # Configuration
 100
 101 The logging library provides several APIs for configuring log categories and
 102 handlers.  While you can programmatically configure `LogCategory` and
 103 `LogHandler` objects via their public APIs, there are also APIs to configure
 104 the logging library via configuration strings.
 105
 106 `folly::parseLogConfig()` can parse a configuration string in to a `LogConfig`
 107 object.  The configuration string syntax is documented in
 108 [Config.md](Config.md).
 109
 110 You can then apply a `LogConfig` object to the main `LoggerDB` singleton by
 111 using `LoggerDB::get()->updateConfig()` to incrementally update the current
 112 configuration, or by using `LoggerDB::get()->resetConfig()` to replace all
 113 existing settings with the new configuration.
 114
 115 The `folly::initLogging()` function provides a convenient API for initially
 116 configuring the logging library from a configuration string that was obtained
 117 from a command line flag or configuration file.