138 lines
4.4 KiB
TeX
138 lines
4.4 KiB
TeX
\section{\module{hotshot} ---
|
|
High performance logging profiler}
|
|
|
|
\declaremodule{standard}{hotshot}
|
|
\modulesynopsis{High performance logging profiler, mostly written in C.}
|
|
\moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
|
|
\sectionauthor{Anthony Baxter}{anthony@interlink.com.au}
|
|
|
|
\versionadded{2.2}
|
|
|
|
|
|
This module provides a nicer interface to the \module{_hotshot} C module.
|
|
Hotshot is a replacement for the existing \refmodule{profile} module. As it's
|
|
written mostly in C, it should result in a much smaller performance impact
|
|
than the existing \refmodule{profile} module.
|
|
|
|
\begin{notice}[note]
|
|
The \module{hotshot} module focuses on minimizing the overhead
|
|
while profiling, at the expense of long data post-processing times.
|
|
For common usages it is recommended to use \module{cProfile} instead.
|
|
\module{hotshot} is not maintained and might be removed from the
|
|
standard library in the future.
|
|
\end{notice}
|
|
|
|
\versionchanged[the results should be more meaningful than in the
|
|
past: the timing core contained a critical bug]{2.5}
|
|
|
|
\begin{notice}[warning]
|
|
The \module{hotshot} profiler does not yet work well with threads.
|
|
It is useful to use an unthreaded script to run the profiler over
|
|
the code you're interested in measuring if at all possible.
|
|
\end{notice}
|
|
|
|
|
|
\begin{classdesc}{Profile}{logfile\optional{, lineevents\optional{,
|
|
linetimings}}}
|
|
The profiler object. The argument \var{logfile} is the name of a log
|
|
file to use for logged profile data. The argument \var{lineevents}
|
|
specifies whether to generate events for every source line, or just on
|
|
function call/return. It defaults to \code{0} (only log function
|
|
call/return). The argument \var{linetimings} specifies whether to
|
|
record timing information. It defaults to \code{1} (store timing
|
|
information).
|
|
\end{classdesc}
|
|
|
|
|
|
\subsection{Profile Objects \label{hotshot-objects}}
|
|
|
|
Profile objects have the following methods:
|
|
|
|
\begin{methoddesc}{addinfo}{key, value}
|
|
Add an arbitrary labelled value to the profile output.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{close}{}
|
|
Close the logfile and terminate the profiler.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{fileno}{}
|
|
Return the file descriptor of the profiler's log file.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{run}{cmd}
|
|
Profile an \keyword{exec}-compatible string in the script environment.
|
|
The globals from the \refmodule[main]{__main__} module are used as
|
|
both the globals and locals for the script.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{runcall}{func, *args, **keywords}
|
|
Profile a single call of a callable.
|
|
Additional positional and keyword arguments may be passed
|
|
along; the result of the call is returned, and exceptions are
|
|
allowed to propagate cleanly, while ensuring that profiling is
|
|
disabled on the way out.
|
|
\end{methoddesc}
|
|
|
|
|
|
\begin{methoddesc}{runctx}{cmd, globals, locals}
|
|
Evaluate an \keyword{exec}-compatible string in a specific environment.
|
|
The string is compiled before profiling begins.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{start}{}
|
|
Start the profiler.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{stop}{}
|
|
Stop the profiler.
|
|
\end{methoddesc}
|
|
|
|
|
|
\subsection{Using hotshot data}
|
|
|
|
\declaremodule{standard}{hotshot.stats}
|
|
\modulesynopsis{Statistical analysis for Hotshot}
|
|
|
|
\versionadded{2.2}
|
|
|
|
This module loads hotshot profiling data into the standard \module{pstats}
|
|
Stats objects.
|
|
|
|
\begin{funcdesc}{load}{filename}
|
|
Load hotshot data from \var{filename}. Returns an instance
|
|
of the \class{pstats.Stats} class.
|
|
\end{funcdesc}
|
|
|
|
\begin{seealso}
|
|
\seemodule{profile}{The \module{profile} module's \class{Stats} class}
|
|
\end{seealso}
|
|
|
|
|
|
\subsection{Example Usage \label{hotshot-example}}
|
|
|
|
Note that this example runs the python ``benchmark'' pystones. It can
|
|
take some time to run, and will produce large output files.
|
|
|
|
\begin{verbatim}
|
|
>>> import hotshot, hotshot.stats, test.pystone
|
|
>>> prof = hotshot.Profile("stones.prof")
|
|
>>> benchtime, stones = prof.runcall(test.pystone.pystones)
|
|
>>> prof.close()
|
|
>>> stats = hotshot.stats.load("stones.prof")
|
|
>>> stats.strip_dirs()
|
|
>>> stats.sort_stats('time', 'calls')
|
|
>>> stats.print_stats(20)
|
|
850004 function calls in 10.090 CPU seconds
|
|
|
|
Ordered by: internal time, call count
|
|
|
|
ncalls tottime percall cumtime percall filename:lineno(function)
|
|
1 3.295 3.295 10.090 10.090 pystone.py:79(Proc0)
|
|
150000 1.315 0.000 1.315 0.000 pystone.py:203(Proc7)
|
|
50000 1.313 0.000 1.463 0.000 pystone.py:229(Func2)
|
|
.
|
|
.
|
|
.
|
|
\end{verbatim}
|