— Macro: common-lisp:trace &rest specs

trace {Option Global-Value}* {Name {Option Value}*}*

trace is a debugging tool that provides information when specified functions are called. In its simplest form:

                 (TRACE NAME-1 NAME-2 ...)
     

The NAMEs are not evaluated. Each may be a symbol, denoting an individual function, or a string, denoting all functions fbound to symbols whose home package is the package with the given name.

Options allow modification of the default behavior. Each option is a pair of an option keyword and a value form. Global options are specified before the first name, and affect all functions traced by a given use of trace. Options may also be interspersed with function names, in which case they act as local options, only affecting tracing of the immediately preceding function name. Local options override global options.

By default, trace causes a printout on *trace-output* each time that one of the named functions is entered or returns. (This is the basic, ansi Common Lisp behavior of trace.) As an sbcl extension, the :report sb-ext:profile option can be used to instead cause information to be silently recorded to be inspected later using the sb-ext:profile function.

The following options are defined:

:report Report-Type

If Report-Type is trace (the default) then information is reported by printing immediately. If Report-Type is sb-ext:profile, information is recorded for later summary by calls to sb-ext:profile. If Report-Type is nil, then the only effect of the trace is to execute other options (e.g. print or BREAK).

:condition Form

:condition-after Form

:condition-all Form

If :condition is specified, then trace does nothing unless Form evaluates to true at the time of the call. :condition-after is similar, but suppresses the initial printout, and is tested when the function returns. :condition-all tries both before and after. This option is not supported with :report profile.

:break Form

:break-after Form

:break-all Form

If specified, and Form evaluates to true, then the debugger is invoked at the start of the function, at the end of the function, or both, according to the respective option.

:print Form

:print-after Form

:print-all Form

In addition to the usual printout, the result of evaluating Form is printed at the start of the function, at the end of the function, or both, according to the respective option. Multiple print options cause multiple values to be printed.

:wherein Names

If specified, Names is a function name or list of names. trace does nothing unless a call to one of those functions encloses the call to this function (i.e. it would appear in a backtrace.) Anonymous functions have string names like "DEFUN FOO". This option is not supported with :report profile.

:encapsulate {:DEFAULT | t | NIL}

If t, the tracing is done via encapsulation (redefining the function name) rather than by modifying the function. :default is the default, and means to use encapsulation for interpreted functions and funcallable instances, breakpoints otherwise. When encapsulation is used, forms are *not* evaluated in the function's lexical environment, but sb-debug:arg can still be used.

:methods {T | NIL}

If t, any function argument naming a generic function will have its methods traced in addition to the generic function itself.

:function Function-Form

This is a not really an option, but rather another way of specifying what function to trace. The Function-Form is evaluated immediately, and the resulting function is instrumented, i.e. traced or profiled as specified in report.

:condition, :break and :print forms are evaluated in a context which mocks up the lexical environment of the called function, so that sb-debug:var and sb-debug:arg can be used. The -after and -all forms are evaluated in the null environment.

— Macro: common-lisp:untrace &rest specs

Remove tracing from the specified functions. With no args, untrace all functions.

— Variable: sb-debug:*trace-indentation-step*

the increase in trace indentation at each call level

— Variable: sb-debug:*max-trace-indentation*

If the trace indentation exceeds this value, then indentation restarts at 0.

— Variable: sb-debug:*trace-encapsulate-default*

the default value for the :encapsulate option to trace

— Variable: sb-debug:*trace-values*

This is bound to the returned values when evaluating :break-after and :print-after forms.