What's new in this version?

Multi-monitor support - BugTrap may capture screenshots from several monitors

Other enhancements - Tons of features/options added since last update. See app history for details

Introduction

Some time ago, I was working on a multi-tier application with quite complex logic. The application was handling medical information, and it was important to correctly synchronize data under all circumstances. I put extra code to make the application as stable as possible, and added automatic backups and self-recovery. Do you think it solved all problems?

No, I was still searching for a tool to handle problems, seen by customers, remotely. How could I assist them and debug the problem if I lived on the other side of the globe? Eventually, I found this excellent Jim Crafton article about a tool capable of intercepting unhandled errors. That was a solution!

Unfortunately, the original black-box was not customizable, it didn't support mini-dump files or Unicode strings, and it didn't have any server. In spite of these limitations, it was an excellent starting point because I knew exactly what kind of a tool I wanted. I started working on my own tool in the hope of making it flexible and customizable, and a powerful solution.

Overview

Usually, it's very frustrating to receive a message from your customer saying that your program doesn't work. Most users may not let you know what's incorrect in your application and which piece of code went wrong. Windows has a built-in handler for unhandled errors, however, this default handler might be useless when errors happen on the customer side, because you rarely want to send your error report to Microsoft:

BugTrap solves this problem by overriding the default error handler. BugTrap gathers error details such as address, call stack, and the computer environment. It's also possible to add an arbitrary number of custom log files, with additional information on the default error report, using built-in or external logging functions.

BugTrap may save error reports on the disk, or automatically deliver error reports to the developer's computer by e-mail, over HTTP, or through a fast low-level TCP-based network protocol. The BugTrap server automatically manages the error reports repository, and notifies developers about any new errors.

BugTrap stores error descriptions in log and mini-dump files. Mini-dump files may be opened in Microsoft Visual Studio .NET and in WinDbg. The BugTrap package also includes a CrashExplorer utility that can extract symbolic information from MAP and PDB files. There is a special BugTrap version for .NET applications (currently under development).

All details are available in the BugTrap documentation. The documentation is also included as part of the Setup. If you like to know how BugTrap works, you may read these articles:

The SetupExceptionHandler() function may be called from InitInstance() or main(), depending on the type of your application.

When your application experiences a problem, the user is prompted by BugTrap to submit an error report to the BugTrap server. The error report includes many details of the user environment. The report also includes a complete stack trace for the call that caused a problem.

With BugTrap, you can debug the problem using two different approaches.

1. You can open post-mortem mini-dump files in Visual Studio:

2. You can use the built-in utility CrashExplorer:

When BugTrap is building stack traces, it searches for the PDB file – a file that holds debugging information. If this file is available, BugTrap is able to show function names and line numbers next to each address. Obviously, the PDB file makes the stack trace much nicer, but most developers prefer not to distribute PDB files to end users because PDB files could simplify program reverse engineering.

So, the end user doesn't have any clue what's behind these hexadecimal numbers.

CrashExplorer reverts back all functions names and line numbers based on the PDB/MAP file and addresses in a log:

Adding BugTrap Support to .NET Applications

.NET version of BugTrap is redistributed as managed library: BugTrapN.dll. This DLL consists of managed and unmanaged code. Such design lets BugTrap support pure managed .NET assemblies as well as mixed C++ assemblies that could throw managed .NET exceptions and native Win32/64 exceptions.

BugTrap for .NET exposes both managed and unmanaged (native) interfaces. Managed interface is accessible from C# or VB.NET code:

Building Notes

Most developers may go ahead and download the Setup - it installs all necessary files and components. However, some professionals enjoy building all components from scratch. Those developers may download BugTrap source code from here.

I have been trying to make BugTrap DLL as compact as possible. Therefore BugTrap DLL does not use MFC/ATL/WTL. I have been using pure C and C++. In particular, you will find several classes from my own library: collection classes, IO streams, built-in XML parser, etc. BugTrap DLL depends on zlib. I have included it in the archive to simplify building.

CrashExplorer depends on STL, Boost and WTL. Both libraries must be pre-installed on your computer.

Thank you!

I appreciate support, help, contributions, and even simple feedback that I am getting from many of you. BugTrap could not be in a position to meet the demands of modern software without this.

That's it! Happy bug-trapping ;-)

License

This article, along with any associated source code and files, is licensed under The MIT License

Share

About the Author

Comments and Discussions

First, thank you for this great library.
I have compiled BugTrapNetTest on Windows XP SP2 and it runs OK.
But when I try to run the compiled code on Windows Server 2003 SP2 (our software will run on this platform), it won't run.
There is no binary example for .NET from BugTrapSetup. But other MFC based examples in bin folder work fine on Windows Server 2003.

I am try to build Crash Explorer from the sources (the reason being that the vast majority of .xml/.dmp files arriving in my inbox cause Crash Explorer to crash.)

I have VS2008 SP1 but I don't seem to have some of the ATL header files e.g. atlapp.h, atlframe.h required to build Crash Explorer. Everything else seems to build fine. Typically it's just the Crash Explorer project that I need and it's the one that needs some of the ATL files

After (and if) the source is released with a license we can use with our project I do plan to host the source via github and will gladly do the repository work to keep it patched with incoming contributions.

If having the both the com and .net binary available for download, and perhaps Maksim's documentation as well, then that can be done as well.

As far as future directions for modifications of the app, what do you have in mind?

... just wanted to mention few thoughts that I didn't have a chance to implement:

1. BugTrap server could automatically sort & classify errors by exception address & version number or binary check-sum to enforce version check.

This could eliminate some of your (developer) tasks, when you are looking at error repository, since you do not have to go through every error report anymore.

All you need to do is to pick few different crashes and look into them. Duplicated error reports could be purged by server as well...

2. I thought of integrating BugTrap with one of the existing error reporting systems. Not only this would allow users to submit error reports with one click, this would also allow developers to review these errors using familiar Web interface, track fixes and collect user feedback.

Even better, when version info & line numbers are available, such Web interface could grab proper C-file from the source control and jump straight to your source code, which would be nice.

As you know, WER provides ability to gather error reports from users. It also provides functions for adding dump-files and extended log files into the reports. In fact, WER and BugTrap server does the same work. So I suggest implementing ability to add BugTrap-made minidumps and BugTrap logs to WER.

Probably some of you have noticed silence and the lack of new releases.
The inactivity was caused by the change of my work and the life style.

I am no longer a freelance individual spending my personal time on something interesting.
I had to switch that [pretty lame] way of making money and supporting my family.

I found a job in a big and demanding company, where I got a chance to work on more challenging projects. Since then, the amount of my free time was greatly reduced and I had to stop contributing to free projects, at least for some time.

At the same time, I'd be happy to know that project is still being developed and used by someone else.
Recently I was contacted by developers willing to continue development of BugTrap. But I was asked to release BugTrap under terms of less restrictive license that would allow anyone to make changes to the source code.

We have decided to release BugTrap under the terms of the Code Project Open License, that will not limit you in using BugTrap in free or commercial projects.

This is the best that I can do now. I very much hope that this will give BugTrap a fresh breath.

This is all good news! Except that you had to stop doing the 'scratch your own itch' method of making money.

I can't really commit to being the _main_ maintainer of the project as of right now but I surely can commit to being a repository maintainer. The problem I see is that I can't because of the CPOL license! First, thank you for altering it, but there is a concern here for projects desiring to include the BugTrap with their own apps though and that arises from:

=== Item 5.e of the CPOL ===
# You may distribute the Executable Files and Source Code only under the terms of this License, and You must include a copy of, or the Uniform Resource Identifier for, this License with every copy of the Executable Files or Source Code You distribute and ensure that anyone receiving such Executable Files and Source Code agrees that the terms of this License apply to such Executable Files and/or Source Code. You may not offer or impose any terms on the Work that alter or restrict the terms of this License or the recipients' exercise of the rights granted hereunder. You may not sublicense the Work. You must keep intact all notices that refer to this License and to the disclaimer of warranties. You may not distribute the Executable Files or Source Code with any technological measures that control access or use of the Work in a manner inconsistent with the terms of this License.
===

The part that is concerning is::

You distribute and ensure that anyone receiving such Executable Files and Source Code agrees that the terms of this License apply to such Executable Files and/or Source Code.

That means the source has to have acknowlegement of agreement prior to downloading the source. This totally eliminates distributed version control systems if I'm reading it correctly.

If that _is_ the case then please, please, please, alter the license to GPL, Apache, or MPL.

I'll be glad to host the repo on github and keep it up to date with patches from contributors.

Seconded! This could be really useful, and it'd be great to add some things to it, and distributed version control is really good at getting people involved, but the license needs to support it. I read the license the same way the previous poster does, and that seems to prohibit not only DVCS but also plain downloading an exe that uses it, without first clicking an "I Accept" button (ok that could be done in an installer, but for the project I'm involved in, there isn't necessarily an installer, it's just one download option, zip being another).

Be good to hear your thoughts on changing the license (again!).... kudos for open sourcing it (and writing it in the first place) though!

Please reconsider switching to LGPL. Some of my clients have legal departments with nothing better to do, and they have refused to let me use LGPL code on their projects. This is a major pain, and really makes life difficult.

If someone has told you that the LGPL eliminates the problem of using code in commercial products, then they have given you bad information. Last month I had to sit through a two-hour meeting with client lawyers, who told me flatly that they would never approve LGPL code for any reason. They said this in the first two sentences. The rest of the two-hour meeting was spent going into crushing detail about what Bad Things could potentially happen with LGPL code, and giving examples of companies who have had trouble with LGPL. Most of the time I had no idea what they were talking about, but there is one thing I am very sure of: I can't use LGPL code for that client.

Chris Maunder has done a lot of research into this. Email him at chris at codeproject dot com if you want to ask him about this stuff. Or you can just google for "LGPL problem" with a lot of coffee.

I was afraid that I won't make everyone happy when I was asking about proper licensing and sure enough his happened.
Unfortunately it is too late to switch license third time after everyone else was in agreement with LGPL.

You can keep the source code that you are using right now to workaround this issue - that source code was released under the terms of COPL.

Yeah, just use the previous release for those few customers who don't allow LGPL, it has obviously been working for you to use it for them up until now, and since no source code changes have taken place...

As for the project itself the LGPL does seem to offer the right protections.

The contact form at intellesoft.net results in a bounced email, and I can't find any email address anywhere. I wrote a PHP server for this, and am interested in trading it for either some small but critical fixes, or else for an exclusion to the terms that forbid code modification.