Blame docs/wlog.md

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