RunSnakeRun is a small GUI utility that allows
you to view (Python) cProfile or Profile profiler dumps in a sortable
GUI view. It allows you to explore the profiler information using
a "square map" visualization or sortable tables of data. It also (experimentally)
allows you to view the output of the Meliae "memory analysis" tool
using the same basic visualisations.
RunSnakeRun is a simple program, it doesn't provide all the bells-and-whistles of a program like KCacheGrind, it's intended to allow for profiling your Python programs, and just your Python programs. What it does provide, for profile viewing:
For Meliae memory-dump viewing, it provides:
You will need to have all of wxPython, SquareMap and RunSnakeRun installed to use RunSnakeRun. You may also need the "python-profiler" package for your platform, which provides the pstats view. You will likely want to use your platform wxPython package (i.e. a pre-built binary). For Debian/Ubuntu distributions the prerequisite setup looks like this:
apt-get install python-profiler python-wxgtk2.8 python-setuptools
RunSnakeRun and SquareMap will install well in a VirtualEnv if you
would like to keep them isolated (normally you do not want to use the
--no-site-packages flag if you are doing this). I recommend this approach rather than using easy_install directly on your Linux/OS-X host.
If you already have Python setuptools installed (a.k.a. easy_install), you should be able to install the Python packages with:
easy_install SquareMap RunSnakeRun
You will require a modern wxPython (e.g. 2.8) and
Python 2.x (e.g. 2.5 through 2.7) installation. The setup will create a script named
"runsnake" on Linux machines which launches the profile viewer.
On OS-X machines a wrapper script runsnake is created that runs the
runsnake32 executable with a flag to tell Python to use the 32-bit
implementation (for wxPython compatibility). On Win32 machines, a
Scripts\runsnake.exe executable is created. If you have added
your scripts directory to the PATH then this will be available from the
If you are new to profiling you may wish to check out:
To use cProfile to capture your application's profile data, either using the command-line, like so:
$ python -m cProfile -o <outputfilename> <script-name> <options>
Or in code, like so:
command = """reactor.run()"""
cProfile.runctx( command, globals(), locals(), filename="OpenGLContext.profile" )
To view the results of your run:
python runsnake.py OpenGLContext.profile
There will be a brief delay as the application is created and begins the loading process, then you should see something like this:
Click on any column title to sort by that property within that list. Select a record in the left-most list view to see a breakdown of that record in the right-side list views. Choose the appropriate view on the right via the tabs. You can resize the borders between the lists and square-map views. You can select a package/module/function hierarchic view via the menus. You can also toggle use of percentage displays there.
Note: this feature is considered
experimental, the memory consumed loading even a tiny meliae dump is
enormous, so real-world programs will make RunSnakeRun quite slow and
require a very large amount of RAM (far more than the process being
To install Meliae, you will need a working C extension compilation environment (Meliae uses a Cython extension):
Now instrument your application to be able to trigger a memory dump at the moment you would like to capture, like so:
from meliae import scanner
scanner.dump_all_objects( filename ) # you can pass a file-handle if you prefer
The memory dump will generally be quite large (e.g. 2MB to describe an application with 200KB of user-controllable memory usage (i.e. not the interpreter itself)) and for any real application will take an extremely long time to load (multiple minutes for 16MB dumps).
$ runsnakemem <filename>
The Meliae loader in RunSnakeRun performs the following simplifications:
Even with those simplifications, however, the program is tracking
most ints, strings, tuples, lists, etc. separately, which uses a large
amount of RAM and slows down the GUI substantially.
RunSnakeRun is reasonably stable. I don't tend to do much work on it, as it tends to just work. My (personal) current wish list for the project follows:
If you have an idea, feel free to check out the code and implement the new feature. I'm certainly willing to entertain new features or bug-fix requests as well. The code is available in bzr here:
bzr branch lp:~mcfletch/squaremap/trunk squaremap
python setup.py develop
bzr branch lp:~mcfletch/runsnakerun/trunk runsnakerun
python setup.py develop
You can contact me directly if you'd like to contribute. Or you can just set up a bzr branch on LaunchPad and request a merge.
This is just a listing of things that either I or others have requested as features:
RunSnakeRun is by no means a comprehensive tool-set for profiling, you may want to have any or all of these other tools available for your profiling needs: