Skip to main content

​
Overview

WLog is a configurable and flexible logging system used throughout WinPR and FreeRDP. The primary concept is a hierarchy of loggers that can be configured independently. Each logger is identified by a dotted name (e.g., core.channel, com.freerdp.client.x11) and inherits settings from its parent unless overridden. Configuration is done entirely through environment variables — no source changes are required.

​
Log levels

Levels are cumulative: setting a level includes all levels below it in the hierarchy.
LevelDescription
TRACEPrint everything, including packet dumps
DEBUGDebug messages
INFOGeneral information
WARNWarnings
ERRORErrors
FATALFatal problems
OFFCompletely disable WLog output

​
Environment variables

​
Core variables

VariableDescription
WLOG_LEVELThe minimum level to output. Applies globally unless overridden by WLOG_FILTER.
WLOG_FILTERComma-separated list of <logger>:<level> pairs. Only matching loggers at the specified level are printed.
WLOG_PREFIXFormat string controlling the prefix of every log line. See Format specifiers.
WLOG_APPENDERSelects the output target. See Appenders.

​
File appender variables

VariableDescription
WLOG_FILEAPPENDER_OUTPUT_FILE_PATHDirectory in which the log file is written.
WLOG_FILEAPPENDER_OUTPUT_FILE_NAMEName of the output log file.

​
Journald appender variable

VariableDescription
WLOG_JOURNALD_IDIdentifier used with the journal (defaults to the executable name).

​
UDP appender variable

VariableDescription
WLOG_UDP_TARGETTarget in host:port format. Defaults to 127.0.0.1:20000.

​
Format specifiers

The WLOG_PREFIX variable controls what appears before each log message. Specifiers are prefixed with %.
SpecifierDescription
%lvLog level
%mnModule name
%flFile name
%fnFunction name
%lnLine number
%pidProcess ID
%tidThread ID
%yrYear
%moMonth
%dwDay of week
%hrHour
%miMinute
%seSecond
%mlMillisecond
A maximum of 16 specifiers can be used in a single format string.

​
Example prefix

WLOG_PREFIX="pid=%pid:tid=%tid:fn=%fn -" xfreerdp /v:192.168.1.100

​
Appenders

An appender defines where log output is written. Select one with WLOG_APPENDER.
Writes to the console. On Android, log_print is used instead.outputstream option values:
  • stdout — write everything to stdout
  • stderr — write everything to stderr
  • default — errors and fatal messages go to stderr; everything else to stdout
  • debug — use debug output (Windows only; behaves like default on other platforms)
WLOG_APPENDER=CONSOLE xfreerdp /v:192.168.1.100
Writes textual log output to a file.
WLOG_APPENDER=FILE \
WLOG_FILEAPPENDER_OUTPUT_FILE_PATH=/var/log \
WLOG_FILEAPPENDER_OUTPUT_FILE_NAME=freerdp.log \
xfreerdp /v:192.168.1.100
Writes log data in a binary format file.
WLOG_APPENDER=BINARY \
WLOG_FILEAPPENDER_OUTPUT_FILE_PATH=/tmp \
WLOG_FILEAPPENDER_OUTPUT_FILE_NAME=freerdp.bin \
xfreerdp /v:192.168.1.100
Sends log messages to a remote host over UDP. The default target is 127.0.0.1:20000.
WLOG_APPENDER=UDP WLOG_UDP_TARGET=127.0.0.1:20000 xfreerdp /v:192.168.1.100
Receive messages with netcat in a second terminal:
nc -u 127.0.0.1 -p 20000 -l
Outputs log messages to syslog. No additional options are available.
WLOG_APPENDER=SYSLOG xfreerdp /v:192.168.1.100
Syslog support is optional and depends on build-time configuration.
Outputs log messages to the systemd journal.
WLOG_APPENDER=JOURNALD WLOG_JOURNALD_ID=freerdp xfreerdp /v:192.168.1.100
Read the journal:
journalctl -t freerdp -f
Journald support is optional. It requires building with -DWITH_LIBSYSTEMD=ON.

​
Filtering specific modules

Use WLOG_FILTER to restrict output to particular loggers and levels. The format is a comma-separated list of <logger>:<level> pairs. 
# Show DEBUG messages for the core channel logger and TRACE for a specific component
WLOG_FILTER=core.channel:DEBUG,dummy:TRACE xfreerdp /v:192.168.1.100
Only loggers matching the filter are printed; all others are suppressed regardless of WLOG_LEVEL.

​
Common recipes

WLOG_LEVEL=TRACE xfreerdp /v:192.168.1.100