+++ /dev/null
-<?xml version="1.0" encoding="UTF-8" ?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "/usr/share/sgml/docbook/dtd/4.3/xdocbook.dtd">
-<!--<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" >-->
-
-<book>
-
-<bookinfo>
-<title>Linux Trace Toolkit Viewer User Guide</title>
-<authorgroup>
-<author>
-<firstname>Mathieu</firstname>
-<surname>Desnoyers</surname>
-</author>
-</authorgroup>
-
-<date>11/01/2006</date>
-<releaseinfo>1.00.02</releaseinfo>
-
-<abstract>
-<para>
-This document describes how to install <application>Linux Trace
-Toolkit Viewer</application> and how to use it.
-
-</para>
-</abstract>
-
-<keywordset>
-<keyword>Linux Trace Toolkit Viewer</keyword>
-<keyword>Linux Trace Toolkit</keyword>
-<keyword>tracing</keyword>
-<keyword>Linux</keyword>
-<keyword>visualization</keyword>
-<keyword>operating system</keyword>
-</keywordset>
-
-</bookinfo>
-
-<chapter>
-<title>Introduction</title>
-<para>
-Linux Trace Toolkit (LTT) is a tracing tool that permits to get all the possible
-execution information from the Linux Kernel. It is based on kernel
-instrumentation and a high-speed relay file system to copy the information from
-the kernel space to the user space.
-</para>
-
-<para>
-Linux Trace Toolkit Viewer (LTTV) is the second generation of visualization
-tool. It is based on a trace format (the files where the data is recorded on
-disk) written by the LTTng tracer.
-</para>
-
-<para>
-This document explains all the steps that are necessary in order to record a
-trace with LTT and view it with LTTV.
-</para>
-</chapter>
-
-<chapter>
-<title>Getting started</title>
-
-<sect1 id="install">
-<title>Installing LTTng and LTTV</title>
-<para>
-Follow the QUICKSTART guide found at
-<ulink url="http://ltt.polymtl.ca">ltt.polymtl.ca</ulink>.
-</para>
-
-<!--
-<title>Installing LTTV</title>
-<para>
-First, you must download the latests version of LTTV. You should get it from
-this site : <ulink url="http://ltt.polymtl.ca">ltt.polymtl.ca</ulink>.
-I suggest that you get it from the "Packages" section.
-</para>
-
-<para>
-You need a recent gcc compiler to compile the project. You might want to use gcc
-3.2 or newer.
-You will also need some libraries in order to compile it. They are described in
-the README of the LTTV package. These are GTK 2.0, GLIB 2.0, "popt" and Pango 1.0.
-Install them if they are not on your system. Remember that if you use a package
-manager from you favourite Linux distribution, you will need to specifically
-install the librairies'development packages.
-</para>
-
-
-<para>
-Then, you are ready to compile LTTV. Extract and untar the file you previously
-downloaded :
-</para>
-
-<screen>
-<prompt>$</prompt> <userinput>tar -xvzof LinuxTraceToolkitViewer-x.x-dddddddd.tar.bz2</userinput>
-</screen>
-
-<para>
-Then, go to the directory newly created, and type :
-</para>
-
-<screen>
-<prompt>$</prompt> <userinput>./configure</userinput>
-<prompt>$</prompt> <userinput>make</userinput>
-<prompt>#</prompt> <userinput>make install</userinput> (as root)
-</screen>
--->
-<para>
-At this point, LTTV is installed in the default directory. You may find the
-lttv executable in /usr/local/bin and the librairies in /usr/local/lib. You will
-also notice the presence of the convert executable in /usr/local/bin. This tool
-will be used later to convert from the Linux Trace Toolkit trace format to the
-LTTV format.
-</para>
-<!--
-<para>
-You are now ready to go to the next step : installing the LTT kernel tracer.
-</para>
-
-
-</sect1>
-
-
-
-<sect1 id="install-tracer">
-<title>Installing LTT kernel tracer</title>
-<para>
-The goal of this guide is not to describe the Linux Trace Toolkit project in
-details, as it is a
-seperate project for now. It just gives pointers to the basic steps you must
-take in order to generate a trace suitable for conversion.
-</para>
-
-<para>
-First, go to the <ulink url="http://ltt.polymtl.ca">ltt.polymtl.ca</ulink>
-website, in the "Patches for the Official LTT" section. Use the latest version
-of patches available. The file name convention used goes like this :
-aaaaaa-x.x\-\-bbbbb-y.y.patch. That means a patch made for aaaaa, release x.x,
-that adds bbbbb, release y.y to it. Notice the presence of the \-\- sign that
-separates the "from" field from the name of the patch applied. This way, it's
-impossible to be mixed up on the specific sequence of patch application. I
-suggest that you use the "relayfs", "ltt" and then "md" patches. The "md" patch
-adds events useful to LTTV that are not in the official LTT.
-</para>
-
-<para>
-Once you have the patches you need, get the matching Linux kernel version, apply
-the patches on it, configure it, install it, reboot with the new kernel. You then
-have an instrumented kernel ready for tracing. If you have problems during this phase,
-please refer to <ulink
-url="http://www.opersys.com/ltt">www.opersys.com/ltt</ulink>. If you need
-instructions about how to recompile a kernel, see
-<ulink url="http://www.tldp.org/HOWTO/Kernel-HOWTO/">Kernel-HOWTO</ulink>.
-</para>
-
-</sect1>
-
-<sect1 id="install-daemon">
-<title>Installing LTT trace recording daemon</title>
-<para>
-In order to install the LTT trace recording daemon, you should get the latest
-TraceToolkit (or ltt) package from the LTT ftp site.
-Use the link "Official Linux Trace Toolkit Packages" on the
-<ulink url="http://ltt.polymtl.ca">ltt.polymtl.ca</ulink> webpage to access it.
-As of November 30, 2004, the most recent version is 0.9.6-pre3.
-</para>
-<para>
-Then, you should apply the TraceToolkit patches from the LTTV website related
-to the package version. Get them from the "Patches for the Official LTT"
-section.
-</para>
-<para>
-You are now ready to install the daemon in your system. Please refer to the
-documentation in the package for details.
-</para>
-<para>
-You may now use the following command to record a sample 30 seconds trace in
-your current directory. Command line switches are described on the official
-LTT website.
-</para>
-<screen>
-<prompt>#</prompt><userinput>tracedaemon -ts30 sample.out sample.proc (as root) userinput></userinput>
-</screen>
-</sect1>
-
-
-
-<sect1 id="convert">
-<title>Conversion from LTT to LTTV trace format</title>
-<para>
-If you used the default directory for installation, you should find the
-conversion tool in /usr/local/bin/convert. Before using it, some other files are
-necessary. You will find them in
-/usr/local/share/LinuxTraceToolkitViewer/convert/. Those are sysInfo and
-core.xml.
-</para>
-<para>
-sysInfo is a script that get informations about the traced computer. It should
-be invoked like this :
-</para>
-<screen>
-<prompt>$</prompt> <userinput>sh /usr/local/LinuxTraceToolkitViewer/convert/sysInfo</userinput>
-</screen>
-<para>
-It creates a file named sysInfo.out. This file has to be present in the current
-directory where the convert tool will be executed. I suggest that you choose a
-destination directory where will be written converted traces right now, put sysInfo.out in it, at
-use it as current directory for running the convert tool.
-</para>
-<para>
-Once the sysInfo.out file is ready and you have a trace ready for conversion,
-you should invoke convert like the following example. This is for a uniprocessor
-computer. If you whish to get detailed explanation on the parameters, simply
-execute the convert tool without any option. You may also wish to see the
-/usr/local/LinuxTraceToolkitViewer/convert/README file.
-</para>
-<screen>
-<prompt>$</prompt> <userinput>/usr/local/bin/convert sample.proc 1 sample.trace sample.converted</userinput>
-</screen>
-<para>
-You must then copy the core event definition file to the converted trace directory :
-</para>
-<screen>
-<prompt>$</prompt> <userinput>cp /usr/local/share/LinuxTraceToolkitViewer/convert/core.xml sample.converted/</userinput>
-</screen>
-<para>
-You now have a converted trace ready for visualization in LTTV. Congratulations!
-</para>
--->
-</sect1>
-
-<sect1 id="running">
-<title>Running the executable with basic libraries</title>
-<para>
-Starting the graphical mode with the basic viewer activated is as simple as :
-</para>
-<screen>
-<prompt>$</prompt> <userinput>lttv-gui</userinput>
-</screen>
-<para>
-Using the text mode is very simple too. Look in /usr/local/lib/lttv/plugins for
-the list of modules. You may use the --help switch to get basic help on the
-command line parameters of every loaded modules. To simply output the events of
-a trace in a text file, try the textDump module. The batchAnalysis module
-permits to do batch mode analysis (state and statistics calculation ) on a
-trace.
-</para>
-<screen>
-<prompt>$</prompt> <userinput>lttv -L /usr/local/lib/lttv/plugins -m textDump --help</userinput>
-</screen>
-</sect1>
-</chapter>
-
-<chapter>
-<title>Using LTTV graphical interface</title>
-
-<sect1 id="mainwindow">
-<title>LTTV main window</title>
-<para>
-This section describes the main functionnalities that are provided by the LTTV
-GUI and how to use them.
-</para>
-<para>
-By default, when the lttv GUI starts with all the graphical modules loaded,
-it loads the statistics viewer, the control flow viewer, and the detailed event
-list inside a tab. Other viewers can be added later to this tab by interacting
-with the main window. Let's describe the operations available on the window :
-</para>
-<screenshot>
-<mediaobject>
-<imageobject>
-<imagedata srccredit="Mathieu Desnoyers, 2004" fileref="lttv-numbered-5.png"
-format="PNG" align="center"/>
-</imageobject>
-<imageobject>
-<imagedata srccredit="Mathieu Desnoyers, 2004"
-fileref="lttv-numbered-5.eps"
-format="EPS" align="center"/>
-</imageobject>
-<!--<imagedata srccredit="Mathieu Desnoyers, 2004" fileref="lttv-numbered-6.svg"
-format="SVG" align="center" scalefit="1"/>
-</imageobject>-->
-<caption><para>Linux Trace Toolkit Viewer GUI</para></caption>
-</mediaobject>
-</screenshot>
-<orderedlist>
-<listitem>
-<para>
-This toolbar allows you to navigate through the basic functionnalities of LTTV.
-The first button opens a new window and the second one, a new tab. You can leave
-your mouse over the buttons to read the information provided by the tooltips.
-</para>
-</listitem>
-<listitem>
-<para>
-This notebook, containing different tabs, lets you select the "Trace Set" you
-want to interact with. A trace set is an aggregation of traces, synchronised in
-time. You may also want to use one tab per viewer by simply cloning the traceset
-to a new tab. This way, you can have vertically stacked viewers in one tab, as
-well as different viewers, independant from the time interval. Note that once
-the Trace Set cloning is done, each trace set becomes completely independant.
-For Traceset cloning, see the File Menu.
-</para>
-</listitem>
-<listitem>
-<para>
-These buttons let you control the computation in progress on a trace. As
-sometimes the computation may last for a while, you may want to stop it, restart
-it from the beginning or simply to continue from where you stopped. This is
-exactly what those three buttons offer you.
-</para>
-</listitem>
-<listitem>
-<para>
-Buttons on the right side of the last spacer are semantically different from the
-others. While the other buttons at the left side of the bar are built in the
-lttv program and let you operate the basic functionnalities, the buttons at the
-right side let you add a viewer to the active Tab. They belong to the
-viewers themselves. The number of buttons that appears there should directly
-depend on the number of viewer's modules loaded.
-</para>
-</listitem>
-<listitem>
-<para>
-This is a tree representing the multiple statistics available for the current
-traceset. This is shown by the guistatistics viewer.
-</para>
-</listitem>
-<listitem>
-<para>
-This is the Y axis of the guicontrolflow viewer. It shows the process list of
-the traced system. You may notice that it grows : it dynamically adds
-process when they appear in the trace.
-</para>
-</listitem>
-<listitem>
-<para>
-This is a (missing) time bar for the X axis. Maybe will it be used for viewer
-specific buttons eventually. Work in progress.
-</para>
-</listitem>
-<listitem>
-<para>
-The is the current time selected. The concept of current event and current time
-selected is synchronised in a Tab for all the viewers. The control flow viewer
-shows it a vertical white dotted line. You move this marker by clicking on the
-background of the process state graph. This graph shows evolution of each
-process's state through time. The meaning of the colors will be explained later.
-</para>
-</listitem>
-<listitem>
-<para>
-This is the details event list. It shown the detailed information about each
-event of the trace. It is synchronised with the current time and current event,
-so selecting an event changes other viewer's current time and reciprocally.
-</para>
-</listitem>
-<listitem>
-<para>
-You can enter the values of start time and end time you wish to see on the
-screen here. It also supports pasting time as text input, simply by clicking of
-the "Time Frame", "start" or "end:" fields. A valid entry consists of any
-digital input separated by any quantity of non digital characters. For example :
-"I start at 356247.124626 and stop at 724524.453455" would be a valid input
-for the "Time Frame" field.
-</para>
-</listitem>
-<listitem>
-<para>
-This horizontal scrollbar modifies the window of time shown by all the viewers
-in the tab. It is linked with the fields below it (described at number 10 and
-12). Another way to modify the time shown is to use the zoom buttons of the
-toolbar (yes, the ones that looks like magnifying glasses).
-</para>
-</listitem>
-<listitem>
-<para>
-This field works just like the "Time Frame" field. It modifies the current time
-selected by the viewers. For example, changing its value will change the current
-event selected by the detailed events list and the current time selected by the
-control flow viewer.
-</para>
-</listitem>
-</orderedlist>
-</sect1>
-
-<sect1 id="ControlFlowColors">
-<title>Control Flow View Colors</title>
-<screenshot>
-<mediaobject>
-<imageobject>
-<imagedata srccredit="Mathieu Desnoyers, 2004" fileref="lttv-color-list.png"
-format="PNG" align="center"/>
-</imageobject>
-<imageobject>
-<imagedata srccredit="Mathieu Desnoyers, 2004"
-fileref="lttv-color-list.eps"
-format="EPS" align="center"/>
-</imageobject>
-<!--<imagedata srccredit="Mathieu Desnoyers, 2004" fileref="lttv-numbered-6.svg"
-format="SVG" align="center" scalefit="1"/>
-</imageobject>-->
-<caption><para>Control Flow View Color Legend</para></caption>
-</mediaobject>
-</screenshot>
-
-<para>
-Here is a description of the colors used in the control flow view. Each color
-represents a state of the process at a given time.
-</para>
-
-<itemizedlist>
-<listitem>
-<para>
-White : this color is used for process from which state is not known. It may
-happen when you seek quickly at a far time in the trace just after it has been
-launched. At that moment, the precomputed state information is incomplete. The
-"unknown" state is used to identify this. Note that the viewer gets refreshed
-once the precomputation ends.
-</para>
-</listitem>
-<listitem>
-<para>
-Green : This color is only used for process when they are running in user mode.
-That includes execution of all the source code of an executable as well as the
-libraries it uses.
-</para>
-</listitem>
-<listitem>
-<para>
-Pale blue : A process is doing a system call to the kernel, and the mode is
-switched from process limited rights to super user mode. Only code from the
-kernel (including modules) should be run in that state.
-</para>
-</listitem>
-<listitem>
-<para>
-Yellow : The kernel is running a trap that services a fault. The most frequent
-trap is the memory page fault trap : it is called every time a page is missing
-from physical memory.
-</para>
-</listitem>
-<listitem>
-<para>
-Orange : IRQ servicing routine is running. It interrupts the currently running
-process. As the IRQ does not change the currently running process (on some
-architectures it uses the same stack as the process), the IRQ state is shown in
-the state of the process. IRQ can be nested : a higher priority interrupt can
-interrupt a lower priority interrupt.
-</para>
-</listitem>
-<listitem>
-<para>
-Pink : SoftIRQ handler is running. A SoftIRQ is normally triggered by an
-interrupt that whishes to have some work done very soon, but not "now". This is
-especially useful, for example, to have the longest part of the network stack
-traversal done : a too long computation in the interrupt handler would increase
-the latency of the system. Therefore, doing the long part of the computation in
-a softirq that will be run just after the IRQ handler exits will permits to do
-this work while interrupts are enabled, without increasing the system latency.
-</para>
-</listitem>
-<listitem>
-<para>
-Dark red : A process in that state is waiting for an input/output operation to
-complete before it can continue its execution.
-</para>
-</listitem>
-<listitem>
-<para>
-Dark yellow : A process is ready to run, but waiting to get the CPU (a schedule
-in event).
-</para>
-</listitem>
-<listitem>
-<para>
-Dark purple : A process in zombie state. This state happens when a process
-exits and then waits for the parent to wait for it (wait() or waitpid()).
-</para>
-</listitem>
-<listitem>
-<para>
-Dark green : A process has just been created by its parent and is waiting for
-first scheduling.
-</para>
-</listitem>
-<listitem>
-<para>
-Magenta : The process has exited, but still has the control of the CPU. It may
-happend if it has some tasks to do in the exit system call.
-</para>
-</listitem>
-</itemizedlist>
-</sect1>
-</chapter>
-
-<chapter>
-<title>Using LTTV text modules</title>
-<sect1 id="batchAnalysis">
-<title>The batch analysis module</title>
-<para>
-This batch analysis module can be invoked like this :
-</para>
-<screen>
-<prompt>$</prompt> <userinput>lttv -L path/to/lib/plugins -m batchAnalysis\
--t trace1 -t trace2 ...</userinput>
-</screen>
-<para>
-It permits to call any registered action to perform in batch mode on all the
-trace set, which consists of the traces loaded on the command line. Actions that
-are built in the batchAnalysis module are statistics computation. They can be
-triggered by using the -s (--stats) switch.
-</para>
-<para>
-However, the batchAnalysis module is mostly a backend for every other text
-module that does batch computation over a complete trace set.
-</para>
-</sect1>
-<sect1 id="textDump">
-<title>The text dump module</title>
-<para>
- The goal of this module is to convert the binary data of the traces into
-a formatted text file.
-</para>
-<para>
-The text dump module is a good example of a usage of the batch analysis module
-backend. In fact, the text dump module depends on it. You don't need to
-explicitly load the batchAnalysis module though, as lttv offers a rich module
-backend that deals with the dependencies, loading the module automatically if
-needed.
-</para>
-<para>
-The text dump module is invoked just like the batchAnalysis module. It adds more
-options that can be specified in argument. You may specify the -o switch for the
-output file name of the text dump. You can enable the output of the field names
-(the identifier of the fields) with the -l switch. The -s switch, for process
-states, is very useful to indicate the state in which the process is when the
-event happens.
-</para>
-<para>
-If you use the --help option on the textDump module, you will see all the detail
-about the switches that can be used to show per cpu statistics and per process
-statistics. You will notice that you can use both the switches for the
-batchAnalysis module and those for textDump. You will also notice that the
-options --process_state (from textDump) and --stats (from batchAnalysis) has the
-same short name "-s". If you choose to invoke this option using the short name,
-it will use the option of the last module loaded just before the -s switch.
-</para>
-<para>
-For exemple, if you load the textDump module with -m textDump, it will first
-load the batchAnalysis module, and then load itself. As it is the last module
-loaded, the -s switch used after it will signify --process_stats. On the other
-hand, if you choose to specify explicitly the loading of both modules like this
-:
-</para>
-<screen>
-<prompt>$</prompt> <userinput>lttv -L path/to/lib/plugins -m batchAnalysis -s\
--m textDump -s -t trace</userinput>
-</screen>
-<para>
-The first "-s" will invoke batchAnalysis --stats and the second "-s" will invoke
-textDump --process_state. The list of options generated by --help follows the
-order of registration of the options by the modules, therefore the invocation
-order of the modules.
-</para>
-</sect1>
-
-</chapter>
-
-
-</book>
projects / lttv.git / blobdiff