Generating a Minidump

Last time, I demonstrated a way to automatically generate a stack crawl to help you debug errors in your application. However, I also mentioned that stack crawls are usually not enough information by themselves. In this post, I am going to cover how to create a file with more complete debugging information. Not only will it contain stack crawls, but it will contain local and global variable information, thread and process information, and even application memory. All of this information will be collected into a single minidump file, which you can submit automatically.

The API that we want to design should be able to write out a minidump on demand, without requiring the application to crash, or altering the application in any noticeable fashion. It should capture the state of the application as though a snapshot were taken — as if you broke into it with a debugger.

The magic for generating one of these minidump files is in the MiniDumpWriteDump API from the DbgHelp library. This single call will write out various pieces of application state to a file; but it requires a bit of help to ensure you’re only writing out information you actually need.

At its core, the MiniDumpWriteDump API requires a few pieces of information: what process to write debugging information for, what file to write the data to, what exception information to associate with the debugging scenario, and what filters to apply to the data. None of these pieces of information are difficult to obtain, but it requires an understanding of the problem domain to perform properly.

The first thing to understand about the API is the DumpType parameter — this is a logical OR’ing of MINIDUMP_TYPE enumeration values. The general rule of thumb is: the more stuff you OR in, the larger the dump file will be. However, this isn’t strictly true because 1) some of the flags you can OR in will filter data out out the resulting dump file (making it smaller), and 2) you can optionally specify a callback to further filter the results. MSDN does a pretty good job of describing what information is included or excluded for each of the flags.

One of the more confusing things about this call is the ExceptionParam parameter. MSDN claims that you can set this parameter to NULL to exclude exception information from the resulting dump file, but then goes on to tell you if you do so, the call stack may be wrong. It also tells you that you can use a worker thread to perform the work. So what’s really going on here? To understand this better, you need to understand that minidumps are usually something that come out of application crashes. And application crashes are usually a result of hitting the SEH unhandled exception filter at the base of a thread’s call stack. Because of this, the MiniDumpWriteDump API has a handy way for you to include exception information a la the ExceptionPointers field of the MINIDUMP_EXCEPTION_INFORMATION structure. You can assign the results of GetExceptionInfo into that field, and that exception information can be retained in the minidump.

However, due to the fact that our API can be called at any point in time, we cannot rely on crashes or exceptions being the cause of the minidump. So while it would be possible to use SEH to create the context we require to get a valid stack crawl, that would also mean we have to generate an exception and include that information in the minidump. Instead, we will make use of a worker thread to perform the operation. But this comes with its own considerations and questions. The first thing to remember is that we need to wait for the minidump to complete before allowing our API to continue. Failing to do this would mean that we’re dumping some random callstack and not what the user expected. But beyond that, it raises an interesting question: what should be done with other threads in the application? Do we want to allow them to continue working while the minidump is being written? Or do we want to stop them from running until the dump has completed? Unfortunately, the answer isn’t concrete. If we stop all of the threads by suspending them, then we’re altering the state of the application which is a pretty big debugging no-no. What’s more, by stopping them, we lose information in our minidump about whether the threads were suspended or not, since all of the threads will show up as suspended. However, it can still be beneficial to suspend the threads because it’s possible the caller has detected a threading issue and wants to debug it. So we’re going to have to push this problem off on our API and allow it to perform either way.

The next part of MiniDumpWriteDump of interest to us is the concept of user streams. At first blush, these appear to be ancillary streams of data that can be associated with the minidump. However, they’re not! MSDN does a terrible job of calling this fact out. The minidump itself is comprised of directories of information, and those directories contain these documented stream types. So if you attempt to implement your own stream from the list of MINIDUMP_STREAM_TYPE enumerations (for instance, the MiscInfoStream), then you will get a warning in WinDbg about ignoring a duplicate stream. In Visual Studio, the duplicate stream is silently ignored. The only streams which aren’t duplicated automatically seem to be the two comment stream types. What MSDN fails to call out is that the use of these user streams is for user-defined data, whose type is greater than LastReservedStream. You define your own stream types, and their format. No debugger understands this information automatically — so this option is really only interesting if you wish to write your own debugger extension.

