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

Ian MacLarty maclarty at csse.unimelb.edu.au
Wed Sep 13 12:56:59 AEST 2006
Previous message: [m-rev.] for review: parallel execution mechanism (2/2)
Next message: [m-rev.] for review: document trace count tools
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
Estimated hours taken: 1.5
Branches: main, 0.13

doc/user_guide.texi:
	Add a new section "Trace counts" to the debuggin chapter.
	Document the mtc, mslice, mdice and mtc_union tools.

mdbcomp/slice_and_dice.m:
	Fix a comment.

slice/mtc_union.m:
	Fix an incorrect usage message.

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 02:51:22 -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,
@@ -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,233 @@
 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}.
+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.
+
+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 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
+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}).
+
+ 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:
+ at itemize @bullet
+ at item @samp{Procedure}:
+This column displays the procedure the label relates to.
+ at item @samp{Path/Port}:
+This column displays different things depending on the type of label:
+for labels that generate interface events, the event port is displayed;
+for labels that generate internal events, the goal path is displayed.
+ 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.
+The number in parenthesis for each label row says in how many runs the label
+was executed.
+The number in parenthesis 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
+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 specificies 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 first by
+execution counts ascending and then by number of runs descending.
+ 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
+comparing 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 in 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}:
+This column displays different things depending on the type of label:
+for labels that generate interface events, the event port is displayed;
+for labels that generate internal events, the goal path is displayed.
+ 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 parenthesis which indicates the number of test
+runs the label was executed in.
+The heading of this column also has a number in
+parenthesis 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. 
+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,
+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.
+
+ 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} and 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}.
+If the @samp{-v} or @samp{--verbose} option is present then a progress
+message will be displayed as files are merged.
+
 @c ----------------------------------------------------------------------------
 
 @node Profiling
Index: mdbcomp/slice_and_dice.m
===================================================================
RCS file: /home/mercury1/repository/mercury/mdbcomp/slice_and_dice.m,v
retrieving revision 1.7
diff -u -r1.7 slice_and_dice.m
--- mdbcomp/slice_and_dice.m	5 Sep 2006 14:19:58 -0000	1.7
+++ mdbcomp/slice_and_dice.m	13 Sep 2006 01:49:24 -0000
@@ -63,7 +63,7 @@
     % to a string suitable for displaying on the screen, sorting it first
     % using SortStr. SortStr can be any combination of the letters "cCtT"
     % and indicates how the dice is to be sorted. See the documentation
-    % for the `slice' command in the user guide for an explanation of
+    % for the `mslice' tool in the user guide for an explanation of
     % the sort string. Take only the top N lines of the sorted list.
     %
     % If Module is not the empty string then only labels from the named
Index: slice/mtc_union.m
===================================================================
RCS file: /home/mercury1/repository/mercury/slice/mtc_union.m,v
retrieving revision 1.1
diff -u -r1.1 mtc_union.m
--- slice/mtc_union.m	11 Aug 2005 15:56:59 -0000	1.1
+++ slice/mtc_union.m	12 Sep 2006 13:26:14 -0000
@@ -97,7 +97,7 @@
 
 usage(!IO) :-
 	io__write_strings([
-		"Usage: mtc_union [-p] -o output_file file1 file2 ...\n",
+		"Usage: mtc_union [-v] -o output_file file1 file2 ...\n",
 		"The -v or --verbose option causes each trace count ",
 		"file name\n",
 		"to be printed as it is added to the union.\n",
--------------------------------------------------------------------------
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
--------------------------------------------------------------------------
Previous message: [m-rev.] for review: parallel execution mechanism (2/2)
Next message: [m-rev.] for review: document trace count tools
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
More information about the reviews mailing list