579 lines
19 KiB
XML
579 lines
19 KiB
XML
<?xml version="1.0" encoding="ISO-8859-1"?>
|
|
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
|
|
<!ENTITY % defs SYSTEM "/xserver/doc/xml/xserver.ent"> %defs;
|
|
]>
|
|
|
|
<article id="Xserver-DTrace">
|
|
<articleinfo>
|
|
<title>Xserver provider for DTrace</title>
|
|
<author>
|
|
<firstname>Alan</firstname><surname>Coopersmith</surname>
|
|
<affiliation>
|
|
<orgname>Oracle Corporation</orgname>
|
|
<orgdiv>Solaris Engineering</orgdiv>
|
|
</affiliation>
|
|
</author>
|
|
<releaseinfo>X.Org Xserver version &xserver.version;</releaseinfo>
|
|
<legalnotice>
|
|
<para>
|
|
Copyright (c) 2005, 2006, 2007, 2010, Oracle and/or its affiliates.
|
|
All rights reserved.
|
|
</para><para>
|
|
Permission is hereby granted, free of charge, to any person obtaining a
|
|
copy of this software and associated documentation files (the "Software"),
|
|
to deal in the Software without restriction, including without limitation
|
|
the rights to use, copy, modify, merge, publish, distribute, sublicense,
|
|
and/or sell copies of the Software, and to permit persons to whom the
|
|
Software is furnished to do so, subject to the following conditions:
|
|
</para><para>
|
|
The above copyright notice and this permission notice (including the next
|
|
paragraph) shall be included in all copies or substantial portions of the
|
|
Software.
|
|
</para><para>
|
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
|
|
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
|
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
|
|
DEALINGS IN THE SOFTWARE.
|
|
</para>
|
|
</legalnotice>
|
|
</articleinfo>
|
|
|
|
<sect1 id="introduction">
|
|
<title>Introduction</title>
|
|
<para>
|
|
This page provides details on a
|
|
<ulink url="http://wikis.sun.com/display/DTrace/Statically+Defined+Tracing+for+User+Applications">statically defined user application tracing provider</ulink>
|
|
for the
|
|
<ulink url="http://hub.opensolaris.org/bin/view/Community+Group+dtrace/">DTrace</ulink>
|
|
facility in <productname>Solaris</productname> 10,
|
|
<productname>MacOS X</productname> 10.5, and later releases. This
|
|
provider instruments various points in the X server, to allow
|
|
tracing what client applications are up to.
|
|
</para>
|
|
|
|
<para>
|
|
The provider was integrated into the X.Org git master repository
|
|
with Solaris 10 & OpenSolaris support for the Xserver 1.4 release,
|
|
released in 2007 with X11R7.3. Support for DTrace on MacOS X
|
|
was added in Xserver 1.7.
|
|
</para>
|
|
|
|
<para>
|
|
These probes expose the request and reply structure of the X protocol
|
|
between clients and the X server, so an understanding of that basic
|
|
nature will aid in learning how to use these probes.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="probes">
|
|
<title>Available probes</title>
|
|
|
|
<para>
|
|
Due to the way User-Defined DTrace probes work, arguments to
|
|
these probes all bear undistinguished names of
|
|
<parameter>arg0</parameter>, <parameter>arg1</parameter>,
|
|
<parameter>arg2</parameter>, etc. These tables should help you
|
|
determine what the real data is for each of the probe arguments.
|
|
|
|
<table>
|
|
<title>Probes and their arguments</title>
|
|
<tgroup cols='7'>
|
|
<colspec colname="probe" colwidth="2*"/>
|
|
<colspec colname="desc" colwidth="3*"/>
|
|
<colspec colname="arg0" colwidth="1*"/>
|
|
<colspec colname="arg1" colwidth="1*"/>
|
|
<colspec colname="arg2" colwidth="1*"/>
|
|
<colspec colname="arg3" colwidth="1*"/>
|
|
<colspec colname="arg4" colwidth="1*"/>
|
|
<spanspec spanname="all" namest="probe" nameend="arg4"/>
|
|
<thead>
|
|
<row>
|
|
<entry>Probe name</entry>
|
|
<entry>Description</entry>
|
|
<entry>arg0</entry>
|
|
<entry>arg1</entry>
|
|
<entry>arg2</entry>
|
|
<entry>arg3</entry>
|
|
<entry>arg4</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry spanname="all" class="grouphead">Request Probes</entry>
|
|
</row>
|
|
<row>
|
|
<entry>request-start</entry>
|
|
<entry>Called just before processing each client request.</entry>
|
|
<entry><parameter>requestName</parameter></entry>
|
|
<entry><parameter>requestCode</parameter></entry>
|
|
<entry><parameter>requestLength</parameter></entry>
|
|
<entry><parameter>clientId</parameter></entry>
|
|
<entry><parameter>requestBuffer</parameter></entry>
|
|
</row>
|
|
<row>
|
|
<entry>request-done</entry>
|
|
<entry>Called just after processing each client request.</entry>
|
|
<entry><parameter>requestName</parameter></entry>
|
|
<entry><parameter>requestCode</parameter></entry>
|
|
<entry><parameter>sequenceNumber</parameter></entry>
|
|
<entry><parameter>clientId</parameter></entry>
|
|
<entry><parameter>resultCode</parameter></entry>
|
|
</row>
|
|
<row>
|
|
<entry spanname="all" class="grouphead">Event Probes</entry>
|
|
</row>
|
|
<row>
|
|
<entry>send-event</entry>
|
|
<entry>Called just before send each event to a client.</entry>
|
|
<entry><parameter>clientId</parameter></entry>
|
|
<entry><parameter>eventCode</parameter></entry>
|
|
<entry><parameter>eventBuffer</parameter></entry>
|
|
<entry nameend="arg4" class="unused"/>
|
|
</row>
|
|
<row>
|
|
<entry spanname="all" class="grouphead">Client Connection Probes</entry>
|
|
</row>
|
|
<row>
|
|
<entry>client-connect</entry>
|
|
<entry>Called when a new connection is opened from a client</entry>
|
|
<entry><parameter>clientId</parameter></entry>
|
|
<entry><parameter>clientFD</parameter></entry>
|
|
<entry nameend="arg4" class="unused"/>
|
|
</row>
|
|
<row>
|
|
<entry>client-auth</entry>
|
|
<entry>Called when client authenticates (normally just after connection opened)</entry>
|
|
<entry><parameter>clientId</parameter></entry>
|
|
<entry><parameter>clientAddr</parameter></entry>
|
|
<entry><parameter>clientPid</parameter></entry>
|
|
<entry><parameter>clientZoneId</parameter></entry>
|
|
<entry nameend="arg4" class="unused"/>
|
|
</row>
|
|
<row>
|
|
<entry>client-disconnect</entry>
|
|
<entry>Called when a client connection is closed</entry>
|
|
<entry><parameter>clientId</parameter></entry>
|
|
<entry nameend="arg4" class="unused"/>
|
|
</row>
|
|
<row>
|
|
<entry spanname="all" class="grouphead">Resource Allocation Probes</entry>
|
|
</row>
|
|
<row>
|
|
<entry>resource-alloc</entry>
|
|
<entry>Called when a new resource (pixmap, gc, colormap, etc.) is allocated</entry>
|
|
<entry><parameter>resourceId</parameter></entry>
|
|
<entry><parameter>resourceTypeId</parameter></entry>
|
|
<entry><parameter>resourceValue</parameter></entry>
|
|
<entry><parameter>resourceTypeName</parameter></entry>
|
|
<entry nameend="arg4" class="unused"/>
|
|
</row>
|
|
<row>
|
|
<entry>resource-free</entry>
|
|
<entry>Called when a resource is freed</entry>
|
|
<entry><parameter>resourceId</parameter></entry>
|
|
<entry><parameter>resourceTypeId</parameter></entry>
|
|
<entry><parameter>resourceValue</parameter></entry>
|
|
<entry><parameter>resourceTypeName</parameter></entry>
|
|
<entry nameend="arg4" class="unused"/>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="arguments">
|
|
<title>Data Available in Probe Arguments</title>
|
|
|
|
<para>
|
|
To access data in arguments of type <type>string</type>, you will need
|
|
to use <ulink url="http://wikis.sun.com/display/DTrace/Actions+and+Subroutines#ActionsandSubroutines-{{copyinstr}}"><function>copyinstr()</function></ulink>.
|
|
To access data buffers referenced via <type>uintptr_t</type>'s, you will
|
|
need to use <ulink url="http://wikis.sun.com/display/DTrace/Actions+and+Subroutines#ActionsandSubroutines-{{copyin}}"><function>copyin()</function></ulink>.
|
|
|
|
<table>
|
|
<title>Probe Arguments</title>
|
|
<tgroup cols='3'>
|
|
<colspec colname="arg" colwidth="2*"/>
|
|
<colspec colname="type" colwidth="1*"/>
|
|
<colspec colname="desc" colwidth="7*"/>
|
|
<thead>
|
|
<row>
|
|
<entry>Argument name</entry>
|
|
<entry>Type</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><parameter>clientAddr</parameter></entry>
|
|
<entry><type>string</type></entry>
|
|
<entry>String representing address client connected from</entry>
|
|
</row>
|
|
<row>
|
|
<entry><parameter>clientFD</parameter></entry>
|
|
<entry><type>int</type></entry>
|
|
<entry>X server's file descriptor for server side of each connection</entry>
|
|
</row>
|
|
<row>
|
|
<entry><parameter>clientId</parameter></entry>
|
|
<entry><type>int</type></entry>
|
|
<entry>Unique integer identifier for each connection to the
|
|
X server</entry>
|
|
</row>
|
|
<row>
|
|
<entry><parameter>clientPid</parameter></entry>
|
|
<entry><type>pid_t</type></entry>
|
|
<entry>Process id of client, if connection is local
|
|
(from <function>getpeerucred()</function>)</entry>
|
|
</row>
|
|
<row>
|
|
<entry><parameter>clientZoneId</parameter></entry>
|
|
<entry><type>zoneid_t</type></entry>
|
|
<entry>Solaris: Zone id of client, if connection is local
|
|
(from <function>getpeerucred()</function>)</entry>
|
|
</row>
|
|
<row>
|
|
<entry><parameter>eventBuffer</parameter></entry>
|
|
<entry><type>uintptr_t</type></entry>
|
|
<entry>Pointer to buffer containing X event - decode using
|
|
structures in
|
|
<<ulink url="http://cgit.freedesktop.org/xorg/proto/xproto/tree/Xproto.h"><filename class="headerfile">X11/Xproto.h</filename></ulink>>
|
|
and similar headers for each extension</entry>
|
|
</row>
|
|
<row>
|
|
<entry><parameter>eventCode</parameter></entry>
|
|
<entry><type>uint8_t</type></entry>
|
|
<entry>Event number of X event</entry>
|
|
</row>
|
|
<row>
|
|
<entry><parameter>resourceId</parameter></entry>
|
|
<entry><type>uint32_t</type></entry>
|
|
<entry>X resource id (XID)</entry>
|
|
</row>
|
|
<row>
|
|
<entry><parameter>resourceTypeId</parameter></entry>
|
|
<entry><type>uint32_t</type></entry>
|
|
<entry>Resource type id</entry>
|
|
</row>
|
|
<row>
|
|
<entry><parameter>resourceTypeName</parameter></entry>
|
|
<entry><type>string</type></entry>
|
|
<entry>String representing X resource type
|
|
(<literal>"PIXMAP"</literal>, etc.)</entry>
|
|
</row>
|
|
<row>
|
|
<entry><parameter>resourceValue</parameter></entry>
|
|
<entry><type>uintptr_t</type></entry>
|
|
<entry>Pointer to data for X resource</entry>
|
|
</row>
|
|
<row>
|
|
<entry><parameter>resultCode</parameter></entry>
|
|
<entry><type>int</type></entry>
|
|
<entry>Integer code representing result status of request</entry>
|
|
</row>
|
|
<row>
|
|
<entry><parameter>requestBuffer</parameter></entry>
|
|
<entry><type>uintptr_t</type></entry>
|
|
<entry>Pointer to buffer containing X request - decode using
|
|
structures in
|
|
<<ulink url="http://cgit.freedesktop.org/xorg/proto/xproto/tree/Xproto.h"><filename class="headerfile">X11/Xproto.h</filename></ulink>>
|
|
and similar headers for each extension</entry>
|
|
</row>
|
|
<row>
|
|
<entry><parameter>requestCode</parameter></entry>
|
|
<entry><type>uint8_t</type></entry>
|
|
<entry>Request number of X request or Extension</entry>
|
|
</row>
|
|
<row>
|
|
<entry><parameter>requestName</parameter></entry>
|
|
<entry><type>string</type></entry>
|
|
<entry>Name of X request or Extension</entry>
|
|
</row>
|
|
<row>
|
|
<entry><parameter>requestLength</parameter></entry>
|
|
<entry><type>uint16_t</type></entry>
|
|
<entry>Length of X request</entry>
|
|
</row>
|
|
<row>
|
|
<entry><parameter>sequenceNumber</parameter></entry>
|
|
<entry><type>uint32_t</type></entry>
|
|
<entry>Number of X request in in this connection</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="examples">
|
|
<title>Examples</title>
|
|
|
|
<example>
|
|
<title>Counting requests by request name</title>
|
|
|
|
<para>
|
|
This script simply increments a counter for each different request
|
|
made, and when you exit the script (such as by hitting
|
|
<keycombo action='simul'><keycap>Control</keycap><keycap>C</keycap>
|
|
</keycombo>) prints the counts.
|
|
|
|
<programlisting>
|
|
#!/usr/sbin/dtrace -s
|
|
|
|
Xserver*:::request-start
|
|
{
|
|
@counts[copyinstr(arg0)] = count();
|
|
}
|
|
</programlisting>
|
|
|
|
The output from a short run may appear as:
|
|
<screen>
|
|
QueryPointer 1
|
|
CreatePixmap 2
|
|
FreePixmap 2
|
|
PutImage 2
|
|
ChangeGC 10
|
|
CopyArea 10
|
|
CreateGC 14
|
|
FreeGC 14
|
|
RENDER 28
|
|
SetClipRectangles 40
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
This can be rewritten slightly to cache the string containing the name
|
|
of the request since it will be reused many times, instead of copying
|
|
it over and over from the kernel:
|
|
|
|
<programlisting>
|
|
#!/usr/sbin/dtrace -s
|
|
|
|
string Xrequest[uintptr_t];
|
|
|
|
Xserver*:::request-start
|
|
/Xrequest[arg0] == ""/
|
|
{
|
|
Xrequest[arg0] = copyinstr(arg0);
|
|
}
|
|
|
|
Xserver*:::request-start
|
|
{
|
|
@counts[Xrequest[arg0]] = count();
|
|
}
|
|
</programlisting>
|
|
</para>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Get average CPU time per request</title>
|
|
|
|
<para>This script records the CPU time used between the probes at
|
|
the start and end of each request and aggregates it per request type.
|
|
|
|
<programlisting>
|
|
#!/usr/sbin/dtrace -s
|
|
|
|
Xserver*:::request-start
|
|
{
|
|
reqstart = vtimestamp;
|
|
}
|
|
|
|
Xserver*:::request-done
|
|
{
|
|
@times[copyinstr(arg0)] = avg(vtimestamp - reqstart);
|
|
}
|
|
</programlisting>
|
|
|
|
The output from a sample run might look like:
|
|
|
|
<screen>
|
|
ChangeGC 889
|
|
MapWindow 907
|
|
SetClipRectangles 1319
|
|
PolyPoint 1413
|
|
PolySegment 1434
|
|
PolyRectangle 1828
|
|
FreeCursor 1895
|
|
FreeGC 1950
|
|
CreateGC 2244
|
|
FreePixmap 2246
|
|
GetInputFocus 2249
|
|
TranslateCoords 8508
|
|
QueryTree 8846
|
|
GetGeometry 9948
|
|
CreatePixmap 12111
|
|
AllowEvents 14090
|
|
GrabServer 14791
|
|
MIT-SCREEN-SAVER 16747
|
|
ConfigureWindow 22917
|
|
SetInputFocus 28521
|
|
PutImage 240841
|
|
|
|
</screen>
|
|
</para>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Monitoring clients that connect and disconnect</title>
|
|
|
|
<para>
|
|
This script simply prints information about each client that
|
|
connects or disconnects from the server while it is running.
|
|
Since the provider is specified as <code>Xserver$1</code> instead
|
|
of <code>Xserver*</code> like previous examples, it won't monitor
|
|
all Xserver processes running on the machine, but instead expects
|
|
the process id of the X server to monitor to be specified as the
|
|
argument to the script.
|
|
|
|
<programlisting>
|
|
#!/usr/sbin/dtrace -s
|
|
|
|
Xserver$1:::client-connect
|
|
{
|
|
printf("** Client Connect: id %d\n", arg0);
|
|
}
|
|
|
|
Xserver$1:::client-auth
|
|
{
|
|
printf("** Client auth'ed: id %d => %s pid %d\n",
|
|
arg0, copyinstr(arg1), arg2);
|
|
}
|
|
|
|
Xserver$1:::client-disconnect
|
|
{
|
|
printf("** Client Disconnect: id %d\n", arg0);
|
|
}
|
|
</programlisting>
|
|
|
|
A sample run:
|
|
|
|
<screen>
|
|
<prompt>#</prompt> <userinput>./foo.d 5790</userinput>
|
|
<computeroutput>dtrace: script './foo.d' matched 4 probes
|
|
CPU ID FUNCTION:NAME
|
|
0 15774 CloseDownClient:client-disconnect ** Client Disconnect: id 65
|
|
|
|
2 15774 CloseDownClient:client-disconnect ** Client Disconnect: id 64
|
|
|
|
0 15773 EstablishNewConnections:client-connect ** Client Connect: id 64
|
|
|
|
0 15772 AuthAudit:client-auth ** Client auth'ed: id 64 => local host pid 2034
|
|
|
|
0 15773 EstablishNewConnections:client-connect ** Client Connect: id 65
|
|
|
|
0 15772 AuthAudit:client-auth ** Client auth'ed: id 65 => local host pid 2034
|
|
|
|
0 15774 CloseDownClient:client-disconnect ** Client Disconnect: id 64
|
|
</computeroutput>
|
|
</screen>
|
|
|
|
</para>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Monitoring clients creating Pixmaps</title>
|
|
|
|
<para>
|
|
This script can be used to determine which clients are creating
|
|
pixmaps in the X server, printing information about each client
|
|
as it connects to help trace it back to the program on the other
|
|
end of the X connection.
|
|
|
|
<programlisting>
|
|
#!/usr/sbin/dtrace -qs
|
|
|
|
string Xrequest[uintptr_t];
|
|
string Xrestype[uintptr_t];
|
|
|
|
Xserver$1:::request-start
|
|
/Xrequest[arg0] == ""/
|
|
{
|
|
Xrequest[arg0] = copyinstr(arg0);
|
|
}
|
|
|
|
Xserver$1:::resource-alloc
|
|
/arg3 != 0 && Xrestype[arg3] == ""/
|
|
{
|
|
Xrestype[arg3] = copyinstr(arg3);
|
|
}
|
|
|
|
|
|
Xserver$1:::request-start
|
|
/Xrequest[arg0] == "X_CreatePixmap"/
|
|
{
|
|
printf("-> %s: client %d\n", Xrequest[arg0], arg3);
|
|
}
|
|
|
|
Xserver$1:::request-done
|
|
/Xrequest[arg0] == "X_CreatePixmap"/
|
|
{
|
|
printf("<- %s: client %d\n", Xrequest[arg0], arg3);
|
|
}
|
|
|
|
Xserver$1:::resource-alloc
|
|
/Xrestype[arg3] == "PIXMAP"/
|
|
{
|
|
printf("** Pixmap alloc: %08x\n", arg0);
|
|
}
|
|
|
|
|
|
Xserver$1:::resource-free
|
|
/Xrestype[arg3] == "PIXMAP"/
|
|
{
|
|
printf("** Pixmap free: %08x\n", arg0);
|
|
}
|
|
|
|
Xserver$1:::client-connect
|
|
{
|
|
printf("** Client Connect: id %d\n", arg0);
|
|
}
|
|
|
|
Xserver$1:::client-auth
|
|
{
|
|
printf("** Client auth'ed: id %d => %s pid %d\n",
|
|
arg0, copyinstr(arg1), arg2);
|
|
}
|
|
|
|
Xserver$1:::client-disconnect
|
|
{
|
|
printf("** Client Disconnect: id %d\n", arg0);
|
|
}
|
|
</programlisting>
|
|
|
|
Sample output from a run of this script:
|
|
<screen><computeroutput>
|
|
** Client Connect: id 17
|
|
** Client auth'ed: id 17 => local host pid 20273
|
|
-> X_CreatePixmap: client 17
|
|
** Pixmap alloc: 02200009
|
|
<- X_CreatePixmap: client 17
|
|
-> X_CreatePixmap: client 15
|
|
** Pixmap alloc: 01e00180
|
|
<- X_CreatePixmap: client 15
|
|
-> X_CreatePixmap: client 15
|
|
** Pixmap alloc: 01e00181
|
|
<- X_CreatePixmap: client 15
|
|
-> X_CreatePixmap: client 14
|
|
** Pixmap alloc: 01c004c8
|
|
<- X_CreatePixmap: client 14
|
|
** Pixmap free: 02200009
|
|
** Client Disconnect: id 17
|
|
** Pixmap free: 01e00180
|
|
** Pixmap free: 01e00181
|
|
</computeroutput></screen>
|
|
|
|
</para>
|
|
|
|
</example>
|
|
|
|
|
|
</sect1>
|
|
|
|
</article>
|