So for this API, the user streams will be ignored and we can simply pass NULL.

The final part of the call which requires discussion is the callback filter. This is a function that the minidump writer will call, allowing you to filter the contents of the dump file. The callback is passed an input parameter that denotes the type of information to be filtered, and you can modify the output parameter to exclude specific pieces of information from the dump file. This is an important mechanism to us for two reasons: 1) we want to allow the caller to control the size of the dump files, and 2) we need to be able to filter out our helper thread so the user doesn’t see it. The first point is important because there are times when the caller may only need 10k of information to solve a particular bug, but may need 100MB of information to solve another. The second point is important simply so we don’t expose the implementation details of our API to the caller.

After all of that lead up, we’re finally ready to start looking at some code. The public parts of our API, with the boring bits elided, will look something like this:

class MiniDump {
public:
	typedef enum InfoLevel {
		kInfoLevelSmall,
		kInfoLevelMedium,
		kInfoLevelLarge
	} InfoLevel;

	bool Create( const wchar_t *inPath, 
				InfoLevel inLevel = kInfoLevelMedium, 
				bool inSuspendOtherThreads = false ) const;
};

This suits our need nicely — it allows the user to control where the dump file is written, how much information to output, and whether to suspend background threads or not.

The implementation of the Create function itself isn’t too interesting — it spawns a worker thread to do most of the work, and optionally suspends background threads.

bool MiniDump::Create( const wchar_t *inPath, InfoLevel inLevel, bool inSuspendOtherThreads ) const {
	if (!inPath)	return false;

	// Set up the list of parameters we want to pass to the newly-created thread.  Note
	// that we create the thread in a suspended state!
	struct MiniDumpParams param = { inPath, inLevel, this };
	DWORD threadId = 0;
	HANDLE hThread = ::CreateThread( NULL, 0, MinidumpWriter, &param, CREATE_SUSPENDED, &threadId );

	if (hThread) {
		// Having created the thread successfully, we need to put all of the other 
		// threads in the process into a suspended state, making sure not to suspend
		// our newly-created thread.  We do this because we want this function to
		// behave as a snapshot, and that means other threads should not continue
		// to perform work while we're creating the minidump.
		if (inSuspendOtherThreads) {
			EnumerateThreads( ::SuspendThread, threadId );
		}

		// Now we can resume our worker thread
		::ResumeThread( hThread );

		// Wait for the thread to finish working, without allowing the current
		// thread to continue working.  This ensures that the current thread won't
		// do anything interesting while we're writing the debug information out.  
		// This also means that the minidump will show this as the current callstack.
		::WaitForSingleObject( hThread, INFINITE );

		// The thread exit code tells us whether we were able to create the minidump
		DWORD code = 0;
		::GetExitCodeThread( hThread, &code );
		::CloseHandle( hThread );

		// If we suspended other threads, now is the time to wake them up
		if (inSuspendOtherThreads) {
			EnumerateThreads( ::ResumeThread, threadId );
		}

		return code != 0;
	}
	return false;
}

The MinidumpWriter thread entrypoint is where most of the interesting work happens. Ignoring the uninteresting bits, it looks like:

int type = MiniDumpNormal;
switch (p->level) {
	case kInfoLevelSmall: {
		type |= MiniDumpWithIndirectlyReferencedMemory |
				MiniDumpScanMemory;
	} break;
	case kInfoLevelMedium: {
		type |= MiniDumpWithDataSegs |
				MiniDumpWithPrivateReadWriteMemory |
				MiniDumpWithHandleData |
				MiniDumpWithFullMemoryInfo | 
				MiniDumpWithThreadInfo |
				MiniDumpWithUnloadedModules;
	} break;
	case kInfoLevelLarge: {
		type |= MiniDumpWithDataSegs |
				MiniDumpWithPrivateReadWriteMemory |
				MiniDumpWithHandleData |
				MiniDumpWithFullMemory |
				MiniDumpWithFullMemoryInfo | 
				MiniDumpWithThreadInfo |
				MiniDumpWithUnloadedModules |
				MiniDumpWithProcessThreadData;
	} break;
}

