3 Using Errortrace

(require errortrace)

3.1 Instrumentation and Profiling

By default, errortrace only instruments for stack-trace-on-exception. Profiling and coverage need to be enabled separately.

(instrumenting-enabled) → boolean?

(instrumenting-enabled on?) → void?

on? : any/c

A parameter that determines whether tracing instrumentation is enabled, #t by default. Affects only the way that source code is compiled, not the way that exception information is reported. The instrumentation for storing exception information slows most programs by a factor of 2 or 3.

(profiling-enabled) → boolean?

(profiling-enabled on?) → void?

on? : any/c

Errortrace’s profiling instrumentation is #f by default. To use it, you also need to ensure that instrumenting-enabled is on.

(profiling-record-enabled) → boolean?

(profiling-record-enabled on?) → void?

on? : any/c

Enables/disables the recording of profiling info for the instrumented code. The default is #t.

Profiling information is accumulated in a hash table. If a procedure is redefined, new profiling information is accumulated for the new version of the procedure, but the old information is also preserved.

Depending of the source program, profiling usually induces a factor of 2 to 4 slowdown in addition to any slowdown from the exception information instrumentation.

(output-profile-results paths? sort-time?) → void?

paths? : any/c

sort-time? : any/c

Gets the current profile results using get-profile-results and displays them. It optionally shows paths information (if it is recorded), and sorts by either time or call counts.

(get-profile-results) → list?

Returns a list of lists that contain all profiling information accumulated so far:

• the number of times a procedure was called.

• the number of milliseconds consumed by the procedure’s body across all calls (including the time consumed by any nested non-tail call within the procedure, but not including time consumed by a tail-call from the procedure).

• an inferred name (or #f) for the procedure.

• the procedure’s source in the form of a syntax object (which might, in turn, provide a source location file and position).

• optionally, a list of unique call paths (i.e. stack traces) recorded if profile-paths-enabled is set to #t. Each call path is a pair of

  • a count (the number of times the path occurred), and

  • a list containing two-element lists. Each two-element list contains

    • the calling procedure’s name or source expression, and

    • the calling procedure’s source file or #f.

  Collecting this information is relatively expensive.

(profile-paths-enabled) → boolean?

(profile-paths-enabled on?) → void?

on? : any/c

Enables/disables collecting path information for profiling. The default is #f, but setting the parameter to #t immediately affects all procedures instrumented for profiling information.

(clear-profile-results) → void?

Clears accumulated profile results.

3.2 Coverage

Errortrace can produce coverage information in two flavors: both count the number of times each expression in the source was used during execution. The first flavor uses a simple approach, where each expression is counted when executed; the second one uses the same annotations that the profiler uses, so only function bodies are counted. To see the difference between the two approaches, try this program:

(define (foo x) (if x 1 2))

(equal? (foo #t) 1)

The first approach will produce exact results, but it is more expensive; use it when you want to know how covered your code is (when the expected counts are small). The second approach produces coarser results (which, in the above case, will miss the 2 expression), but is less expensive; use it when you want to use the counts for profiling (when the expected counts are large).

(coverage-counts-enabled) → boolean? (coverage-counts-enabled on?) → void?   on? : any/c

(execute-counts-enabled) → boolean? (execute-counts-enabled on?) → void?   on? : any/c

Parameters that determine if the first (exact coverage) or second (profiler-based coverage) are enabled. Remember that setting instrumenting-enabled to #f also disables both.

(get-coverage-counts) → list?

(get-execute-counts) → list?

Returns a list of pairs, one for each instrumented expression. The first element of the pair is a syntax? object (usually containing source location information) for the original expression, and the second element of the pair is the number of times that the expression has been evaluated. These elements are destructively modified, so to take a snapshot you will need to copy them.

(annotate-covered-file   filename-path            [ display-string])   →   void?   filename-path : path-string?   display-string : (or/c string? false/c) = #f

(annotate-executed-file   filename-path            [ display-string])   →   void?   filename-path : path-string?   display-string : (or/c string? false/c) = "^.,"

Writes the named file to the current-output-port, inserting an additional line between each source line to reflect execution counts (as reported by get-coverage-counts or get-execute-counts). The optional display-string is used for the annotation: the first character is used for expressions that were visited 0 times, the second character for 1 time, ..., and the last character for expressions that were visited more times. It can also be #t for a maximal display ("012...9ABC...Z"), or #f for a minimal display ("#-").

3.3 Other Errortrace Bindings

The errortrace module also exports:

(print-error-trace output-port exn) → void?

output-port : output-port?

exn : exn?

The print-error-trace procedure takes a port and exception and prints the Errortrace-collected debugging information contained in the exception. It is used by the exception handler installed by Errortrace.

(error-context-display-depth) → integer?

(error-context-display-depth d) → void?

d : integer?

The error-context-display-depth parameter controls how much context Errortrace’s exception handler displays. The default value is 10,000.