diff options
Diffstat (limited to 'docs/wlog.md')
-rw-r--r-- | docs/wlog.md | 151 |
1 files changed, 151 insertions, 0 deletions
diff --git a/docs/wlog.md b/docs/wlog.md new file mode 100644 index 0000000..e6d1286 --- /dev/null +++ b/docs/wlog.md @@ -0,0 +1,151 @@ +# Overview + +WLog is a configurable and flexible logging system used throughout winpr and +FreeRDP. + +The primary concept is to have a hierarchy of loggers that can be be configured +independently. + +TODO add more details and configuration examples. + + + +# Environment variables + +* WLOG_APPENDER - the appender to use possible values below also see the Appender section. + * CONSOLE + * FILE + * BINARY + * SYSLOG + * JOURNALD + * UDP +* WLOG_PREFIX - configure the prefix used for outputting the message (see + Format for more details and examples) +* WLOG_LEVEL - the level to output messages for +* WLOG_FILTER - sets a filter for WLog messages. Only the filtered messages are +printed +* WLOG_FILEAPPENDER_OUTPUT_FILE_PATH - set the output file path for the file +file appender +* WLOG_FILEAPPENDER_OUTPUT_FILE_NAME - set the output file name for the output +appender +* WLOG_JOURNALD_ID - identifier used by the journal appender +* WLOG_UDP_TARGET - target to use for the UDP appender in the format host:port + +# Levels + +The WLog are complementary the higher level always includes the lower ones. +The level list below is top down. Top the highest level. + +* WLOG_TRACE - print everything including package dumps +* WLOG_DEBUG - debug messages +* WLOG_INFO - general informations +* WLOG_WARN - warnings +* WLOG_ERROR - errors +* WLOG_FATAL - fatal problems +* WLOG_OFF - completely disable the wlog output + + +# Format + +The format a logger prints in has the following possible options: + +* "lv" - log level +* "mn" - module name +* "fl" - file name +* "fn" - function +* "ln" - line number +* "pid" - process id +* "tid" - thread id +* "yr" - year +* "mo" - month +* "dw" - day of week +* "hr" - hour +* "mi" - minute +* "se" - second +* "ml" - millisecond + +A maximum of 16 options can be used per format string. + +An example that generally sets the WLOG_PREFIX for xfreerdp would look like: +``` +WLOG_PREFIX="pid=%pid:tid=%tid:fn=%fn -" xfreerdp /v:xxx +``` + +# Appenders + +WLog uses different appenders that define where the log output should be written +to. If the application doesn't explicitly configure the appenders the above +described variable WLOG_APPENDER can be used to choose one appender. + +The following represents an overview about all appenders and their possible +configuration values. + +### Binary + +Write the log data into a binary format file. + +Options: +* "outputfilename", value const char* - file to write the data to +* "outputfilepath", value const char* - location of the output file + +### Callback +The callback appender can be used from an application to get all log messages +back the application. For example if an application wants to handle the log +output itself. + +Options: + +* "callbacks", value struct wLogCallbacks*, callbacks to use + +### Console + +The console appender writes to the console. Depending of the operating system +the application runs on the output might be handled differently. For example +on android log print would be used. + +Options: + + +* "outputstream", value const char * - output stream to write to + * "stdout" - write everything to stdout + * "stderr" - write everything to stderr + * "default" - use the default settings - in this case errors and fatal would + go to stderr everything else to stdout + * debug - use the debug output. Only used on windows on all operating systems + this behaves as as if default was set. + +### File +The file appender writes the textual output to a file. + +Options: + +* "outputfilename", value const char*, filename to use +* "outputfilepath", value const char*, location of the file + +### Udp + +This appender sends the logging messages to a pre-defined remote host via UDP. + +Options: + +* "target", value const char*, target to send the data too in the format +host:port + +If no target is set the default one 127.0.0.1:20000 is used. To receive the +log messages one can use netcat. To receive the default target the following +command could be used. +``` +nc -u 127.0.0.1 -p 20000 -l +``` + +### Syslog (optional) + +Use syslog for outputting the debug messages. No options available. + +### Journald (optional) + +For outputting the log messages to journald this appender can be used. +The available options are: + +* "identifier", value const char*, the identifier to use for journald (default + is winpr) |