[m-rev.] for review: document trace count tools

[Julien Fischer]

On Wed, 13 Sep 2006, Ian MacLarty wrote:

> Here's the new diff:
>
> Index: doc/user_guide.texi
> ===================================================================
> RCS file: /home/mercury1/repository/mercury/doc/user_guide.texi,v
> retrieving revision 1.489
> diff -u -r1.489 user_guide.texi
> --- doc/user_guide.texi	4 Sep 2006 01:47:34 -0000	1.489
> +++ doc/user_guide.texi	13 Sep 2006 08:08:12 -0000
> @@ -1193,6 +1193,7 @@
> * I/O tabling::
> * Debugger commands::
> * Declarative debugging::
> +* Trace counts::
> @end menu
>
> @node Quick overview
> @@ -3706,10 +3707,10 @@
> This can be done by compiling the program with deep tracing enabled
> (either by compiling in a .debug or .decldebug grade
> or with the @samp{--trace deep} or @samp{--trace rep} compiler options)
> -and then running the program
> -with the MERCURY_OPTIONS environment variable set to @samp{--trace-count}.
> -This will generate a file called @samp{.mercury_trace_counts}
> -which contains a summary of the program's execution.
> +and then running the program under mtc.
> +This will generate a file with the prefix
> + at samp{.mercury_trace_counts} and a unique suffix,
> +that contains a summary of the program's execution
> This summary is called a slice.
> Copy the generated slice to a new file for each test case,
> to end up with some passing slices,

Is this last step necessary now that each of the trace count files has 
a unique suffix?

> @@ -3753,9 +3754,9 @@
> breakpoint on the goal.
> @item @samp{Pass (total passing test runs)}:
> The total number of times the goal was executed in all the passing test runs.
> -This is followed by a number in parenthesis which indicates the number of test
> +This is followed by a number in parentheses which indicates the number of test
> runs the goal was executed in.  The heading of this column also has a number in
> -parenthesis which is the total number of passing test cases.  In the example
> +parentheses which is the total number of passing test cases.  In the example
> above we can see that 3 passing tests were run.
> @item @samp{Fail}:
> The number of times the goal was executed in the failing test run.
> @@ -3774,7 +3775,7 @@
> The name of a file containing a list of the files containing the passing
> slices can be given with the @samp{-p} or @samp{--pass-trace-counts} option.
> Alternatively a separate @samp{set pass_trace_counts @var{filename}} command
> -can be given.
> +can be given.  See @ref{Trace counts} for more information about trace counts.
> @sp 1
> The table can be sorted on the Pass, Fail or Suspicion columns, or a
> combination of these.  This can be done with the @samp{-s} or @samp{--sort}
> @@ -4699,6 +4700,236 @@
> You can also change the search mode from within the declarative debugger
> with the @samp{mode} command.
>
> + at node Trace counts
> + at section Trace counts
> +
> +A program with debugging enabled can be run in a special mode that causes it
> +to dump out a summary of its execution,
> +called a @emph{trace count} or @emph{slice}.

How about:

 	A program compiled with debugging enabled may be run in a
 	special mode that causes it to write out a summary of its
 	execution to a file.  This summary is called a
 	@emph{trace count} or @emph{slice}.


> +A slice is a record of how many times each @emph{label} in the program was
> +executed for a particular run.
> +A label is a point in the source code where a debugger event can be triggered.
> +

I would give some examples,

 	A label is a point in the source code where a debugger event,
 	such as CALL or EXIT, can be triggered.

> +Slices are useful for determining what parts of a failing program are being run
> +and possibly causing the failure.

> +Slices from failing and passing runs can be compared to see which parts of the
> +program are being run in the failing runs,
> +but not the passing runs.
> +
> + at menu
> +* mtc::
> +* mslice::
> +* mdice::
> +* mtc_union::
> + at end menu
> +
> + at node mtc
> + at subsection mtc
> +
> +To generate a slice for a program run, first compile the program with deep
> +tracing enabled
> +(either by using the @samp{--trace deep} option or
> +compiling the program in a debugging grade).
> +Then invoke the program with the mtc script, passing any required
> +arguments after the program name.
> + at sp 1
> +For example:
> + at example
> +mtc ./myprog arg1 arg2
> + at end example
> + at sp 1
> +The program will run as usual, except that when it terminates it will dump

s/dump/write/

