Clozure CL Documentation

4.2. Trace

Clozure CL's tracing facility is invoked by an extended version of the Common Lisp trace macro. Extensions allow tracing of methods, as well as finer control over tracing actions.

TRACE {keyword global-value}* {spec | (spec {keyword local-value}*)}* [Macro]

The trace macro encapsulates the functions named by specs, causing trace actions to take place on entry and exit from each function. The default actions print a message on function entry and exit. Keyword/value options can be used to specify changes in the default behavior.

Invoking (trace) without arguments returns a list of functions being traced.

A spec is either a symbol that is the name of a function, or an expression of the form (setf symbol), or a specific method of a generic function in the form (:method gf-name {qualifier}* ({specializer}*)), where a specializer can be the name of a class or an EQL specializer.

A spec can also be a string naming a package, or equivalently a list (:package package-name), in order to request that all functions in the package to be traced.

By default, whenever a traced function is entered or exited, a short message is printed on *trace-output* showing the arguments on entry and values on exit. Options specified as key/value pairs can be used to modify this behavior. Options preceding the function specs apply to all the functions being traced. Options specified along with a spec apply to that spec only and override any global options. The following options are supported:

:methods {T | nil}

If true, and if applied to a spec naming a generic function, arranges to trace all the methods of the generic function in addition to the generic function itself.

:inside outside-spec | ({outside-spec}*)

Inhibits all trace actions unless the current invocation of the function being traced is inside one of the outside-spec's, i.e. unless a function named by one of the outside-spec's is currently on the stack. outside-spec can name a function, a method, or a package, as above.

:if form, :condition form

Evaluates form whenever the function being traced is about to be entered, and inhibits all trace actions if form returns nil. The form may reference the lexical variable ccl::args, which is a list of the arguments in this call. :condition is just a synonym for :if, though if both are specified, both must return non-nil.

:before-if form

Evaluates form whenever the function being traced is about to be entered, and inhibits the entry trace actions if form returns nil. The form may reference the lexical variable ccl::args, which is a list of the arguments in this call. If both :if and :before-if are specified, both must return non-nil in order for the before entry actions to happen.

:after-if form

Evaluates form whenever the function being traced has just exited, and inhibits the exit trace actions if form returns nil. The form may reference the lexical variable ccl::vals, which is a list of values returned by this call. If both :if and :after-if are specified, both must return non-nil in order for the after exit actions to happen.

:print-before form

Evaluates form whenever the function being traced is about to be entered, and prints the result before printing the standard entry message. The form may reference the lexical variable ccl::args, which is a list of the arguments in this call. To see multiple forms, use values: :print-before (values (one-thing) (another-thing)).

:print-after form

Evaluates form whenever the function being traced has just exited, and prints the result after printing the standard exit message. The form may reference the lexical variable ccl::vals, which is a list of values returned by this call. To see multiple forms, use values: :print-after (values (one-thing) (another-thing)).

:print form

Equivalent to :print-before form :print-after form.

:eval-before form

Evaluates form whenever the function being traced is about to be entered. The form may reference the lexical variable ccl::args, which is a list of the arguments in this call.

:eval-after form

Evaluates form whenever the function being has just exited. The form may reference the lexical variable ccl::vals, which is a list of values returned by this call.

:eval form

Equivalent to :eval-before form :eval-after form.

:break-before form

Evaluates form whenever the function being traced is about to be entered, and if the result is non-nil, enters a debugger break loop. The form may reference the lexical variable ccl::args, which is a list of the arguments in this call.

:break-after form

Evaluates form whenever the function being traced has just exited, and if the result is non-nil, enters a debugger break loop. The form may reference the lexical variable ccl::vals, which is a list of values returned by this call.

:break form

Equivalent to :break-before form :break-after form.

:backtrace-before form, :backtrace form

Evaluates form whenever the function being traced is about to be entered. The form may reference the lexical variable ccl::args, which is a list of the arguments in this call. The value returned by form is intepreted as follows:

nil: does nothing
:detailed: prints a detailed backtrace to *trace-output*.
(:detailed integer): prints the top integer frames of detailed backtrace to *trace-output*.
integer: prints top integer frames of a terse backtrace to *trace-output*.
anything else: prints a terse backtrace to *trace-output*.

Note that unlike with the other options, :backtrace is equivalent to :backtrace-before only, not both before and after, since it's usually not helpful to print the same backtrace both before and after the function call.

:backtrace-after form

Evaluates form whenever the function being traced has just exited. The form may reference the lexical variable ccl::vals, which is a list of values returned by this call. The value returned by form is intepreted as follows:

nil: does nothing
:detailed: prints a detailed backtrace to *trace-output*.
(:detailed integer): prints the top integer frames of detailed backtrace to *trace-output*.
integer: prints top integer frames of a terse backtrace to *trace-output*.
anything else: prints a terse backtrace to *trace-output*.

:before action

specifies the action to be taken just before the traced function is entered. action is one of:

:print: The default, prints a short indented message showing the function name and the invocation arguments
:break: Equivalent to :before :print :break-before t
:backtrace: Equivalent to :before :print :backtrace-before t
function: Any other value is interpreted as a function to call on entry instead of printing the standard entry message. It is called with its first argument being the name of the function being traced, the remaining arguments being all the arguments to the function being traced, and ccl:*trace-level* bound to the current nesting level of trace actions.

:after action

specifies the action to be taken just after the traced function exits. action is one of:

:print: The default, prints a short indented message showing the function name and the returned values
:break: Equivalent to :after :print :break-after t
:backtrace: Equivalent to :after :print :backtrace-after t
function: Any other value is interpreted as a function to call on exit instead of printing the standard exit message. It is called with its first argument being the name of the function being traced, the remaining arguments being all the values returned by the function being traced, and ccl:*trace-level* bound to the current nesting level of trace actions.

CCL:*TRACE-LEVEL* [Variable]

Variable bound to the current nesting level during execution of before and after trace actions. The default printing actions use it to determine the amount of indentation.

CCL:*TRACE-MAX-INDENT* [Variable]

The default before and after print actions will not indent by more than the value of ccl:*trace-max-indent* regardless of the current trace level.

CCL:TRACE-FUNCTION spec &key {keyword value}* [Function]

This is a functional version of the TRACE macro. spec and keywords are as for TRACE, except that all arguments are evaluated.

CCL:*TRACE-PRINT-LEVEL* [Variable]

The default print actions bind CL:*PRINT-LEVEL* to this value while printing. Note that this rebinding is only in effect during the default entry and exit messages. It does not apply to printing of :print-before/:print-after forms or any explicit printing done by user code.

CCL:*TRACE-PRINT-LENGTH* [Variable]

The default print actions bind CL:*PRINT-LENGTH* to this value while printing. Note that this rebinding is only in effect during the default entry and exit messages. It does not apply to printing of :print-before/:print-after forms or any explicit printing done by user code.

CCL:*TRACE-BAR-FREQUENCY* [Variable]

By default, this is nil. If non-nil it should be a integer, and the default entry and exit messages will print a | instead of space every this many levels of indentation.