minidumper - Python crash dumps on Windows


Posted:   |  More posts about python software

If you're writing software on Windows, you've likely come across minidumps. They're a great help when your project encounters a crashing scenario, as they record varying levels of information to help you reproduce the problem.

The main product I work on at my day job, a server written in C++, has had minidump functionality since the beginning. We keep PDBs around for our releases, then when customers encounter a crash, we grab the minidump, match it up with the binaries and PDBs, then try to figure out what the scenario was. I think that's fairly standard operating procedure, and it tends to work alright. Release crash dumps are obviously less helpful than debug dumps, but you can still get enough out of them to get started in the right direction. So while one part of my job has that, the other part - the Python part - has had me wishing for it. So I wrote it.

The extension modules I maintain internally for our server's APIs occasionally come crashing down during our test automation. That's fairly alarming at first since the tests just drop out and you don't get much of an indication of why. Was it the extension? The underlying C++ API? Python itself? The unittest logs are all we have to go off of, so then it's a matter of piecing together what was happening at the time, then either manually re-running it from the REPL and/or attaching the Visual Studio debugger to catch the problem.

In comes minidumper. By importing minidumper and enabling it, you can receive crash dump files whenever your Python process goes down. It's there for you.

import minidumper

minidumper.enable(name="example")

Now if you do some crazy stuff and cause a crash in your extension code...

void
divide_by_zero()
{
    int x = 1;
    int b = x / 0;
}

...you'll get a crash dump that will tell you exactly what just happened. In my case, I got example_20110929-071529.mdmp. Now if you open that up in Visual Studio, ideally the one that Python was compiled with, you'll get a look into what happened once you hit F5 (or Debug > Start Debugging).

http://i.imgur.com/ZVSQN.png

The first thing you'll see is a popup telling you what the problem was and where it occurred, then Visual Studio will show you exactly where in the code the issue lies. As we all know, division by zero is a no-no, and it crashed. If you hit the break button, you can poke around in a ton of information that was gathered from your crashed process. Depending on what value you gave to the type parameter of minidumper.enable(type=...), which defaults to MiniDumpNormal and has a full list of options here, you'll have different amounts of information.

http://i.imgur.com/qYwqH.png

You can walk around the call stack and see what functions were called with what values, and from there you can inspect variables within a function by hovering over them with the cursor. The Debug > Windows menu contains a whole bunch of other pieces of information, including memory, disassembly, value watching, and more.

As far as examples and tests go, I only have some of the basics down, although I plan on bulking those areas up and coming up with more useful and interesting code to prove this extension's worth. I just threw the source up on https://bitbucket.org/briancurtin/minidumper, but I'm going to wait on getting it on PyPI until I figure out the best way to organize and distribute it.

If you're looking for more info on minidumps, http://www.debuginfo.com/articles/effminidumps.html and http://www.codeproject.com/KB/debug/postmortemdebug_standalone1.aspx were helpful sites, as well as the various MSDN documentation.


The following setup steps are what I do to get started, using the CPython default branch, aka, CPython 3.3. Also note that I'm using a debug-built Python, and telling the minidumper extension to do a debug build as it's what I usually use at work, as well as when I'm working on CPython.

  1. hg clone https://YOURNAMEHERE@bitbucket.org/briancurtin/minidumper minidumper-dev
  2. C:python-devcpython-mainPCbuildpython_d.exe setup.py build --debug install
  3. C:python-devcpython-mainPCbuildpython_d.exe -m tests

Running the tests will build a tester extension, which contains two crashing functions. Right now, the few tests just call the crash functions with different minidumper.enable settings in order to make sure the right dumps are being created in the right places.

Hope it helps.

Note: Until I fix http://bugs.python.org/issue11732, the crash windows asking you to debug or close the program will stay around until you click something. Ideally I'll be able to add functionality to temporarily disable Windows Error Reporting for the http://docs.python.org/dev/library/faulthandler.html module, as it currently requires manual intervention while running the CPython test suite on Windows, as :code:`minidumper` does.

Contents © 2013 Brian Curtin