> +a summary of the run to a file with the prefix @samp{.mercury_trace_counts}
> +and a unique suffix.
> +The generated slice can then be analysed with the @samp{mslice}
> +and @samp{mdice} tools
> +and can also be used to help direct a declarative debugging search
> +(see @ref{Search Modes}).

I would reword that as:

 	The generated slice can be analyased by the @samp{mslice}
 	and @samp{mdice} tools.  It can also be used to help direct
 	a declarative debugging search (see @ref{Search Modes}).

> +
> + at node mslice
> + at subsection mslice
> +
> +Once a slice has been generated it can be viewed in various ways using the
> +mslice tool.
> +The output of the mslice tool will look something like the following:
> + at sp 1
> + at example
> +Procedure            Path/Port File:Line Count (1)
> +pred mrg.merge/3-0   CALL      mrg.m:60     14 (1)
> +pred mrg.merge/3-0   EXIT      mrg.m:60     14 (1)
> +pred mrg.msort_n/4-0 CALL      mrg.m:33     12 (1)
> +pred mrg.msort_n/4-0 EXIT      mrg.m:33     12 (1)
> +pred mrg.msort_n/4-0 <?;>      mrg.m:35     12 (1)
> + at end example
> + at sp 1
> +Each row corresponds to a label in the program and the meanings of the columns
> +are as follows:

Make that two sentences, e.g.

 	Each row corresponds to ...
 	The meaning of the columns are ...

> + at itemize @bullet
> + at item @samp{Procedure}:
> +This column displays the procedure that the label relates to.
> + at item @samp{Path/Port}:
> +For labels that generate interface events this column displays
> +the event port and for labels that generate internal events it
> +displays the goal path.

Add a pointer to where internal events are defined (if there is such
a place.)

> + at item @samp{File:Line}:
> +This column displays the context of the label.
> + at item @samp{Count}:
> +This column displays how many times the particular label was executed.

Delete "particular".

> +The number in parentheses for each label row says in how many runs the label
> +was executed.
> +The number in parentheses in the heading row (after the word "Count")
> +indicates how many runs were analysed by the mslice tool.
> + at end itemize
> +
> + at sp 1
> +
> +The mslice tool is invoked using a command of the form:
> + at example
> +mslice [-s sortspec] [-l N] [-m module] file
> + at end example
> + at sp 1
> +where @samp{file} may be a generated trace counts file, or a file containing

Is it a "trace counts" file or "trace count" file?

> +a list of generated trace count file names.
> + at sp 1
> +The @samp{-s} or @samp{--sort} option specifies how the output should be
> +sorted.
> + at samp{sortspec} should be a string made up of any combination of the letters
> + at samp{cCtT}.
> +Each letter specifies a column and direction to sort on:
> + at itemize @bullet
> + at item @samp{c}: Count ascending
> + at item @samp{C}: Count descending
> + at item @samp{t}: Number of runs ascending
> + at item @samp{T}: Number of runs descending
> + at end itemize
> + at sp 1
> +For example the option @samp{-s cT} will sort the output table by the
> +Count column in ascending order.  If the counts for two or more labels are the
> +same, then those labels will be sorted by number of runs in descending order.
> + at sp 1
> +The @samp{-l} or @samp{--limit} option limits the output to @samp{N} lines.
> + at sp 1
> +The @samp{-m} or @samp{--module} option limits the output to labels only
> +from the given module.
> + at sp 1
> +
> + at node mdice
> + at subsection mdice
> +
> +A dice is a comparison between passing and failing runs of a program.
> + at sp 1
> +To use the @samp{mdice} tool one must first generate a set of trace count
> +files for passing runs and a set of trace count files for failing runs
> +using the @samp{mtc} tool.
> +Once this has been done, the @samp{mdice} command
> +can be used to display a table of statistics
> +that compares the passing runs to the failing runs.
> + at sp 1
> +Here is an example of the output of the @samp{mdice} tool:
> + at sp 1
> + at example
> +Procedure        Path/Port  File:Line Pass (3) Fail Suspicion
> +pred s.mrg/3-0   <s2;c2;e;> s.m:74       0 (0)    1      1.00
> +pred s.mrg/3-0   <s2;c2;t;> s.m:67      10 (3)    4      0.29
> +pred s.mrg/3-0   CALL       s.m:64      18 (3)    7      0.28
> +pred s.mrg/3-0   EXIT       s.m:64      18 (3)    7      0.28
> + at end example
> + at sp 1
> +This example tells us that the @samp{else} in @samp{s.m} on line 74
> +was executed once in the failing test run,
> +but never during the passing test runs,
> +so this would be a good place to start looking for a bug.
> + at sp 1
> +Each row corresponds to a label in the program and the meanings of the
> +columns are as follows:
> + at itemize @bullet
> + at item @samp{Procedure}:
> +This column displays the procedure the label relates to.
> + at item @samp{Path/Port}:
> +For labels that generate interface events this column displays
> +the event port and for labels that generate internal events it
> +displays the goal path.
> + at item @samp{File:Line}:
> +This column displays the context of the label.
> + at item @samp{Pass (total passing test runs)}:
> +This columns displays the total number of times the label was executed in all
> +the passing test runs.
> +This is followed by a number in parentheses which indicates the number of test
> +runs the label was executed in.
> +The heading of this column also has a number in
> +parentheses which is the total number of passing test cases.
> + at item @samp{Fail}:
> +This column displays the number of times the goal was executed in the failing
> +test run(s).
> + at item @samp{Suspicion}:
> +This columns displays a number between 0 and 1 which gives an indication of how
> +likely a particular goal is to be buggy.

