diff options
Diffstat (limited to 'doc/dtrace/Xserver-DTrace.xml')
| -rw-r--r-- | doc/dtrace/Xserver-DTrace.xml | 578 |
1 files changed, 578 insertions, 0 deletions
diff --git a/doc/dtrace/Xserver-DTrace.xml b/doc/dtrace/Xserver-DTrace.xml new file mode 100644 index 000000000..69cd30eb0 --- /dev/null +++ b/doc/dtrace/Xserver-DTrace.xml @@ -0,0 +1,578 @@ +<?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> |