Logging

Sometimes the problem is so obvious that you will simply get the error directly from the command line or in the server log file.

Basics

Otherwise, a good first step is to start xpra from the command line and add "-d CATEGORY" to it, for example to debug geometry issues:

xpra attach -d geometry

The full list of debugging categories can be found with xpra -d help, see below for a command output example.

Use the special category value "all" to enable all logging. (this will be very verbose)

You can also prefix the CATEGORY with a dash "-" to disable debug logging for it. For example, to log everything except "window" category:

xpra start :10 -d all,-window

Environment Variables

Each logging category can also be enabled using environment variable, which can be useful if you cannot modify the command line, or if the logging should happen very early on, or if you aren't calling the code from its normal wrappers. Use: XPRA_CATEGORY_DEBUG=1 xpra ... to enable debug logging for your chosen CATEGORY.

Xpra control interface

It is also possible to enable and disable debug logging of a server at runtime using:

xpra control :DISPLAY debug enable CATEGORY

and

xpra control :DISPLAY debug enable CATEGORY

And you can get the current list of debug loggers which:

xpra control :DISPLAY debug status

These commands are also available trough the server's dbus interface, see #904.

Detailed Logging

Some subsystems require special environment variables to enable logging, this is to minimize the cost of logging in performance critical paths. In particular the X11 bindings which can process thousands of events per second.

For example:

• x11 event handling:

  XPRA_X11_DEBUG_EVENTS="*" xpra start :10
  

or

XPRA_X11_DEBUG_EVENTS="EnterNotify,CreateNotify" xpra start :10

• XShm and image debugging code:

  XPRA_XSHM_DEBUG=1 xpra start :10
  

or

XPRA_XIMAGE_DEBUG=1 xpra start :10

Please refer to the source code for details and more up to date information.

Logging Categories

You can get the list of debugging categories with a brief explanation by running:

$ xpra -d help
known logging filters: 
Client:
 * client          : All client code
 * paint           : Client window paint code
 * draw            : Client draw packets
 * cairo           : Cairo paint code used with the GTK3 client
 * opengl          : Client OpenGL rendering
 * info            : About and Session info dialogs
 * launcher        : The client launcher program
General:
 * clipboard       : All clipboard operations
 * notify          : Notification forwarding
 * tray            : System Tray forwarding
 * printing        : Printing
 * file            : File transfers
 * keyboard        : Keyboard mapping and key event handling
 * screen          : Screen and workarea dimension
 * fps             : Frames per second
 * xsettings       : XSettings synchronization
 * dbus            : DBUS calls
 * rpc             : Remote Procedure Calls
 * menu            : Menus
 * events          : System and window events
Window:
 * window          : All window code
 * damage          : Window X11 repaint events
 * geometry        : Window geometry
 * shape           : Window shape forwarding (XShape)
 * focus           : Window focus
 * workspace       : Window workspace synchronization
 * metadata        : Window metadata
 * state           : Window state
 * icon            : Window icons
 * frame           : Window frame
Encoding:
 * codec           : Codec loader and video helper
 * loader          : Pixel compression codec loader
 * video           : Video encoding
 * score           : Video pipeline scoring and selection
 * encoding        : Server side encoding selection and compression
 * scaling         : Picture scaling
 * delta           : Delta pre-compression
 * scroll          : Scrolling detection and compression
 * xor             : XOR delta pre-compression
 * subregion       : Video subregion processing
 * regiondetect    : Video region detection
 * regionrefresh   : Video region refresh
 * refresh         : Refresh of lossy screen updates
 * compress        : Pixel compression (non video)
Codec:
 * csc             : Colourspace conversion codecs
 * cuda            : CUDA device access (nvenc)
 * cython          : Cython CSC module
 * swscale         : swscale CSC module
 * libyuv          : libyuv CSC module
 * decoder         : All decoders
 * encoder         : All encoders
 * avcodec         : avcodec decoder
 * libav           : libav common code (used by swscale, avcodec and ffmpeg)
 * ffmpeg          : ffmpeg encoder
 * pillow          : Pillow encoder and decoder
 * vpx             : libvpx encoder and decoder
 * nvenc           : nvenc encoder (all versions)
 * x264            : libx264 encoder
 * x265            : libx265 encoder
 * webcam          : webcam access
Pointer:
 * mouse           : Mouse motion
 * cursor          : Mouse cursor shape
Misc:
 * gtk             : All GTK code: bindings, client, etc
 * util            : All utility functions
 * gobject         : Command line clients
 * grab            : Window grabs (both keyboard and mouse)
 * test            : Test code
 * verbose         : Very verbose flag
Network:
 * network         : All network code
 * http            : HTTP requests
 * mmap            : mmap transfers
 * protocol        : Packet input and output (formatting, parsing, sending and receiving)
 * websocket       : Websocket layer
 * crypto          : Encryption
 * auth            : Authentication
Server:
 * server          : All server code
 * proxy           : Proxy server
 * shadow          : Shadow server
 * command         : Server control channel
 * timeout         : Server timeouts
 * exec            : Executing commands
 * mdns            : mDNS session publishing
 * stats           : Server statistics
 * xshm            : XShm pixel capture
Sound:
 * sound           : All sound
 * gstreamer       : GStreamer internal messages
 * av-sync         : Audio-video sync
X11:
 * x11             : All X11 code
 * bindings        : X11 Cython bindings
 * core            : X11 core bindings
 * randr           : X11 RandR bindings
 * ximage          : X11 XImage bindings
 * error           : X11 errors
Platform:
 * platform        : All platform support code
 * import          : Platform support import code
 * osx             : Mac OS X platform support code
 * win32           : Microsoft Windows platform support code
 * posix           : Posix platform code