How to integrate your Windows C++ application with Doctor Dump Crash Reporting System

C++ crash reporting integration example

The shortest way is as small as this:

#include <CrashRpt.h>

crash_rpt::CrashRpt g_crashRpt(
    "979035E1-28F6-4701-A5EF-E0200F732471", // GUID assigned to this application.
    L"Sample Application",                  // Application name that will be used in message box.
    L"Idol Software"                        // Company name that will be used in message box.
    );
                        
int main(int argc,char* argv[])
{
    ...
}

Mandatory steps

  1. Get Doctor Dump Windows SDK that contains C++ Windows crash reporting library CrashRpt.CPP:
  2. Instantiate a global crash reporter object of class CrashRpt in your application (see sample here) with these parameters:
    applicationGUID generate new static GUID (in "00000000-0000-0000-0000-000000000000" form)
    prefix some abbreviation of your app name (for example, samp for Sample Application)
    appName friendly application name that will be used in message box
    company friendly company name that will be used in message box
  3. Copy crash reporting library binaries (crashrpt.dll, sendrpt.exe and dbghelp.dll) to the output directory of your application (this is done automatically in NuGet package).
    Also you need to add these files to installer.

This is enough to see first results. Just compile, run without debugger and crash your app.

Optional steps

  1. Sign up to Doctor Dump service.
  2. Register your application.
  3. Debug Symbol information should be created for all application binaries in Release configuration.
    To create it you need to specify /Zi option for C++ compiler and /DEBUG option for linker. Or you may do this in Visual Studio project properties: PDB setup
    NOTE: The Debug Symbol information is needed to unroll the stack and for memory dump analysis. Now only Microsoft *.pdb files accepted.
  4. Symbols and binaries for public builds should be uploaded to Doctor Dump service.
    They needed to unroll the stack. You need to check that you building a public build (build that will be run by someone else) and if so - upload symbols (*.pdb) and binaries (*.exe, *.dll). To upload the symbols and binaries you should use SymUpload.exe utility that is a part of Doctor Dump SDK.
    To upload your symbols and binaries use command:

    SYMUPLOAD <app-family-id> <version> <hotfix-id> <path>, where:

    app-family-id Is an application GUID that you can see in application registration page (you have got it on step 2)
    version Application version in format "n.n.n.n", where n is from 0 to 32000
    hotfix-id 0 if unknown
    path Path or mask to your symbol/image files
    for example:
    SYMUPLOAD FDB41CEF-257D-4583-A70A-7680E777BCDE 2.1.157.0 0 .\Release\*.pdb
    SYMUPLOAD FDB41CEF-257D-4583-A70A-7680E777BCDE 2.1.157.0 0 .\Release\*.exe
    SYMUPLOAD FDB41CEF-257D-4583-A70A-7680E777BCDE 2.1.157.0 0 .\Release\*.dll
    PS: Only stripped symbols are needed by Doctor Dump. Any symbols you upload will be stripped. It is important for you to have all full symbols for all published builds since without symbols you cannot analyze a crash dumps. It is better to store symbols in symbol server. If you do not have your own symbol server it can be discussed to have it on Doctor Dump side.
  5. Add the version resource to your application
    You can add version information to any files that can have Windows resources, such as DLLs, executable files, or .fon font files. To add the information, create a VERSIONINFO Resource and use the resource compiler to compile the resource.

Best practices

  1. Integrate source server information in .pdb files
    When there is a lot of version it is very difficult to find proper sources to debug a dump. Fortunately WinDbg has very good feature - a source server. With some easy actions source information is injected in .pdb files and when source file is needed WinDbg extracts correct revision directly from source control system.
  2. Write dumps on asserts and continue execution
    Writing dumps on asserts is very useful feature. Crash dumps shows only a subset of errors with known effect (crash), but assert violations finds comparable amount of bugs that are sometimes very tricky to reproduce manually and with dumps on asserts you have an ability to investigate such cases more easily. Even more dumps on asserts can change your paradigm of debugging of some tricky issues. Before that you needed to add some logging to interesting place of code and to instruct a single user on how to make these logs. And those actions can repeat some times, because logs don't give full information about the case. With dumps on assert in that cases you often just write some asserts, and any user (not only one that report original bug) who reproduces the bug will send you a memory dump, so you have more information and you get it much faster.
    Read how to enable assertion violation reporting in CRASHRPT_ENABLE_RELEASE_ASSERTS macro documentation and related topics.
  3. Use application verifier on public (but not release) builds by default
    That practice shows itself very well. It helps to find some subset of bugs early, most important are memory corruptions, but other kind of bugs also can be found. Drawback of application verifier is some performance penalty (but it is visible only on CPU intensive applications and it could be adjusted in some range), because of that it should be enabled only on non-release builds.
    To turn on application verifier you just need to write some values to [HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\YouApp.exe] registry key on installation of you application. You may use GUI tool to setup that values and then just copy it to your installer. Full page heap options is very useful, but if you experience not acceptable performance penalty you can reduce full page heap impact by reducing full page allocation from 100% to any percent or to totally off it and use light page heap.

FAQ

  1. What to do if I write a library (DLL) that works inside a thirdparty process (plugin for example)?
    You need to set parameter ownProcess of CrashRpt constructor or InitCrashRpt method to FALSE and to use CrashRpt::SendReport function in all entry points to you code. See CrashRpt::SendReport documentation for more information.
  2. Windows has its own dbghelp.dll. Why do I need to distribute one more?
    Although this DLL is included in all supported versions of Windows, it is rarely the most current version of DbgHelp available. Furthermore, the version of DbgHelp that ships in Windows has reduced functionality from the other releases. See DbgHelp Versions for more information.
  3. I don't see a full stack trace for my release binaries.
    Turn off "Omit Frame Pointer Optimization" compiler /Oy- option because Frame Pointer Optimization complicates stack unrolling (in many cases debugger says that it cannot show full stack, only some latest calls) and memory dump analyzing (since it is harder to find some local variables). Also that optimization has no affect on performance, you can see that all Windows binaries has no FPO and even in VS2010 that optimization was turned off by default.
  4. My application has version 1.0.0.0 in Doctor Dump, how to change it?
    The application version is passed by application itself on initialization in ApplicationInfo::V field. If you use simplified initialization and don't pass ApplicationInfo struct, the version is get from your main .exe file version resource. And 1.0.0.0 is used if there is no version resource.

If you experience any troubles in any point of this instruction feel free to contact with us and we will help you.