s/is to be buggy/is to contain a bug/

> +The suspicion is calculated as Suspicion = F / (P + F) where F is the number of
> +times the goal was executed in failing runs and P is the number of times
> +the goal was executed in passing runs.
> + at end itemize
> + at sp 1
> +The @samp{mdice} tool is invoked with a command of the form:
> + at sp 1
> + at example
> +mdice [-s sortspec] [-l N] [-m module] passfile failfile
> + at end example
> + at samp{passfile} is either a generated trace counts file for a passing run,

again: trace counts or trace count (and below)

> +or a file containing a list of generated trace count filenames for passing
> +runs.
> + at samp{failfile} is either a generated trace counts file for a failing run,
> +or a file containing a list of generated trace count filenames for failing
> +runs.
> + at sp 1
> +The table can be sorted on the Pass, Fail or Suspicion columns, or a
> +combination of these.  This can be done with the @samp{-s} or @samp{--sort}
> +option.  The argument of this option is a string made up of any combination of
> +the letters @samp{pPfFsS}.  The letters in the string indicate how the table
> +should be sorted:
> + at sp 1
> + at itemize @bullet
> + at item @samp{p}: Pass ascending
> + at item @samp{P}: Pass descending
> + at item @samp{f}: Fail ascending
> + at item @samp{F}: Fail descending
> + at item @samp{s}: Suspicion ascending
> + at item @samp{S}: Suspicion descending
> + at end itemize
> + at sp 1
> +For example the string "SF" means sort the table by suspicion in descending
> +order, and if any two suspicions are the same, then by number of executions in
> +the failing run(s), also in descending order.
> + at sp 1
> +The option @samp{-l} or @samp{--limit} can be used to limit the number of lines
> +displayed.
> + at sp 1
> +The @samp{-m} or @samp{--module} option limits the output to the given module
> +and its submodules, if any.

 	... to a given module and any submodules.

> +
> + at sp 1
> +
> + at node mtc_union
> + at subsection mtc_union
> +
> +The @samp{mtc_union} tool can be used to combine several trace counts files
> +into one trace counts file.
> +This is useful when you have many trace counts files you wish to analyse with
> + at samp{mslice} or @samp{mdice}.
> +It avoids the overhead of reading all the files
> +each time @samp{mslice} or @samp{mdice} is invoked.
> +
> + at samp{mtc_union} is invoked by issuing a command of the form:
> + at sp 1
> + at example
> +mtc_union [-v] -o output_file file1 file2 ...
> + at end example
> + at sp 1
> + at samp{file1}, @samp{file2}, etc. are the trace counts files that should be
> +combined.
> +The new trace counts file will be written to @samp{output_file}.

s/counts/count/

> +If the @samp{-v} or @samp{--verbose} option is present then a progress

s/present/specified/

> +message will be displayed as files are merged.

s/as files/as the files/

Julien.
--------------------------------------------------------------------------
mercury-reviews mailing list
Post messages to:       mercury-reviews at csse.unimelb.edu.au
Administrative Queries: owner-mercury-reviews at csse.unimelb.edu.au
Subscriptions:          mercury-reviews-request at csse.unimelb.edu.au
--------------------------------------------------------------------------