Anthony Baxter | b3303ef | 2003-04-07 12:19:15 +0000 | [diff] [blame] | 1 | \section{\module{hotshot} --- |
| 2 | High performance logging profiler} |
| 3 | |
| 4 | \declaremodule{standard}{hotshot} |
Fred Drake | fcd845a | 2003-04-09 04:06:37 +0000 | [diff] [blame] | 5 | \modulesynopsis{High performance logging profiler, mostly written in C.} |
Anthony Baxter | b3303ef | 2003-04-07 12:19:15 +0000 | [diff] [blame] | 6 | \moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org} |
| 7 | \sectionauthor{Anthony Baxter}{anthony@interlink.com.au} |
| 8 | |
Anthony Baxter | b3303ef | 2003-04-07 12:19:15 +0000 | [diff] [blame] | 9 | \versionadded{2.2} |
| 10 | |
Anthony Baxter | b3303ef | 2003-04-07 12:19:15 +0000 | [diff] [blame] | 11 | |
Fred Drake | fcd845a | 2003-04-09 04:06:37 +0000 | [diff] [blame] | 12 | This module provides a nicer interface to the \module{_hotshot} C module. |
Anthony Baxter | b3303ef | 2003-04-07 12:19:15 +0000 | [diff] [blame] | 13 | Hotshot is a replacement for the existing \refmodule{profile} module. As it's |
Fred Drake | fcd845a | 2003-04-09 04:06:37 +0000 | [diff] [blame] | 14 | written mostly in C, it should result in a much smaller performance impact |
| 15 | than the existing \refmodule{profile} module. |
Anthony Baxter | b3303ef | 2003-04-07 12:19:15 +0000 | [diff] [blame] | 16 | |
Fred Drake | 621b443 | 2004-01-16 17:30:16 +0000 | [diff] [blame] | 17 | \begin{notice}[warning] |
| 18 | The \module{hotshot} profiler does not yet work well with threads. |
| 19 | It is useful to use an unthreaded script to run the profiler over |
| 20 | the code you're interested in measuring if at all possible. |
| 21 | \end{notice} |
| 22 | |
| 23 | |
| 24 | \begin{classdesc}{Profile}{logfile\optional{, lineevents\optional{, |
| 25 | linetimings}}} |
Fred Drake | fcd845a | 2003-04-09 04:06:37 +0000 | [diff] [blame] | 26 | The profiler object. The argument \var{logfile} is the name of a log |
| 27 | file to use for logged profile data. The argument \var{lineevents} |
| 28 | specifies whether to generate events for every source line, or just on |
| 29 | function call/return. It defaults to \code{0} (only log function |
| 30 | call/return). The argument \var{linetimings} specifies whether to |
| 31 | record timing information. It defaults to \code{1} (store timing |
Anthony Baxter | b3303ef | 2003-04-07 12:19:15 +0000 | [diff] [blame] | 32 | information). |
Anthony Baxter | b3303ef | 2003-04-07 12:19:15 +0000 | [diff] [blame] | 33 | \end{classdesc} |
| 34 | |
Fred Drake | fcd845a | 2003-04-09 04:06:37 +0000 | [diff] [blame] | 35 | |
Anthony Baxter | b3303ef | 2003-04-07 12:19:15 +0000 | [diff] [blame] | 36 | \subsection{Profile Objects \label{hotshot-objects}} |
| 37 | |
| 38 | Profile objects have the following methods: |
| 39 | |
| 40 | \begin{methoddesc}{addinfo}{key, value} |
| 41 | Add an arbitrary labelled value to the profile output. |
| 42 | \end{methoddesc} |
| 43 | |
| 44 | \begin{methoddesc}{close}{} |
| 45 | Close the logfile and terminate the profiler. |
| 46 | \end{methoddesc} |
Fred Drake | fcd845a | 2003-04-09 04:06:37 +0000 | [diff] [blame] | 47 | |
Anthony Baxter | b3303ef | 2003-04-07 12:19:15 +0000 | [diff] [blame] | 48 | \begin{methoddesc}{fileno}{} |
| 49 | Return the file descriptor of the profiler's log file. |
| 50 | \end{methoddesc} |
| 51 | |
| 52 | \begin{methoddesc}{run}{cmd} |
Fred Drake | fcd845a | 2003-04-09 04:06:37 +0000 | [diff] [blame] | 53 | Profile an \keyword{exec}-compatible string in the script environment. |
| 54 | The globals from the \refmodule[main]{__main__} module are used as |
Anthony Baxter | b3303ef | 2003-04-07 12:19:15 +0000 | [diff] [blame] | 55 | both the globals and locals for the script. |
| 56 | \end{methoddesc} |
| 57 | |
| 58 | \begin{methoddesc}{runcall}{func, *args, **keywords} |
| 59 | Profile a single call of a callable. |
Anthony Baxter | b3303ef | 2003-04-07 12:19:15 +0000 | [diff] [blame] | 60 | Additional positional and keyword arguments may be passed |
| 61 | along; the result of the call is returned, and exceptions are |
Raymond Hettinger | 6880431 | 2005-01-01 00:28:46 +0000 | [diff] [blame^] | 62 | allowed to propagate cleanly, while ensuring that profiling is |
Anthony Baxter | b3303ef | 2003-04-07 12:19:15 +0000 | [diff] [blame] | 63 | disabled on the way out. |
| 64 | \end{methoddesc} |
| 65 | |
| 66 | |
| 67 | \begin{methoddesc}{runctx}{cmd, globals, locals} |
Fred Drake | fcd845a | 2003-04-09 04:06:37 +0000 | [diff] [blame] | 68 | Evaluate an \keyword{exec}-compatible string in a specific environment. |
Anthony Baxter | b3303ef | 2003-04-07 12:19:15 +0000 | [diff] [blame] | 69 | The string is compiled before profiling begins. |
| 70 | \end{methoddesc} |
| 71 | |
| 72 | \begin{methoddesc}{start}{} |
| 73 | Start the profiler. |
| 74 | \end{methoddesc} |
| 75 | |
| 76 | \begin{methoddesc}{stop}{} |
| 77 | Stop the profiler. |
| 78 | \end{methoddesc} |
| 79 | |
Anthony Baxter | b3303ef | 2003-04-07 12:19:15 +0000 | [diff] [blame] | 80 | |
Fred Drake | fcd845a | 2003-04-09 04:06:37 +0000 | [diff] [blame] | 81 | \subsection{Using hotshot data} |
| 82 | |
| 83 | \declaremodule{standard}{hotshot.stats} |
Anthony Baxter | b3303ef | 2003-04-07 12:19:15 +0000 | [diff] [blame] | 84 | \modulesynopsis{Statistical analysis for Hotshot} |
| 85 | |
| 86 | \versionadded{2.2} |
| 87 | |
Fred Drake | fcd845a | 2003-04-09 04:06:37 +0000 | [diff] [blame] | 88 | This module loads hotshot profiling data into the standard \module{pstats} |
Anthony Baxter | b3303ef | 2003-04-07 12:19:15 +0000 | [diff] [blame] | 89 | Stats objects. |
| 90 | |
| 91 | \begin{funcdesc}{load}{filename} |
Fred Drake | fcd845a | 2003-04-09 04:06:37 +0000 | [diff] [blame] | 92 | Load hotshot data from \var{filename}. Returns an instance |
Anthony Baxter | b3303ef | 2003-04-07 12:19:15 +0000 | [diff] [blame] | 93 | of the \class{pstats.Stats} class. |
| 94 | \end{funcdesc} |
| 95 | |
| 96 | \begin{seealso} |
Fred Drake | fcd845a | 2003-04-09 04:06:37 +0000 | [diff] [blame] | 97 | \seemodule{profile}{The \module{profile} module's \class{Stats} class} |
Anthony Baxter | b3303ef | 2003-04-07 12:19:15 +0000 | [diff] [blame] | 98 | \end{seealso} |
| 99 | |
Fred Drake | fcd845a | 2003-04-09 04:06:37 +0000 | [diff] [blame] | 100 | |
Anthony Baxter | b3303ef | 2003-04-07 12:19:15 +0000 | [diff] [blame] | 101 | \subsection{Example Usage \label{hotshot-example}} |
| 102 | |
Fred Drake | fcd845a | 2003-04-09 04:06:37 +0000 | [diff] [blame] | 103 | Note that this example runs the python ``benchmark'' pystones. It can |
Anthony Baxter | cb8ed53 | 2003-04-07 12:21:56 +0000 | [diff] [blame] | 104 | take some time to run, and will produce large output files. |
| 105 | |
Anthony Baxter | b3303ef | 2003-04-07 12:19:15 +0000 | [diff] [blame] | 106 | \begin{verbatim} |
Anthony Baxter | b3303ef | 2003-04-07 12:19:15 +0000 | [diff] [blame] | 107 | >>> import hotshot, hotshot.stats, test.pystone |
| 108 | >>> prof = hotshot.Profile("stones.prof") |
| 109 | >>> benchtime, stones = prof.runcall(test.pystone.pystones) |
| 110 | >>> prof.close() |
| 111 | >>> stats = hotshot.stats.load("stones.prof") |
| 112 | >>> stats.strip_dirs() |
| 113 | >>> stats.sort_stats('time', 'calls') |
| 114 | >>> stats.print_stats(20) |
| 115 | 850004 function calls in 10.090 CPU seconds |
| 116 | |
| 117 | Ordered by: internal time, call count |
| 118 | |
| 119 | ncalls tottime percall cumtime percall filename:lineno(function) |
| 120 | 1 3.295 3.295 10.090 10.090 pystone.py:79(Proc0) |
| 121 | 150000 1.315 0.000 1.315 0.000 pystone.py:203(Proc7) |
| 122 | 50000 1.313 0.000 1.463 0.000 pystone.py:229(Func2) |
| 123 | . |
| 124 | . |
| 125 | . |
Anthony Baxter | b3303ef | 2003-04-07 12:19:15 +0000 | [diff] [blame] | 126 | \end{verbatim} |