[ltt-dev] [PATCH] Add formattedDump and textFilter documentation on user_guide.docbook

[Mathieu Desnoyers]

* Vincent Attard (vincent.attard at polymtl.ca) wrote:
> ---
>  doc/user/user_guide/docbook/user_guide.docbook |  120 ++++++++++++++++++++++--
>  1 files changed, 113 insertions(+), 7 deletions(-)
> 
> diff --git a/doc/user/user_guide/docbook/user_guide.docbook b/doc/user/user_guide/docbook/user_guide.docbook
> index ed9c960..e920eb3 100644
> --- a/doc/user/user_guide/docbook/user_guide.docbook
> +++ b/doc/user/user_guide/docbook/user_guide.docbook
> @@ -1,8 +1,6 @@
>  <?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.3//EN" "/usr/share/sgml/docbook/dtd/4.3/xdocbook.dtd">
>  <!--<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" >-->
> -
>  <book>
>  
>  <bookinfo>
> @@ -560,12 +558,120 @@ hand, if you choose to specify explicitly the loading of both modules like this
>  <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 registration of the options by the modules, therefore the invocation

what is being changed above ?

>  order of the modules.
>  </para>
>  </sect1>
> -
> +<sect1 id="formattedDump">
> +<title>The formatted dump module</title>
> +<para>
> +Like text dump the goal of this module is to convert the binary data of the
> +traces into a desired formatted text file. This module allows for a flexible
> +text output, where you specify which information you want. It also provides
> +severals preset format.

several

> +</para>
> +<para>
> +Formatted dump plugin prints a formatted output of each events in a trace.
> +The output format is defined as a parameter. It provides a default easy
> +to read format, a "strace-like" format and the original textDump format for
> +backward compatibility. Like text dump, formatted dump uses the batch analysis
> +module. That's why you may specify the -o switch for the output file name of
> +the formatted dump.
> +</para>
> +<para>
> +The formatted dump module is invoked just like the text module. It adds more
> +options that can be specified as argument. You may specify the -F switch for
> +the format of the output followed by your output format between quotes. The -T
> +switch activate the text dump format while -S provides the "strace-like" format.

activates

> +If there is no argument or option following formattedDump, it will provides the

or -> nor

will provide

> +default format, which is easier to read than textDump.
> +</para>
> +<para>
> +If you use the --help (or -h) option on the formattedDump module, you will see

pass the ... option to the ...

> +all the detail about the switches that can be used. You will notice that you
> +can use both the switches for batchAnalysis and those for formattedDump. You
> +will also remark that all interpreted sequences follow the FORMAT description.
> +</para>
> +<para>
> +For exemple, if you load the formattedDump module with -m formattedDump, it
> +will first load the batchAnalysis module, and then load itself. You have to add

This is a user document, it should not describe the architecture. Saying
that the batchAnalysis module is loaded is useless for the user.

> +the -t switch from batchAnalysis followed by the path to trace. Then you can
> +add the formatted dump options like this:
> +</para>
> +<screen>
> +<prompt>$</prompt> <userinput>lttv -m formattedDump -t path/to/trace -F
> +"event name:%e timestamp:%t process name:%p"</userinput>
> +</screen>
> +<para>
> +With the same exemple, you can add the -o switch followed by the name of the

example

> +file where you want extract the output:

extract -> store

> +<screen>
> +<prompt>$</prompt> <userinput>lttv -m formattedDump -t path/to/trace -F
> +"event name:%e timestamp:%t process name:%p -o output.txt"</userinput>
> +</screen>
> +</para>
> +<para>The get the full list of options for the format, use the help option on
> +the command line.
> +<screen>
> +<prompt>$</prompt> <userinput>lttv -m formattedDump -h</userinput>
> +</screen></para>
> +</sect1>
> +<sect1 id="textFilter">
> +<title>The text filter module</title>
> +<para>
> +The text filter module provides the ability to filter the events of a trace.
> +Unlike formattedDump which let you select which information to display,
> +textFilter lets you filter complete events and not simply their informations.

lets -> let

information

> +It should be used with either textDump or formattedDump the display the

to display

> +remaining events.
> +</para>
> +<para>
> +The possibilities of filtering are numerous through this module. You can filter
> +events by event name, channel name, time(current, creation, insertion,...),

events by: ...

> +pid, ppid, process name, cpu... and many other opportunities are provided. All
> +possible field and operators are listed in the switch -l (or --list) of

fields

> +textFilter.
> +</para>
> +<para>
> +The text filter module is invoked just like all others text modules of lttv

other

> +except that you should specify if you want use textDump or formattedDump for
> +displaying your trace. You also need describe your filtering expression with -e
> +switch followed by your filter request between quotes.
> +</para>
> +<para>
> +If you use the --help (or -h) option on the textFilter module, you will see
> +all the detail about the switches that can be used. Remember that all possible
> +filtering field are listed in --list switch.
> +</para>
> +<para>
> +This module is an addition of textDump and formattedDump. The combo textFilter
> +and formattedDump provides a complete filter of a trace: event and event's
> +informations.

information

> +</para>
> +<para>
> +If you load the textFilter module with -m textFilter, you should first add the
> +filtering expression, then load formattedDump (or textDump) module and use it
> +with its normal way. For exemple you can use textFilter and formattedDump like
> +this:
> +</para>
> +<screen>
> +<prompt>$</prompt> <userinput>lttv -m textFilter -e "channel.name=kernel"
> +-m formattedDump -t path/to/trace -F "channel name:%c timestamp:%t process
> +name:%p"</userinput>
> +</screen>
> +<para>
> +If you want use textDump instead of formattedDump with textFilter the same principle apply,
> + you just have to write:
> +<screen>
> +<prompt>$</prompt> <userinput>lttv -m textFilter -e
> +"event.name=kernel.syscall_entry" -m textDump -t path/to/trace</userinput>
> +</screen>
> +</para>
> +<para>To get the full list of options and filtering expressions, use the help
> +option followed by -l switch on the command line.
> +<screen>
> +<prompt>$</prompt> <userinput>lttv -m textFilter -h -l</userinput>
> +</screen></para>
> +</sect1>
>  </chapter>
> -
> -

This line removal could be removed.

Thanks,

Mathieu

>  </book>
> -- 
> 1.7.0.4
> 
> 
> _______________________________________________
> ltt-dev mailing list
> ltt-dev at lists.casi.polymtl.ca
> http://lists.casi.polymtl.ca/cgi-bin/mailman/listinfo/ltt-dev
> 

-- 
Mathieu Desnoyers
Operating System Efficiency R&D Consultant
EfficiOS Inc.
http://www.efficios.com