<?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="paracallgraph">
		<title>Call Graph Tracing</title>
		
<indexterm>
<primary>script examples</primary>
<secondary>call graph tracing</secondary>
</indexterm>

<indexterm>
<primary>examples of SystemTap scripts</primary>
<secondary>call graph tracing</secondary>
</indexterm>

<indexterm>
<primary>call graph tracing</primary>
<secondary>examples of SystemTap scripts</secondary>
</indexterm>	

<indexterm>
<primary>incoming/outgoing function calls, tracing</primary>
<secondary>examples of SystemTap scripts</secondary>
</indexterm>
<indexterm>
<primary>function calls (incoming/outgoing), tracing</primary>
<secondary>examples of SystemTap scripts</secondary>
</indexterm>
<indexterm>
<primary>tracing incoming/outgoing function calls</primary>
<secondary>examples of SystemTap scripts</secondary>
</indexterm>
<indexterm>
<primary>tracing call graph</primary>
<secondary>examples of SystemTap scripts</secondary>
</indexterm>

		<remark>
			WAR STORY: Call graph tracing http://sourceware.org/systemtap/wiki/WSCallGraph?highlight=((WarStories))
		</remark>
		
		<remark>
			script: http://sourceware.org/systemtap/examples/general/para-callgraph.stp
		</remark>	
				
		
	<para>This section describes how to trace incoming and outgoing function calls. </para>
	
<formalpara id="scriptcallgraph">
	<title>para-callgraph-simple.stp</title>
<para>
<programlisting>
<xi:include parse="text" href="extras/para-callgraph-simple.stp" xmlns:xi="http://www.w3.org/2001/XInclude" />
</programlisting>
</para>
</formalpara>		
<indexterm>
<primary>script examples</primary>
<secondary>multiple command-line arguments, example of</secondary>
</indexterm>

<indexterm>
<primary>examples of SystemTap scripts</primary>
<secondary>multiple command-line arguments, example of</secondary>
</indexterm>

<indexterm>
<primary>multiple command-line arguments, example of</primary>
<secondary>examples of SystemTap scripts</secondary>
</indexterm>
<indexterm>
<primary>example of multiple command-line arguments</primary>
<secondary>examples of SystemTap scripts</secondary>
</indexterm>

<para><xref linkend="scriptcallgraph"/> takes two command-line arguments:</para>
<indexterm>
<primary>script examples</primary>
<secondary>trigger function</secondary>
</indexterm>

<indexterm>
<primary>examples of SystemTap scripts</primary>
<secondary>trigger function</secondary>
</indexterm>

<indexterm>
<primary>trigger function</primary>
<secondary>examples of SystemTap scripts</secondary>
</indexterm>
<itemizedlist>

	<listitem><para>
			A <firstterm>trigger function</firstterm> (<command>@1</command>), which 
			enables or disables tracing on a per-thread basis. Tracing in each thread 
			will continue as long as the trigger function has not exited yet.  
		</para></listitem>
	
	<listitem><para>
			The kernel function/s whose entry/exit call you'd like to trace 
			(<command>@2</command>). 
		</para></listitem>
</itemizedlist>

<remark> please verify previous if correct; i'm particularly interested in finding out how to better describe "trigger function"</remark>
<indexterm>
<primary>script examples</primary>
<secondary>thread_indent(), sample usage</secondary>
</indexterm>

<indexterm>
<primary>examples of SystemTap scripts</primary>
<secondary>thread_indent(), sample usage</secondary>
</indexterm>

<indexterm>
<primary>thread_indent(), sample usage</primary>
<secondary>examples of SystemTap scripts</secondary>
</indexterm>

<para><xref linkend="scriptcallgraph"/> uses <command>thread_indent()</command>; as such, its output contains the timestamp, process name, and thread ID of <command>@2</command> (i.e. the probe function you are tracing). For more information about <command>thread_indent()</command>, refer to its entry in <xref linkend="systemtapscript-functions"/>.</para>

		<para>The following example contains an excerpt from the output for <command>stap para-callgraph.stp sys_read '*@fs/*.c'</command>:</para>
		
	
<example id="paracallgraphoutput">
	<title><xref linkend="scriptcallgraph"/> Sample Output</title>
<screen>
[...]
     0 klogd(1391):->sys_read
    14 klogd(1391): ->fget_light
    22 klogd(1391): &lt;-fget_light
    27 klogd(1391): ->vfs_read
    35 klogd(1391):  ->rw_verify_area
    43 klogd(1391):  &lt;-rw_verify_area
    49 klogd(1391):  ->kmsg_read
     0 sendmail(1696):->sys_read
    17 sendmail(1696): ->fget_light
    26 sendmail(1696): &lt;-fget_light
    34 sendmail(1696): ->vfs_read
    44 sendmail(1696):  ->rw_verify_area
    52 sendmail(1696):  &lt;-rw_verify_area
    58 sendmail(1696):  ->proc_file_read
    70 sendmail(1696):   ->loadavg_read_proc
    84 sendmail(1696):    ->proc_calc_metrics
    92 sendmail(1696):    &lt;-proc_calc_metrics
    95 sendmail(1696):   &lt;-loadavg_read_proc
   101 sendmail(1696):  &lt;-proc_file_read
   106 sendmail(1696):  ->dnotify_parent
   115 sendmail(1696):  &lt;-dnotify_parent
   119 sendmail(1696):  ->inotify_dentry_parent_queue_event
   127 sendmail(1696):  &lt;-inotify_dentry_parent_queue_event
   133 sendmail(1696):  ->inotify_inode_queue_event
   141 sendmail(1696):  &lt;-inotify_inode_queue_event
   146 sendmail(1696): &lt;-vfs_read
   151 sendmail(1696):&lt;-sys_read
</screen>
</example>

<!--
    function trace(entry_p) {
    if(tid() in trace)
    printf("%s%s%s\n",thread_indent(entry_p),
    (entry_p>0?"->":"&lt;-"),
probefunc())
}

global trace
probe kernel.function(@1).call {
if (execname() == "stapio") next # skip our own helper process
trace[tid()] = 1
trace(1)
}
probe kernel.function(@1).return {
trace(-1)
delete trace[tid()]
}

probe kernel.function(@2).call { trace(1) }
probe kernel.function(@2).return { trace(-1) }    
    
    
    -->
	</section>

