5.2 Tracing options

There are a number of options available when using the trace facilities, which allow you both to restrict or expand upon the information printed during a trace. For instance, you can restrict tracing of a function to a particular process, or specify additional actions to be taken on function call entry and exit.

Note that the options and values available only apply to a particular traced function. Each traced function has its own, independent, set of options.

This section describes the options that are available. Each option can be set as described in the next subsection.

5.2.1 Evaluating forms on entry to and exit from a traced function

:before Trace keyword

:before list-of-forms

If non-nil, the list of forms is evaluated on entry to the function being traced. The forms are evaluated and the results printed after the arguments to the function.

Here is an example of its use. *traced-arglist* is bound to the list of arguments given to the function being traced. In this example, it is used to accumulate a list of all the arguments to fac across all iterations.

In the listener, initialize the variable args-in-reverse as follows:
```
(setq args-in-reverse ())
```

For the fac function used earlier, set the value of :before as follows:

(trace (fac :before ((push (car *traced-arglist*) args-in-reverse))))

In the listener, evaluate the following form:
```
(fac 3)
```

After evaluating this form, args-in-reverse has the value (1 2 3), that is, it lists the arguments which fac was called with, in reverse order.

:after Trace keyword

:after list-of-forms

If non-nil, this option evaluates a list of forms upon return from the function to be traced. The forms are evaluated and the results printed after the results of a call to the function.

This option is used in exactly the same way as :before. For instance, using the example for :before as a basis, create a list called results-in-reverse, and set the value of :after so that (car *traced-results*) is pushed onto this list. After calling fac, results-in-reverse contains the results returned from fac, in reverse order.

Note also that *traced-arglist* is still bound.

5.2.2 Evaluating forms without printing results

:eval-before Trace keyword

:eval-before list-of-forms

This option allows you to supply a list of forms for evaluation upon entering the traced function. The forms are evaluated after printing out the arguments to the function, but unlike :before their results are not printed.

:eval-after Trace keyword

:eval-after list-of-forms

This option allows you to supply a list of forms for evaluation upon leaving the traced function. The forms are evaluated after printing out the results of the function call, but unlike :after their results are not printed.

5.2.3 Using the debugger when tracing

:break Trace keyword

:break form

If form evaluates to non-nil, the debugger is entered directly from trace. If it returns nil, tracing continues as normal. This option lets you force entry to the debugger by supplying a form as simple as t.

Upon entry to the traced function, the standard trace information is printed, any supplied :before forms are executed, and then form is evaluated.

:break-on-exit Trace keyword

:break-on-exit form

Like :break, this option allows you to enter the debugger from trace. It differs in that the debugger is entered after the function call is complete.

Upon exit from the traced function, the standard trace information is printed, and then form is evaluated. Finally, any supplied :after forms are executed.

:backtrace Trace keyword

:backtrace backtrace

Generates a backtrace on each call to the traced function. backtrace can be any of the following values:

`:quick`	Like the `:bq` debugger command.
`t`	Like the `:b` debugger command.
`:verbose`	Like the `:b :verbose` debugger command.
`:bug-form`	Like the `:bug-form` debugger command.

5.2.4 Entering stepping mode

:step Trace keyword

:step form

When non-nil, this option puts the trace facility into stepper mode, where interpreted code is printed one step of execution at a time.

5.2.5 Configuring function entry and exit information

:entrycond Trace keyword

:entrycond form

This option controls the printing of information on entry to a traced function. form is evaluated upon entry to the function, and information is printed if and only if form evaluates to t. This allows you to turn off printing of function entry information by supplying a form of nil, as in the example below.

:exitcond Trace keyword

:exitcond form

This option controls the printing of information on exit from a traced function. form is evaluated upon exit from the function, and, like :entrycond, information is printed if and only if form evaluates to a non-nil value. This allows you to turn off printing of function exit information by supplying a form of nil.

An example of using :exitcond and :entrycond is shown below:

For the fac function, set the values of :entrycond and :exitcond as follows.
```
(trace (fac :entrycond (evenp (car *traced-arglist*))
            :exitcond (oddp (car *traced-arglist*))))
```
Information is only printed on entry to fac if the argument passed to fac is even. Conversely, information is only printed on exit from fac if the argument passed to fac is odd.

Enter the following call to <Code>fac</Code> in a listener:

CL-USER 24 > (fac 10)

The tracing information printed is as follows:

0 FAC > ...
  >> N : 10
    2 FAC > ...
      >> N : 8
        4 FAC > ...
          >> N : 6
            6 FAC > ...
              >> N : 4
                8 FAC > ...
                  >> N : 2
                  9 FAC < ...
                    << VALUE-0 : 1
              7 FAC < ...
                << VALUE-0 : 6
          5 FAC < ...
            << VALUE-0 : 120
      3 FAC < ...
        << VALUE-0 : 5040
  1 FAC < ...
    << VALUE-0 : 362880

5.2.6 Directing trace output

:trace-output Trace keyword

:trace-output stream

This option allows you to direct trace output to a stream other than the listener in which the original function call was made. By using this you can arrange to dispatch traced output from different functions to different places.

Consider the following example:

In the listener, create a file stream as follows:

CL-USER 1 > (setq str (open "trace.txt" :direction :output))
Warning: Setting unbound variable STR
#<STREAM::LATIN-1-FILE-STREAM C:\temp\trace.txt>

Set the value of the :trace-output option for the function fac to str.
Call the fac function, and then close the file stream as follows:
```
CL-USER 138 > (fac 8)
40320
 
CL-USER 139 > (close str)
T
```

Inspect the file trace.txt in order to see the trace output for the call of (fac 8).

5.2.7 Restricting tracing

:process Trace keyword

:process process

This lets you restrict tracing of a function to a particular process. If process evaluates to t, then the function is traced from within all processes (this is the default). Otherwise, the function is only traced from within the process that process evaluates to.

:when Trace keyword

:when form

This lets you invoke the tracing facilities on a traced function selectively. Before each call to the function, form is evaluated. If form evaluates to nil, no tracing is done. The contents of *traced-arglist* can be examined by form to find the arguments given to trace.

5.2.8 Storing the memory allocation made during a function call

:allocation Trace keyword

:allocation form

If form is non-nil, this prints the memory allocation, in bytes, made during a function call. The symbol that form evaluates to is used to accumulate the amount of memory allocated between entering and exiting the traced function.

Note that this symbol continues to be used as an accumulator on subsequent calls to the traced function; the value is compounded, rather than over-written.

Consider the example below:

For the fac function, set the value of :allocation to $$fac-alloc.
In the listener, call fac, and then evaluate $$fac-alloc.
```
CL-USER 152 > $$fac-alloc
744
```

5.2.9 Tracing functions from inside other functions

:inside Trace keyword

:inside list-of-functions

The functions given in the argument to :inside should reference the traced function in their implementation. The traced function is then only traced in calls to any function in the list of functions, rather than in direct calls to itself.

For example:

Define the function fac2, which calls fac, as follows:
```
(defun fac2 (x)
   (fac x))
```
For the fac function, set the value of :inside to fac2:
```
(trace (fac :inside fac2))
```
Call fac, and notice that no tracing information is produced.
```
CL-USER 2 > (fac 3)
6
```

Call fac2, and notice the tracing information.

Evaluate (fac2 3), and notice the tracing information.

0 FAC > ...
  >> N : 3
  1 FAC > ...
    >> N : 2
    2 FAC > ...
      >> N : 1
    2 FAC < ...
      << VALUE-0 : 1
  1 FAC < ...
    << VALUE-0 : 2
0 FAC < ...
  << VALUE-0 : 6