% This LaTeX document was generated using the LaTeX backend of PlDoc,
% The SWI-Prolog documentation system



\section{library(prolog_trace): Print access to predicates}

\label{sec:prologtrace}

\begin{tags}
    \tag{See also}
\file{library(debug)} for adding conditional print statements to a
program.
\end{tags}

This library prints accesses to specified predicates by wrapping the
predicate.\vspace{0.7cm}

\begin{description}
    \predicate[det]{trace}{1}{:Pred}
\nodescription
    \predicate[det]{trace}{2}{:Pred, +PortSpec}
Print passes through \textit{ports} of specified predicates. \arg{Pred} is a,
possible partial, specification of a predicate as it is also used be
\predref{spy}{1} and similar predicates. Where a full predicate specification
is of the shape \verb$Module:Name/Arity$ (or `\Sidiv{}Arity for non-terminals),
both the module and arity may be omitted in which case \arg{Pred} refers
to all matching predicates. \arg{PortSpec} is either a single port
(\const{call}, \const{exit}, \const{fail} or \const{redo}), preceded with \verb$+$ or \verb$-$ or a
list of these. The predicate modifies the current trace
specification and then installs a suitable wrapper for the predicate
using \predref{wrap_predicate}{4}. For example:

\begin{code}
?- trace(append).
%     lists:append/2: [all]
%     lists:append/3: [all]
%     append/1: [all]
true.

?- append([a,b], [c], L).
 T [10] Call: lists:append([a, b], [c], _18032)
 T [19] Call: lists:append([b], [c], _19410)
 T [28] Call: lists:append([], [c], _20400)
 T [28 +0.1ms] Exit: lists:append([], [c], [c])
 T [19 +0.2ms] Exit: lists:append([b], [c], [b, c])
 T [10 +0.5ms] Exit: lists:append([a, b], [c], [a, b, c])
L = [a, b, c].

?- trace(append, -all).
%     lists:append/2: Not tracing
%     lists:append/3: Not tracing
%     append/1: Not tracing
\end{code}

The text between \Snil{} indicates the call depth (first number) and for
all ports except the \const{call} port the \textit{wall} time since the start
(call port) in milliseconds. Note that the instrumentation and print
time is included in the time. In the example above the actual time
is about 0.00001ms on todays hardware.

    \predicate{tracing}{2}{:Spec, -Ports}
True if \arg{Spec} is traced using \arg{Ports}

    \predicate{list_tracing}{0}{}
List predicates we are currently tracing

    \predicate[det]{notraceall}{0}{}
Remove all trace points
\end{description}