Skip to content
Newer
Older
100644 129 lines (89 sloc) 3.87 KB
69b84b2 @bos Improve docs
authored Apr 9, 2012
1 statprof - statistical profiling for Python
2 ===========================================
3
4 This package provides a simple statistical profiler for Python.
5
ae06aa0 @cyberdelia use restructured for README and description
cyberdelia authored Jun 5, 2012
6 Python's default profiler has been ``lsprof`` for several years. This is
69b84b2 @bos Improve docs
authored Apr 9, 2012
7 an *instrumenting* profiler, which means that it saves data on every
8 action of interest. In the case of lsprof, it runs at function entry
9 and exit. This has problems: it can be expensive due to frequent
10 sampling, and it is blind to hot spots *within* a function.
11
ae06aa0 @cyberdelia use restructured for README and description
cyberdelia authored Jun 5, 2012
12 In contrast, ``statprof`` samples the call stack periodically (by
69b84b2 @bos Improve docs
authored Apr 9, 2012
13 default, 1000 times per second), and it correctly tracks line numbers
14 *inside* a function. This means that if you have a 50-line function
cd7f8d5 @elpres reST syntax clean-up
elpres authored Oct 15, 2015
15 that contains two hot loops, ``statprof`` is likely to report them both
69b84b2 @bos Improve docs
authored Apr 9, 2012
16 accurately.
17
ae06aa0 @cyberdelia use restructured for README and description
cyberdelia authored Jun 5, 2012
18 .. note::
19 This package does not yet work on Windows! See the
20 implementation and portability notes below for details.
69b84b2 @bos Improve docs
authored Apr 9, 2012
21
22
157efab @elpres add info about repeated invocation and interactive use
elpres authored Oct 15, 2015
23 Usage
24 -----
69b84b2 @bos Improve docs
authored Apr 9, 2012
25
ae06aa0 @cyberdelia use restructured for README and description
cyberdelia authored Jun 5, 2012
26 It's easy to get started with ``statprof``: ::
69b84b2 @bos Improve docs
authored Apr 9, 2012
27
28 import statprof
29
30 statprof.start()
17e2229 @elpres fix whitespace in code example
elpres authored Oct 14, 2015
31 try:
32 my_questionable_function()
69b84b2 @bos Improve docs
authored Apr 9, 2012
33 finally:
17e2229 @elpres fix whitespace in code example
elpres authored Oct 14, 2015
34 statprof.stop()
35 statprof.display()
69b84b2 @bos Improve docs
authored Apr 9, 2012
36
7972fe8 @cyberdelia add profile contextmanager
cyberdelia authored Jun 10, 2012
37 Or with a contextmanager : ::
38
39 import statprof
17e2229 @elpres fix whitespace in code example
elpres authored Oct 14, 2015
40
7972fe8 @cyberdelia add profile contextmanager
cyberdelia authored Jun 10, 2012
41 with statprof.profile():
42 my_questionable_function()
43
157efab @elpres add info about repeated invocation and interactive use
elpres authored Oct 15, 2015
44 The profiler can be invoked at more than one place inside your code and will
45 report its findings for all of them at once at the end: ::
46
47 import statprof
48
49 statprof.start()
50 try:
51 my_questionable_function()
52 finally:
53 statprof.stop()
54
55 uninteresting_code()
56
57 statprof.start()
58 try:
59 my_other_questionable_function()
60 finally:
61 statprof.stop()
62
63 statprof.display()
64
65 However, when you are profiling your code by repeatedly executing it in
66 IPython, each run will add new samples to the previously collected ones, and
67 display results aggregated over all runs. Since you will likely just want to
68 see the results for the last run, remember to reset the profiler first: ::
69
70 import statprof
71
72 statprof.reset()
73 with statprof.profile():
74 my_questionable_function()
75
ae06aa0 @cyberdelia use restructured for README and description
cyberdelia authored Jun 5, 2012
76 For more comprehensive help, run ``pydoc statprof``.
69b84b2 @bos Improve docs
authored Apr 9, 2012
77
78
79 Portability
80 -----------
81
cd7f8d5 @elpres reST syntax clean-up
elpres authored Oct 15, 2015
82 Because ``statprof`` uses the Unix ``itimer`` signal facility, it does not
69b84b2 @bos Improve docs
authored Apr 9, 2012
83 currently work on Windows. (Patches to improve portability would be
84 most welcome.)
85
86
87 Implementation notes
88 --------------------
89
ae06aa0 @cyberdelia use restructured for README and description
cyberdelia authored Jun 5, 2012
90 The ``statprof`` profiler works by setting the Unix profiling signal
91 ``ITIMER_PROF`` to go off after the interval you define in the call to
92 ``reset()``. When the signal fires, a sampling routine is run which
69b84b2 @bos Improve docs
authored Apr 9, 2012
93 looks at the current procedure that's executing, and then crawls up
94 the stack, and for each frame encountered, increments that frame's
95 code object's sample count. Note that if a procedure is encountered
96 multiple times on a given stack, it is only counted once. After the
97 sampling is complete, the profiler resets profiling timer to fire
98 again after the appropriate interval.
99
ae06aa0 @cyberdelia use restructured for README and description
cyberdelia authored Jun 5, 2012
100 Meanwhile, the profiler keeps track, via ``os.times()``, how much CPU
101 time (system and user -- which is also what ``ITIMER_PROF`` tracks), has
102 elapsed while code has been executing within a ``start()``/``stop()``
69b84b2 @bos Improve docs
authored Apr 9, 2012
103 block.
104
105 The profiler also tries (as much as possible) to avoid counting or
106 timing its own code.
107
108
109 History
110 -------
111
112 This package was originally
ae06aa0 @cyberdelia use restructured for README and description
cyberdelia authored Jun 5, 2012
113 written and released by `Andy Wingo <http://wingolog.org/archives/2005/10/28/profiling>`_.
69b84b2 @bos Improve docs
authored Apr 9, 2012
114 It was ported to modern Python by Alex Frazer, and posted to github by
ae06aa0 @cyberdelia use restructured for README and description
cyberdelia authored Jun 5, 2012
115 Jeff Muizelaar. The current maintainer is `Bryan O'Sullivan <bos@serpentine.com>`_.
69b84b2 @bos Improve docs
authored Apr 9, 2012
116
117
118 Reporting bugs, contributing patches
119 ------------------------------------
120
ae06aa0 @cyberdelia use restructured for README and description
cyberdelia authored Jun 5, 2012
121 The current maintainer of this package is `Bryan O'Sullivan <bos@serpentine.com>`_.
69b84b2 @bos Improve docs
authored Apr 9, 2012
122
ae06aa0 @cyberdelia use restructured for README and description
cyberdelia authored Jun 5, 2012
123 Please report bugs using the `github issue tracker <https://github.com/bos/statprof.py/issues>`_.
69b84b2 @bos Improve docs
authored Apr 9, 2012
124
125 If you'd like to contribute patches, please do - the source is on
ae06aa0 @cyberdelia use restructured for README and description
cyberdelia authored Jun 5, 2012
126 github, so please just issue a pull request. ::
69b84b2 @bos Improve docs
authored Apr 9, 2012
127
128 $ git clone git://github.com/bos/statprof.py
Something went wrong with that request. Please try again.