| crashrpt |
A crash reporting system for Windows applications

# Architecture Overview

## CrashRpt Mission

The mission is to provide a set of tools for:

- handling exceptions (critical errors) in a client software
- automatically collecting necessary error info and generating error reports
- deliverying error reports over the internet
- and simplifying error report postprocessing

## CrashRpt Stakeholders

Stakeholders are the individuals or groups that have their concerns in CrashRpt architecture:

- Developers that are interested in improving their software by analyzing user feedback on critical errors
- Software end-users that are interested in better quality of programs they install and use
- CrashRpt development team members that are interested in providing a set of convenient crash reporting tools that are widely used

## Non-functional Requirements

Usability. CrashRpt end-users should be provided with a user-friendly, clean and intuitive GUI. GUI should be localizable to end-user's favourite language.

Compatibility. CrashRpt should support Windows operating system. 32-bit and 64-bit platforms should be supported. Visual C++ development environment should be supported.

Rubustness. CrashRpt should provide crash reporting services not depending of client application state. Client application may be unstable, heap-corrupted, stack-corrupted and so on.

Testability. The main features should be covered by automated tests to guarantee expected behavior.

## CrashRpt Structure Overview

CrashRpt consists of two kinds of functionality: error reporting functionality and error report analyzis functionality. Error reporting functionality is distributed with a client software and responsible for handling exceptions in the client software and deliverying error reports to the developer.

Error report analyzis functionality is designed to help the developer to extract data contained in error reports and to simplify error report analyzis. It is usually located at the side of the developer and not distributed with the client software.

CrashRpt Architecture

### Error Reporting Functionality

Error reporting functionality consists of two core modules: CrashRpt.dll and CrashSender.exe.

- CrashRpt.dll contains functionality for handling exceptions in the client software.
- CrashSender.exe contains functionality for sending error reports to the software's support team.

Two modules are needed to be able to close the application that crashes and to continue sending error report through CrashSender.exe in background.

Typically a process (executable file) loads CrashRpt.dll into its address space when process starts. This single instance of CrashRpt is shared between all DLL modules that are loaded into the process' address space. Client application uses CrashRpt Functions to set exception handlers in the process once, typically in its main() function. In a multi-threaded program, client additionally sets exception handlers in the beginning of thread procedure of each worker thread. For additional info, see Using CrashRpt API.

CrashRpt is designed to use C runtime libraries (CRT) as a Multi-threaded DLL (/MD compiler flag). All modules in the client application must be linked to the same version of CRT DLL in order to use CrashRpt. If some dependent module of the application uses different version of CRT or is statically linked to CRT, exceptions are not intercepted in that module. For more information, see About Exceptions and Exception Handling.

In Visual C++, some exceptions related to security can't be intercepted. For example, since CRT v8.0 you can not handle security errors. When buffer overrun is detected, CRT invokes Dr. Watson directly instead of calling unhandled exception filter. This is done because of security reasons and Microsoft doesn't plan to change this behavior.

### Error Report Analyzis Functionality

Error report analyzis functionality consists of two modules:

- CrashRptProbe.dll implements API that can be used to access error report data.
- crprober.exe is a console tool that helps to extract error report data and write the summary in a human-readable form.

When you receive many error reports from users of your software, you would have to spend a lot of time to open each report, analyze its contents and write some summary about the report. There may be many reports related to the same problem, so opening such reports doesn't tell anything new. The error report analyzis functionality is designed to address these problems. For additional information, see Analyzing Error Reports.

## FAQ

My software is not an EXE, but DLL. Can I use crashrpt in such case?

Well, you can install exception handlers in your DllMain() function, but typically you can't guarantee that the client process (EXE) won't install its own exception handlers above yours. And there might be some problems if the client process uses several worker threads that call functions from your DLL. In such case you would have to install per-thread exception handlers too. It would be better if the client process take care of exception handling instead of your DLL.

How do I use crashrpt across process boundaries?

Each process loads its own copy of `CrashRpt.dll`. It is difficult to imagine how you can share single loaded instance of CrashRpt.dll between several processes. Currently CrashRpt doesn't support such possibility.

Does using crashrpt affect performance of my application?

No, using CrashRpt doesn't affect performance of your application. CrashRpt doesn't perform any tasks in background and doesn't use additional memory. CrashRpt code is executed just when an exception is raised.

Does using crashrpt make it easier for somebody to reverse engineer my code?

No, actually not. In order to use CrashRpt, you enable program database generation in Release configuration (/Zi compiler flag and /DEBUG linker flag) and this generates .PDB file for your project. PDB files contain information which can be used to reverse engineer your code, however you typically store such information locally and do not distribute it with your software release package. So, using CrashRpt doesn't affect the difficulty of reverse engineering your code.