/Doc/library/hotshot.rst

  1
  2:mod:`hotshot` --- High performance logging profiler
  3====================================================
  4
  5.. module:: hotshot
  6   :synopsis: High performance logging profiler, mostly written in C.
  7.. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
  8.. sectionauthor:: Anthony Baxter <anthony@interlink.com.au>
  9
 10
 11.. versionadded:: 2.2
 12
 13This module provides a nicer interface to the :mod:`_hotshot` C module. Hotshot
 14is a replacement for the existing :mod:`profile` module. As it's written mostly
 15in C, it should result in a much smaller performance impact than the existing
 16:mod:`profile` module.
 17
 18.. note::
 19
 20   The :mod:`hotshot` module focuses on minimizing the overhead while profiling, at
 21   the expense of long data post-processing times. For common usage it is
 22   recommended to use :mod:`cProfile` instead. :mod:`hotshot` is not maintained and
 23   might be removed from the standard library in the future.
 24
 25.. versionchanged:: 2.5
 26   The results should be more meaningful than in the past: the timing core
 27   contained a critical bug.
 28
 29.. note::
 30
 31   The :mod:`hotshot` profiler does not yet work well with threads. It is useful to
 32   use an unthreaded script to run the profiler over the code you're interested in
 33   measuring if at all possible.
 34
 35
 36.. class:: Profile(logfile[, lineevents[, linetimings]])
 37
 38   The profiler object. The argument *logfile* is the name of a log file to use for
 39   logged profile data. The argument *lineevents* specifies whether to generate
 40   events for every source line, or just on function call/return. It defaults to
 41   ``0`` (only log function call/return). The argument *linetimings* specifies
 42   whether to record timing information. It defaults to ``1`` (store timing
 43   information).
 44
 45
 46.. _hotshot-objects:
 47
 48Profile Objects
 49---------------
 50
 51Profile objects have the following methods:
 52
 53
 54.. method:: Profile.addinfo(key, value)
 55
 56   Add an arbitrary labelled value to the profile output.
 57
 58
 59.. method:: Profile.close()
 60
 61   Close the logfile and terminate the profiler.
 62
 63
 64.. method:: Profile.fileno()
 65
 66   Return the file descriptor of the profiler's log file.
 67
 68
 69.. method:: Profile.run(cmd)
 70
 71   Profile an :keyword:`exec`\ -compatible string in the script environment. The
 72   globals from the :mod:`__main__` module are used as both the globals and locals
 73   for the script.
 74
 75
 76.. method:: Profile.runcall(func, *args, **keywords)
 77
 78   Profile a single call of a callable. Additional positional and keyword arguments
 79   may be passed along; the result of the call is returned, and exceptions are
 80   allowed to propagate cleanly, while ensuring that profiling is disabled on the
 81   way out.
 82
 83
 84.. method:: Profile.runctx(cmd, globals, locals)
 85
 86   Evaluate an :keyword:`exec`\ -compatible string in a specific environment. The
 87   string is compiled before profiling begins.
 88
 89
 90.. method:: Profile.start()
 91
 92   Start the profiler.
 93
 94
 95.. method:: Profile.stop()
 96
 97   Stop the profiler.
 98
 99
100Using hotshot data
101------------------
102
103.. module:: hotshot.stats
104   :synopsis: Statistical analysis for Hotshot
105
106
107.. versionadded:: 2.2
108
109This module loads hotshot profiling data into the standard :mod:`pstats` Stats
110objects.
111
112
113.. function:: load(filename)
114
115   Load hotshot data from *filename*. Returns an instance of the
116   :class:`pstats.Stats` class.
117
118
119.. seealso::
120
121   Module :mod:`profile`
122      The :mod:`profile` module's :class:`Stats` class
123
124
125.. _hotshot-example:
126
127Example Usage
128-------------
129
130Note that this example runs the python "benchmark" pystones.  It can take some
131time to run, and will produce large output files. ::
132
133   >>> import hotshot, hotshot.stats, test.pystone
134   >>> prof = hotshot.Profile("stones.prof")
135   >>> benchtime, stones = prof.runcall(test.pystone.pystones)
136   >>> prof.close()
137   >>> stats = hotshot.stats.load("stones.prof")
138   >>> stats.strip_dirs()
139   >>> stats.sort_stats('time', 'calls')
140   >>> stats.print_stats(20)
141            850004 function calls in 10.090 CPU seconds
142
143      Ordered by: internal time, call count
144
145      ncalls  tottime  percall  cumtime  percall filename:lineno(function)
146           1    3.295    3.295   10.090   10.090 pystone.py:79(Proc0)
147      150000    1.315    0.000    1.315    0.000 pystone.py:203(Proc7)
148       50000    1.313    0.000    1.463    0.000 pystone.py:229(Func2)
149    .
150    .
151    .
152