--- /dev/null
+Content-type: text/html
+
+<HTML><HEAD><TITLE>Manpage of LKET</TITLE>
+</HEAD><BODY>
+<H1>LKET</H1>
+Section: File Formats (5)<BR>Updated: @DATE@<BR><A HREF="#index">Index</A>
+<A HREF="http://localhost/cgi-bin/man/man2html">Return to Main Contents</A><HR>
+
+<A NAME="lbAB"> </A>
+<H2>NAME</H2>
+
+LKET - Linux Kernel Event Trace tool based on SystemTap
+<P>
+
+
+
+<P>
+<A NAME="lbAC"> </A>
+<H2>DESCRIPTION</H2>
+
+<P>
+The Linux Kernel Event Trace (LKET) tool is an extension to the tapsets
+library available on SystemTap. Its goal is to utilize the dynamic probing
+capabilities provided through SystemTap to create a set of standard hooks
+that probe pre-defined places in the kernel. It can be used to collect
+important information that can be used as a starting point to analyze
+a performance problem in their system.
+<P>
+The LKET tapsets are designed to only trace the events selected by the
+user. Once the data has been collected, it is then post-processed
+according to the need of the user. Trace data can be processed in
+various different ways to generate simple to complex reports.
+<P>
+<A NAME="lbAD"> </A>
+<H2>EVENT HOOKS</H2>
+
+<P>
+The following sections enumerate the variety of event hooks implemented
+in LKET and their trace data format. Each event hook contains common data
+as well as some data that is specific to that event hook.
+<P>
+The data common( i.e.
+<I>common_data</I>
+
+)
+in the following subsecions) to all event hooks is:
+<DL COMPACT><DT><DD>
+<I>GroupID, hookID, second, usec, tgid, ppid, pid, cpu_id</I>
+
+</DL>
+
+<P>
+Each event hook group is a collection of those hooks that have
+similarities of what they could trace. And the ID of each event hook
+is defined in the context of its corresponding group.
+<P>
+<A NAME="lbAE"> </A>
+<H3>SYSTEM CALLS (GROUPID=1)</H3>
+
+You could use
+<I>addevent.syscall</I>
+
+to trace the entry and return of all system calls.
+It contains two sub event hooks:
+
+<DL COMPACT>
+<DT><B>addevent.syscall.entry (HOOKID=1)</B>
+
+<DD>
+Trace entry of all system calls.
+<P>
+Data format is:
+<P>
+<I>common_data, syscall_name</I>
+
+<DT><B>addevent.syscall.return (HOOKID=2)</B>
+
+<DD>
+Trace return of all system calls.
+<P>
+Data format is:
+<P>
+<I>common_data, syscall_name</I>
+
+<P>
+</DL>
+<A NAME="lbAF"> </A>
+<H3>PROCESS CREATION (GROUPID=2)</H3>
+
+You could use
+<I>addevent.process</I>
+
+to trace fork and execve of processes.
+It contains two sub event hooks:
+
+<DL COMPACT>
+<DT><B>addevent.process.fork (HOOKID=2)</B>
+
+<DD>
+Trace fork of processes
+<P>
+Data format is:
+<P>
+<I>common_data, new_process_id</I>
+
+<DT><B>addevent.process.execve (HOOKID=3)</B>
+
+<DD>
+Trace execve of new processes
+<P>
+Data format is:
+<P>
+<I>common_data, new_process_name</I>
+
+<P>
+</DL>
+<A NAME="lbAG"> </A>
+<H3>IO SCHEDULER ACTIVITIES (GROUPID=3)</H3>
+
+You could use
+<I>addevent.ioscheduler</I>
+
+to trace the IO scheduler activities. It contains three sub event hooks:
+
+<DL COMPACT>
+<DT><B>addevent.ioscheduler.elv_next_request (HOOKID=1)</B>
+
+<DD>
+Trace when a request is retrieved from request queue
+<P>
+Data format is:
+<P>
+<I>common_data, elevator_name, disk_major, disk_minor</I>
+
+<DT><B>addevent.ioscheduler.elv_add_request (HOOKID=2)</B>
+
+<DD>
+Trace when a request is added to the request queue
+<P>
+Data format is:
+<P>
+<I>common_data, elevator_name, disk_major, disk_minor</I>
+
+<DT><B>addevent.ioscheduler.elv_completed_request (HOOKID=3)</B>
+
+<DD>
+Trace when a request is completed
+<P>
+Data format is:
+<P>
+<I>common_data, elevator_name, disk_major, disk_minor</I>
+
+<P>
+</DL>
+<A NAME="lbAH"> </A>
+<H3>TASK SCHEDULE ACTIVITIES (GROUPID=4)</H3>
+
+You could use
+<I>addevent.tskdispatch</I>
+
+to trace the task scheduler activities. It contains two sub event hooks:
+
+<DL COMPACT>
+<DT><B>addevent.tskdispatch.ctxswitch (HOOKID=1)</B>
+
+<DD>
+Trace the process context switch
+<P>
+Data format is:
+<P>
+<I>common_data, prev_pid, next_pid, previous_process_state</I>
+
+<DT><B>addevent.tskdispatch.cpuidle (HOOKID=2)</B>
+
+<DD>
+Trace when cpu goes idle
+<P>
+Data format is:
+<P>
+<I>common_data, current_pid</I>
+
+<P>
+</DL>
+<A NAME="lbAI"> </A>
+<H3>SCSI ACTIVITIES (GROUPID=5)</H3>
+
+You could use
+<I>addevent.scsi</I>
+
+to trace the scsi layer activities. It contains four sub event hooks:
+
+<DL COMPACT>
+<DT><B>addevent.scsi.ioentry (HOOKID=1)</B>
+
+<DD>
+mid-layer prepares a IO request
+<P>
+Data format is:
+<P>
+<I>common_data, disk_major, disk_minor, device_state</I>
+
+<DT><B>addevent.scsi.iodispatching (HOOKID=2)</B>
+
+<DD>
+Dispatch a command to the low-level driver
+<P>
+Data format is:
+<P>
+<I>common_data, device_state, scsi_info, data_direction, reqbuf_addr, reqbuf_len, cmd_identifier</I>
+
+<P>
+Where
+<I>scsi_info</I>
+
+is the combination of:
+<P>
+
+<BR>
+
+<DL COMPACT><DT><DD>
+<PRE>
+((cmd->device->host->host_no & 0xFF) << 24) |
+((cmd->device->channel & 0xFF) << 16) |
+((cmd->device->lun & 0xFF) << 8) |
+(cmd->device->id & 0xFF)
+
+</PRE>
+
+</DL>
+
+
+<P>
+<DT><B>addevent.scsi.iodone (HOOKID=3)</B>
+
+<DD>
+I/O is done by low-level driver
+<P>
+Data format is:
+<P>
+<I>common_data, scsi_info, data_direction, cmd_identifier</I>
+
+<DT><B>addevent.scsi.iocompleted (HOOKID=4)</B>
+
+<DD>
+mid-layer processed the completed IO
+<P>
+Data format is:
+<P>
+<I>common_data, scsi_info, data_direction, cmd_identifier, bytes_done</I>
+
+<P>
+</DL>
+<A NAME="lbAJ"> </A>
+<H3>PAGE FAULT (GROUPID=6)</H3>
+
+You could use
+<I>addevent.pagefault</I>
+
+to trace page fault events. It contains only one sub event hooks:
+
+<DL COMPACT>
+<DT><B>addevent.pagefault (HOOKID=1)</B>
+
+<DD>
+<P>
+Data format is:
+<P>
+<I>common_data, memory_address, write_access</I>
+
+<P>
+</DL>
+<A NAME="lbAK"> </A>
+<H3>NETWORK DEVICE ACTIVITIES (GROUPID=7)</H3>
+
+You could use
+<I>addevent.netdev</I>
+
+to trace the network device activities. It contains two sub event hooks:
+
+<DL COMPACT>
+<DT><B>addevent.netdev.receive (HOOKID=1)</B>
+
+<DD>
+network device receives a packet
+<P>
+Data format is:
+<P>
+<I>netdev_name, data_length, protocol, buffer_length</I>
+
+<P>
+<DT><B>addevent.netdev.transmit</B>(HOOKID=2)
+
+<DD>
+A packet will be sent out by network device
+<P>
+Data format is:
+<P>
+<I>netdev_name, data_length, protocol, buffer_length</I>
+
+<P>
+</DL>
+<A NAME="lbAL"> </A>
+<H2>BACKTRACE</H2>
+
+<P>
+Some event hooks have the capability of print backtrace. But since
+backtrace printing is costly, it is defaultly turned off.
+<P>
+To print backtrace, you can just add "backtrace=1" into the probes, e.g:
+
+<BR>
+
+<DL COMPACT><DT><DD>
+<PRE>
+probe addevent.scsi.ioentry
+{
+ backtrace=1
+}
+
+</PRE>
+
+</DL>
+
+
+<P>
+By default backtrace=0
+<P>
+Currently the following events could be able to print backtrace:
+
+<BR>
+
+<DL COMPACT><DT><DD>
+<PRE>
+<B>addevent.ioscheduler.elv_next_request</B>
+<B>addevent.ioscheduler.elv_add_request</B>
+<B>addevent.netdev.transmit</B>
+<B>addevent.scsi.ioentry</B>
+<B>addevent.scsi.iodispatching</B>
+<B>addevent.tskdispatch.cpuidle</B>
+<B>addevent.syscall.entry</B>
+<B>addevent.syscall.return</B>
+
+</PRE>
+
+</DL>
+
+
+<P>
+<A NAME="lbAM"> </A>
+<H2>TRACE DATA FORMAT</H2>
+
+<P>
+By default, LKET will log the trace data in binary format.
+<P>
+To get a better performance for binary tracing, the "-b" option should
+be turned on for stap and thus -M option has to be added to stop stpd
+merging per-cpu files.
+<P>
+You could use the command
+<I>lket-b2a</I>
+
+to convert the binary trace data
+generated by LKET into readable data in ascii format.
+<P>
+<I>lket-b2a</I>
+
+uses the pre-cpu binary trace data files as inputs, and generates
+an output file named
+<I>lket.out</I>
+
+You should use "stap -b -M" with LKET to get those pre-cpu files
+(stpd_cpu*) before using it.
+<P>
+<P>
+If you want LKET to log trace data in ASCII format directly, you should:
+
+<BR>
+
+<DL COMPACT><DT><DD>
+<PRE>
+stap -D ASCII_TRACE ...
+
+</PRE>
+
+</DL>
+
+
+<P>
+<A NAME="lbAN"> </A>
+<H2>EXAMPLES</H2>
+
+<P>
+Here are some examples of using LKET:
+<P>
+<DL COMPACT>
+<DT>To turn on all event hooks:<DD>
+stap -e "probe addevent.* {}" -I /usr/local/share/systemtap/tapsets/LKET -b -M
+<DT>To probe syscall:<DD>
+stap -e "probe addevent.syscall {}" -I /usr/local/share/systemtap/tapsets/LKET -b -M
+<DT>To only probe syscall.entry:<DD>
+stap -e "probe addevent.syscall.entry {}" -I /usr/local/share/systemtap/tapsets/LKET -b -M
+<DT>To probe netdev transmition and print the backtrace:<DD>
+stap -e "probe addevent.netdev.transmit { backtrace=1 }" -I /usr/local/share/systemtap/tapsets/LKET -b -M
+<P>
+<P>
+</DL>
+<A NAME="lbAO"> </A>
+<H2>SEE ALSO</H2>
+
+<I><A HREF="http://localhost/cgi-bin/man/man2html?1+stap">stap</A></I>(1)
+
+<P>
+
+<HR>
+<A NAME="index"> </A><H2>Index</H2>
+<DL>
+<DT><A HREF="#lbAB">NAME</A><DD>
+<DT><A HREF="#lbAC">DESCRIPTION</A><DD>
+<DT><A HREF="#lbAD">EVENT HOOKS</A><DD>
+<DL>
+<DT><A HREF="#lbAE">SYSTEM CALLS (GROUPID=1)</A><DD>
+<DT><A HREF="#lbAF">PROCESS CREATION (GROUPID=2)</A><DD>
+<DT><A HREF="#lbAG">IO SCHEDULER ACTIVITIES (GROUPID=3)</A><DD>
+<DT><A HREF="#lbAH">TASK SCHEDULE ACTIVITIES (GROUPID=4)</A><DD>
+<DT><A HREF="#lbAI">SCSI ACTIVITIES (GROUPID=5)</A><DD>
+<DT><A HREF="#lbAJ">PAGE FAULT (GROUPID=6)</A><DD>
+<DT><A HREF="#lbAK">NETWORK DEVICE ACTIVITIES (GROUPID=7)</A><DD>
+</DL>
+<DT><A HREF="#lbAL">BACKTRACE</A><DD>
+<DT><A HREF="#lbAM">TRACE DATA FORMAT</A><DD>
+<DT><A HREF="#lbAN">EXAMPLES</A><DD>
+<DT><A HREF="#lbAO">SEE ALSO</A><DD>
+</DL>
+<HR>
+This document was created by
+<A HREF="http://localhost/cgi-bin/man/man2html">man2html</A>,
+using the manual pages.<BR>
+Time: 18:46:34 GMT, May 25, 2006
+</BODY>
+</HTML>
git://sourceware.org / systemtap-htdocs.git / commitdiff