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