xtruss

an easy-to-use X protocol tracing program

Introduction

Any programmer accustomed to writing programs on Linux or System V-type Unixes will have encountered the program variously known as strace or truss, which monitors another program and produces a detailed log of every system call the program makes – in other words, all the program's interactions with the OS kernel. This is often an invaluable debugging tool, and almost as good an educational one.

When it's a GUI program (or rather, the GUI-related behaviour of a program) that you want to understand or debug, though, the level of interaction with the OS kernel is rarely the most useful one. More helpfully, one would like to log all the program's interactions with the X server in the same way.

Programs already exist that will do this. I'm aware of Xmon and Xtrace. But they tend to require a lot of effort to set up: you have to run the program to establish a listening server, then manually arrange for the target program to contact that instead of the real server – including some fiddly work with xauth. Ideally, you'd like tracing a program's X operations to be just as easy as tracing its kernel system calls: you'd like to type a command as simple as strace program-name arguments, and have everything automatically handled for you.

Also, the output of those programs is less easy to read than I'd have liked – by which I largely mean it's less like strace than I'd like it to be. strace has the nice property of putting each system call and its return value on the same line of output, so that you can see at a glance what each response was a response to. X protocol monitors, however, tend to follow the structure of the X protocol faithfully, meaning that each request and response is printed with a sequence number, and you have to match the two up by eye.

So this page presents xtruss, my own contribution to the field of X protocol loggers. It has a command-line syntax similar to strace – in its default mode, you just prefix "xtruss" to the same command line you would have run anyway – and its output format is also more like strace, putting requests and responses on the same line of output where reasonably possible.

strace also supports the feature of attaching to an already-running process and tracing it from the middle of its run – handy when something goes wrong with a long-running process that you didn't know in advance you were going to need to trace. xtruss supports this same feature, by means of the X RECORD extension (provided your X server supports it, which modern X.Org ones do); so in that mode, you can identify a window with the mouse (similarly to standard programs like xwininfo and xkill), and xtruss will attach to the X client program that owns the window you specified, and begin tracing it.

For some more detail, you can read xtruss's man page online.

Status of xtruss

As of 2009-05-11, xtruss is considered to be barely tested alpha. It works well enough that I've successfully debugged two real problems with it, but I'm not yet aware of anyone else having tried to use it. Testing would be appreciated. Bugs in the protocol decoder are probably numerous (unfortunately); reports of those would be best accompanied by a log file produced with the -R option, so that I can see both the original session data and its mistranslation.

Licence

xtruss is distributed under the MIT/X11 licence, so it is free to copy, redistribute, use and reuse. For more details, see the file called LICENCE in the distribution archive.

Download

A Unix source archive of xtruss is available here:

xtruss-20141217.892f082.tar.gz

If you want to see the latest state of development, you can check the development sources out from my git repository:

git clone git://git.tartarus.org/simon/xtruss.git

Alternatively, you can browse the repository on the web, here.

(The source directory might look a little confusing. In order to put together an X11 proxy quickly, I reused a lot of code from PuTTY, so a lot of the source files will contain code that's irrelevant to their purpose here.)

Feedback

Please report bugs to anakin@pobox.com.

You might find it helpful to read this article before reporting a bug.

Patches are welcome.


(comments to anakin@pobox.com)
(thanks to chiark for hosting this page)
(last modified on Wed Dec 17 02:30:10 2014)