// Set up the callback to be called by the minidump writer.  This allows us to
// filter out information that we may not care about.
MINIDUMP_CALLBACK_INFORMATION callback = { 0 };
struct MinidumpCallbackParam info = { p->level, p->dump, ::GetCurrentThreadId() };
callback.CallbackParam = &info;
callback.CallbackRoutine = MinidumpFilter;

// After all that, we can write out the minidump
BOOL bRet = ::MiniDumpWriteDump( ::GetCurrentProcess(), ::GetCurrentProcessId(), hFile,
		(MINIDUMP_TYPE)type, NULL, NULL, &callback );

Most of the method is comprised of code to determine what flags to set for the DumpType parameter. As you can see, each dump type sets up its own set of flags for what information to dump. What you can’t see is how that information is filtered by the callback. Which brings us to the last interesting piece of the puzzle: the filter itself.

switch (inInput->CallbackType) {
	case IncludeModuleCallback:	
	case ThreadCallback:
	case ThreadExCallback:		return TRUE;
	case CancelCallback:		return FALSE;

	case IncludeThreadCallback: {
		// We don't want to include information about the minidump writing 
		// thread, as that's not of interest to the caller
		if (inInput->IncludeThread.ThreadId == param->thread)	return FALSE;
		return TRUE;
	} break;

	case MemoryCallback: {
		// Small and medium sized dumps don't need full memory access
		if (kInfoLevelSmall == infoLevel ||
			kInfoLevelMedium == infoLevel)	return FALSE;
		return TRUE;
	} break;

	case ModuleCallback: {
		if (kInfoLevelSmall == infoLevel) {
			// When creating a small dump file, we filter out any modules that
			// aren't being directly referenced.
			if (!(outOutput->ModuleWriteFlags & ModuleReferencedByMemory)) {
				outOutput->ModuleWriteFlags &= ~ModuleWriteModule;
			}
		} else if (kInfoLevelMedium == infoLevel) {
			// When creating a medium-sized dump file, we filter out any module
			// data segments if they're not part of our core module list.  This
			// helps reduce the size of the dump file by quite a bit.
			if (outOutput->ModuleWriteFlags & ModuleWriteDataSeg) {
				if (!param->dump->IsDataSegmentNeeded( inInput->Module.FullPath )) {
					outOutput->ModuleWriteFlags &= ~ModuleWriteDataSeg;
				}
			}
		}

		return TRUE;
	} break;
}

You’ll notice that when we determine whether a thread should be included in the dump or not, we look for our worker thread and return FALSE if we find it. This ensures that the worker thread is not written out to the dump file. Also, only large dump files get full memory access. Finally, when determining what module information to include, we ensure that only directly referenced modules are included for small memory dumps, and only modules we care about are included for medium memory dumps. The IsDataSegmentNeeded helper method will return true only for kernel modules and the process itself.

The beauty of this API is in the simplicity for the caller — they merely specify where the information should be written out to, and how much information to provide. Once the file has been written out, it is trivial to write a helper method to automatically generate a bug report and submit the data. Now the only question becomes: when would you use this API?

Personally, I use this approach for reporting on failed assertions. When you’ve got an assertion failing in your code, it means that one of your assumptions which couldn’t possibly be false… is false. This would be a great opportunity for you to write out the application state so you can determine why your assertion isn’t holding up.

One thing about this API that bothers me is the fact that we can lose thread state information. If the user says to suspend all background threads, then our dump file will show all background threads as being suspended. However, it’s possible that the user is trying to debug a threading issue where a background thread has stomped on a particular piece of memory. Unfortunately, there’s no way to handle this automatically, short of rewriting MiniDumpWriteDump ourselves.

tl;dr: I’ve posted the complete code examples on my svn repository, which you can access here.