xtrussan easy-to-use X protocol tracing program
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.
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.
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.
A Unix source archive of xtruss is available here:
If you want to see the latest state of development, you can check
the development sources out from my git repository:
git clone https://git.tartarus.org/simon/xtruss.gitAlternatively, 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.)
Please report bugs to anakin@pobox.com.
You might find it helpful to read this article before reporting a bug.
Patches are welcome.