diff options
3 files changed, 90 insertions, 1 deletions
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-functioncalls.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-functioncalls.xml index d108e4fe..73c1a0ee 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-functioncalls.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-functioncalls.xml @@ -38,7 +38,7 @@ probe end,timer.ms(30000) { <para><xref linkend="countcalls"/> takes the targeted kernel function as an argument. The argument supports wildcards, which enables you to target multiple kernel functions up to a certain extent.</para> -<para>You can increase the sample time by editing the timer in the second probe (<command>timer.ms()</command>). <xref linkend="countcallsoutput"/> contains an excerpt from the output of <command>stap countcalls.stp "*@mm/*.c"</command>: +<para>You can increase the sample time by editing the timer in the second probe (<command>timer.ms()</command>). The output of <xref linkend="countcalls"/> contains the name of the function called and how many times it was called during the sample time (in alphabetical order). <xref linkend="countcallsoutput"/> contains an excerpt from the output of <command>stap countcalls.stp "*@mm/*.c"</command>: <example id="countcallsoutput"> diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-futexes.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-futexes.xml new file mode 100644 index 00000000..adb3e5c4 --- /dev/null +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-futexes.xml @@ -0,0 +1,88 @@ +<?xml version='1.0'?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> + + + <section id="futexcontentionsect"> + <title>Identifying Contended User-Space Locks</title> + + +<remark> + WAR STORY: Futex contention http://sourceware.org/systemtap/wiki/WSFutexContention?highlight=((WarStories)) +</remark> + +<remark> +no script in examples +</remark> + + + <para>This section describes how to identify contended user-space locks throughout the system within a specific time period. The ability to identify contended user-space locks can help you investigate hangs that you suspect may be caused by <command>futex</command> contentions.</para> + + <para>Simply put, a <command>futex</command> contention occurs when multiple processes are trying to access the same region of memory. In some cases, this can result in a deadlock between the processes in contention, thereby appearing as an application hang.</para> + + <para>To do this, <xref linkend="futexcontention"/> probes the <command>futex</command> system call.</section> + +<formalpara id="futexcontention"> + <title>futexcontention.stp</title> +<para> +<programlisting> +global thread_thislock # short +global thread_blocktime # +global FUTEX_WAIT = 0, FUTEX_WAKE = 1 + +global lock_waits # long-lived stats on (tid,lock) blockage elapsed time +global process_names # long-lived pid-to-execname mapping + +probe syscall.futex { + if (op != FUTEX_WAIT) next # we don't care about originators of WAKE events + t = tid () + process_names[pid()] = execname() + thread_thislock[t] = $uaddr + thread_blocktime[t] = gettimeofday_us() +} + +probe syscall.futex.return { + t = tid() + ts = thread_blocktime[t] + if (ts) { + elapsed = gettimeofday_us() - ts + lock_waits[pid(), thread_thislock[t]] <<< elapsed + delete thread_blocktime[t] + delete thread_thislock[t] + } +} + +probe end { + foreach ([pid+, lock] in lock_waits) + printf ("%s[%d] lock %p contended %d times, %d avg us\n", + process_names[pid], pid, lock, @count(lock_waits[pid,lock]), @avg(lock_waits[pid,lock])) +} +</programlisting> +</para> +</formalpara> + +<para><xref linkend="futexcontention"/> needs to be manually stopped; upon exit, it prints the following information:</para> + +<itemizedlist> + <listitem><para>Name and ID of the process responsible for a contention</para></listitem> + <listitem><para>The region of memory it contested</para></listitem> + <listitem><para>How many times the region of memory was contended</para></listitem> + <listitem><para>Average time of contention throughout the probe</para></listitem> +</itemizedlist> + +<para><xref linkend="futexcontentionoutput"/> contains the output of <xref linkend="futexcontention"/> upon exiting the script after approximately 20 seconds.</para> + + +<example id="futexcontentionoutput"> + <title><xref linkend="futexcontention"/> Sample Output</title> +<screen> +automount[2825] lock 0x00bc7784 contended 18 times, 999931 avg us +synergyc[3686] lock 0x0861e96c contended 192 times, 101991 avg us +synergyc[3758] lock 0x08d98744 contended 192 times, 101990 avg us +synergyc[3938] lock 0x0982a8b4 contended 192 times, 101997 avg us +</screen> +</example> + + + </section> + diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml index 7145b622..fb2dba54 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml @@ -29,6 +29,7 @@ <xi:include href="Useful_Scripts-inodewatch.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Useful_Scripts-inodewatch2.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Useful_Scripts-functioncalls.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Useful_Scripts-futexes.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <!-- <xi:include href="Useful_Scripts-Network.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Useful_Scripts-Signals.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Useful_Scripts-Syscalls.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> |