docs/wlog.md

   1 # Overview
   2
   3 WLog is a configurable and flexible logging system used throughout winpr and
   4 FreeRDP.
   5
   6 The primary concept is to have a hierarchy of loggers that can be be configured
   7 independently.
   8
   9 TODO add more details and configuration examples.
  10
  11
  12
  13 # Environment variables
  14
  15 * WLOG_APPENDER  - the appender to use
  16 * WLOG_PREFIX - configure the prefix used for outputting the message (see
  17   Format for more details and examples)
  18 * WLOG_LEVEL - the level to output messages for
  19 * WLOG_FILTER - sets a filter for WLog messages. Only the filtered messages are
  20 printed
  21 * WLOG_FILEAPPENDER_OUTPUT_FILE_PATH  - set the output file path for the file
  22 file appender
  23 * WLOG_FILEAPPENDER_OUTPUT_FILE_NAME - set the output file name for the output
  24 appender
  25 * WLOG_JOURNALD_ID - identifier used by the journal appender
  26 * WLOG_UDP_TARGET - target to use for the UDP appender in the format host:port
  27
  28 # Levels
  29
  30 The WLog are complementary the higher level always includes the lower ones.
  31 The level list below is top down. Top the highest level.
  32
  33 * WLOG_TRACE - print everything including package dumps
  34 * WLOG_DEBUG - debug messages
  35 * WLOG_INFO - general informations
  36 * WLOG_WARN - warnings
  37 * WLOG_ERROR - error
  38 * WLOG_FATAL - fatal problems
  39 * WLOG_OFF - completely disable the wlog output
  40
  41
  42 # Format
  43
  44 The format a logger prints in has the following possible options:
  45
  46 * "lv" - log level
  47 * "mn" - module name
  48 * "fl" - file name
  49 * "fn" - function
  50 * "ln" - line number
  51 * "pid" - process id
  52 * "tid" - thread id
  53 * "yr" - year
  54 * "mo" - month
  55 * "dw" - day of week
  56 * "hr" - hour
  57 * "mi" - minute
  58 * "se" - second
  59 * "ml" - milliseconds
  60
  61 A maximum of 16 options can be used per format string.
  62
  63 An example that generally sets the WLOG_PREFIX for xfreerdp would look like:
  64 ```
  65 WLOG_PREFIX="pid=%pid:tid=%tid:fn=%fn -" xfreerdp /v:xxx
  66 ```
  67
  68 # Appenders
  69
  70 WLog uses different appenders that define where the log output should be written
  71 to. If the application doesn't explicitly configure the appenders the above
  72 described variable WLOG_APPENDER can be used to choose one appender.
  73
  74 The following represents an overview about all appenders and their possible
  75 configuration values.
  76
  77 ### Binary
  78
  79 Write the log data into a binary format file.
  80
  81 Options:
  82 * "outputfilename", value const char* - file to write the data to
  83 * "outputfilepath", value const char* - location of the output file
  84
  85 ### Callback
  86 The callback appender can be used from an application to get all log messages
  87 back the application. For example if an application wants to handle the log
  88 output itself.
  89
  90 Options:
  91
  92 * "callbacks", value struct wLogCallbacks*, callbacks to use
  93
  94 ### Console
  95
  96 The console appender writes to the console. Depending of the operating system
  97 the application runs on the output might be handled differently. For example
  98 on android log print would be used.
  99
 100 Options:
 101
 102
 103 * "outputstream", value const char * - output stream to write to
 104   * "stdout" - write everything to stdout
 105   * "stderr" - write everything to stderr
 106   * "default" - use the default settings - in this case errors and fatal would
 107   go to stderr everything else to stdout
 108   * debug - use the debug output. Only used on windows on all operating systems
 109   this behaves as as if default was set.
 110
 111 ### File
 112 The file appender writes the textual output to a file.
 113
 114 Options:
 115
 116 * "outputfilename", value const char*, filename to use
 117 * "outputfilepath", value const char*, location of the file
 118
 119 ### Udp
 120
 121 This appender sends the loging messages to a pre-defined remote host via UDP.
 122
 123 Options:
 124
 125 * "target", value const char*, target to send the data too in the format
 126 host:port
 127
 128 If no target is set the default one 127.0.0.1:20000 is used. To receive the
 129 log messages one can use netcat. To receive the default target the following
 130 command could be used.
 131 ```
 132 nc -u 127.0.0.1 -p 20000 -l
 133 ```
 134
 135 ### Syslog (optional)
 136
 137 Use syslog for outputting the debug messages. No options available.
 138
 139 ### Journald (optional)
 140
 141 For outputting the log messages to journald this appender can be used.
 142 The available options are:
 143
 144 * "identifier", value const char*, the identifier to use for journald (default
 145   is winpr)