RunSnakeRun

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.

Features

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:

• sortable data-grid views for raw profile information
• identity: function name, file-name, directory name
• time-spent: cummulative, cummulative-per, local and local-per time
• overall data-grid view
• (all) callers-of-this-function, (all) callees-of-this-function views
• squaremap view of call tree
• size proportional to amount of time spent by the given parent in the given function
• squaremap view of packages/modules/functions
• size proportional to time spent in each package/module/function
• basic navigation (home, back, up)

If you are new to profiling you may wish to check out the author's presentation at PyCon 2009 which tries to explain the use of profiling as a tool.

Installation

You will need to have all of wxPython, SquareMap and RunSnakeRun installed to use RunSnakeRun.  You may also need the "python-profile" package for your platform, which provides the pstats view.

You will likely want to use your platform wxPython package.  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
easy_install RunSnakeRun

You will require a modern wxPython and Python installation.  The setup will create a script named "runsnake" on Linux machines which launches the profile viewer.

Usage

To use cProfile to capture your application's profile data:

import cProfile
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.

Code Access and Contributions

RunSnakeRun is reasonably stable.  I don't tend to do much work on it, as it tends to just work.  My 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
bzr branch lp:~mcfletch/runsnakerun/trunk runsnakerun
cd 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.

Roadmap/Wish-list

This is just a listing of things that either I or others have requested as features:

• provide comparison views and "progress" views that compare across multiple profiles
• (re)support Hotshot profile dumps (removed because Hotshot itself was deprecated)
• support Robert Kern's line_profiler module (line and import timings)
• support IronPython profiles (with cleanup on load to remove "noise" functions)
• with a line-profiling module, allow per-line profile views
• source-code view
  
• rework squaremap to be more robust for large profiles
• support (C) calltree/cachegrind files (as used by kcachegrind)
• clean up the UI code (very hacky)
• storage of preferences such as column widths
• utility functions for capturing data

Other Tools

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:

• Gprof2Dot -- Converts various Profile formats into dot-format graphs
  
• Robert Kern's line_profiler -- Cython based Python profiler with line timings
• KCacheGrind -- KDE viewer for CacheGrind C-level profiler or converted Python profiles (via pyprof2calltree), KCacheGrind is basically what RunSnakeRun started off trying to imitate save that RunSnakeRun was intended to be Python specific and cross-platform
• profilehooks -- specify which function to profile by using a decorator on a particular function

Releases/Downloads

• 2.0.0b5 -- Add names of loaded files to the window title, use same colour for each node, make colours cycle across far wider range of colours, bug-fixes
• 2.0.0b4 -- Win32 bug-fixes, drawing of labels on squaremap where there's enough space
• 2.0.0b1 -- packaging fixes, UI fixes
• 2.0.0a1 -- Eliminate support for (obsolete) Hotshot profiles, add squaremap visualization and callee/caller views, lots of UI work to make the application more usable, preliminary i18n work (just gettext markup)
• 1.0.4 -- Add preliminary support for standard cProfile/profile profile results, note that we do not load cProfile results incrementally.  Switch to numpy support from Numeric.  Use setuptools for distribution.  Provide source repository access.
• 1.0.3 -- Fix stupid bug introduced by last fix
• 1.0.2 -- Magically grow the stack-tracking structures if we pass recursion limits, this will be slow, but it should allow for loading even extremely stack-exhausting programs
• 1.0.1 -- Bug-fix, increases stack-tracking size to 10x recursion limit, instead of == recursion limit, but as of yet, doesn't seem to fix the reported stack-exhaustion
• 1.0.0 -- Initial release, no fancy features, just the raw functionality

Copyright 2005-2009 Mike Fletcher