Click here to Skip to main content
12,759,971 members (30,021 online)
Click here to Skip to main content
Add your own
alternative version


42 bookmarked
Posted 8 Sep 2016

OneTrueError - Automated exception handling

, 8 Sep 2016 Apache
Rate this:
Please Sign up or sign in to vote.
OneTrueError is an open source error handling service. It includes the context information that you forgot to include when you logged/reported the exception.


This article is from an usage perspective. It will guide you trough all the features and show how you can get started with your own application. Another article will be posted in a week which will describe the architecture and how you can extend the server.

OneTrueError is an open source service used to detect and analyze exceptions. It works over unstable network connections and even behind corporate proxies. It attaches context information to each reported exception, which makes it significantly easier to identify and correct the cause of the exception.


I've been programming for over 20 years. During that time, error management has been a recurring problem. Especially if your application is installed on an user computer. User reports tend to be sparse with not enough details to be able to reproduce the problem. You either have to make educated guesses or just do monkey testing to identify the root cause.

The worst problem is when think that you have found the cause and correct it. But later you receive a new error report for the same problem. What you have done then is to actually worsen the code base.

The de facto standard for error reporting have been logging. But you know how it is, we try to be good at logging and include enough details. But haven't we missed that important field that would have told us why the exception was thrown?

OneTrueError is an attempt to solve these problems. It bypasses the user and reports exceptions, including relevent context information, directly to the programmers without a middle man.

Feature tour

Let's start by going through all the features. The last chapter in the article contains a step-by-step guide to get started.

OneTrueError consists of a client (nuget packages) and a server (IIS web application). The client detects exceptions in your application, collect context information and uploads everything to the server.

Let's report an excpetion through a simple console program to see what kind of bells and whistles we get.

class Program
    static void Main(string[] args)
        // Initialization
        var url = new Uri("http://localhost/onetrueerror/");
        OneTrue.Configuration.Credentials(url, "yourAppKey", "yourSharedSecret");

            throw new InvalidOperationException("Hello world");
        catch (Exception ex)

When that code is run the exception will be uploaded to the server. When you go to your OneTrueError website you will see something like this:

The dashboard gives you an overview over all applications that have been configured in OneTrueError.

The information presented:

IncidentAn aggregation of all reported exceptions that have been identified as the same error.
Active incidentsIncidents which have not been solved or ignored.
ReportAn uploaded error report.
Users WaitingUsers that have entered their email address when they got the error page (due to an exception).
Feedback countNumber of error descriptions written by users.

Let's click on the incident to get more information about that specific error.


Incidents are used to group error reports together. Unlike log libraries, OneTrueError will not generate 5000 different errors if you receive the same exception 5000 times. Instead OneTrueError identifies that the received report is for the same exception as a previous report. Both reports are grouped together under an incident. ISO 20000 defines an incident as;


unplanned interruption to a service, a reduction in the quality of a service or an event that has not yet impacted the service to the customer.

.. which fits well with what your user(s) experience when an exception is thrown.

Illustration of an incident

The incident page contains information about a specific error. From here you can browse all reports that we've received for the error. I've run my sample application one more time get a total of two reports listed under the incident.

There are two actions that you can take on incidents:

  • Close incident - Mark it as solved/corrected (i.e. it should not happen again)
  • Ignore incident - Do not store any more reports or generate notifications for this incident

When you ignore an incident, all new reports will be thrown away. The report counter will continue to grow to allow you to see that reports are still being received. The new reports will however not be analyzed or stored.

When you close an incident you can also write a message which will be distributed to all users that are waiting on a new version. It's all done through OneTrueError and only to users that signed up to status notifications when the exception was thrown.

Below are some of the analysis features that have been implemented in OneTrueError to date.


If you look at the screen shot above you'll notice the console-application tag. OneTrueError identifies a number of StackOverflow tags for incoming reports. If you click on a tag you'll be directed to a search for the exception message filtered for that tag only.

Showcase of a search

Error origins

Error origins shows where error reports are received from. The information is presented as a heat map. Thus you can easily identify if the error is more frequently occuring in a certain region. That indicates that the error is related to localization or cultural issues.

A map displaying all error origins

Context data

The context data under the incident is a combination of aggregation and specialization. Collections are first specialized, for instance the web browser "User-Agent" string is extracted to it's own collection. Once done the 
information is aggregated and then compared. OneTrueError can therefore tell you for instance if 99% of the error reports for an incident is for the culture "sv-SE", or if there was less then 100Mb memory available in the operating system for all reports.

Demonstrates the localization collection specialization which is generated from OS WMI information

Feedback / Error descriptions

OneTrueError provides a way for users to leave an error description when an exception is caught. i.e. they can describe what they did when the exception occurred. They can also leave their email address to get a notification when the incident is closed.

The manual way to leave feedback is to do something like this:

//last param is email address
var feedback = new UserSuppliedInformation("I pressed the 'any' key.", null); 
OneTrue.LeaveFeedback(errorIdFromReport, feedback);

Once uploaded the feedback will be available under the incident:
Shows how the description looks like once uploaded

The more feedback your users provide, the easier to identify and correct the issue.

Error reports

Incidents are a great way to get an overview of which different errors your application have, including information like how often they occur and what they have in common. However, it's sometimes better to get into the details of each specific error report to understand why the exception was thrown.

Therefore you can click of any of the reports in the list under the incident to take a peek.


Ever wanted to get informed directly when an exception is thrown in your application?

OneTrueError supports multiple types of notifications. You can either get a text to your cell phone or an email message.

These are the notifications that OTE supports:

Client libraries

A client library is used to report exceptions. The library can either do it fully automated by injecting itself into your favorite library/framework's pipeline, or by invocations made by you.

The libraries that we have built so far is:

OneTrueError.clientOur reporting library, allows you to manually report exceptions.
OneTrueError.client.aspnetGeneric ASP.NET library. Catches all unhandled exceptions and report them. Collects information about the HTTP request, session data etc. Allows you to easily create custom error pages for different HTTP error codes.
OneTrueError.client.mvc5ASP.NET MVC5 specific library. Does the same as the ASP.NET library, but do also collect specific MVC5 information like route data, ViewBag etc. Also allows you to customize your error pages by just creating razor views in the error view folder.
OneTrueError.client.wcfCatches unhandled exceptions in the WCF pipeline. Collects WCF specific information like the inbound WCF message that failed to be processed.
OneTrueError.client.log4netReports all exceptions that you log, including the error message that you wrote.
OneTrueError.client.winformsReports all unhandled exceptions. Can take screen shots and collect the state of all open forms.

It's also possible to report exceptions directly by your own library/application. The client specification (HTTP/JSON) is available in the online documentation.

Core library

This library is the foundation of all exception reporting done with OneTrueError. All other client libraries are based upon this one.

With the core library you have to report exceptions manually like this:

catch (Exception ex)

You can also attach different kinds of context information which we'll get back to in the 'Getting started' chapter.

Context collections

A context collection is a set of properties which is fetched from a specific source. A context collection can be HTTP Headers, a view model, Route data etc.

There are few built in context collections in the core library. Some are added to the pipeline per default, which means that they are included every time an exception is reported. Other collections require that you to add them manually when configuring the client library.

If you like, you can also create and include your own easily.

Application information

This collection includes information about your process. It contains information like used memory, thread count and amount of used CPU.


All assemblies that have been loaded into the AppDomain and their versions.

Exception information

Information from the exception, including all properties. If you have ever used EntityFramework and got the DbEntityValidationException? It's exception message just says:


System.Data.Entity.Validation.DbEntityValidationException: Validation failed for one or more entities. See 'EntityValidationErrors' property for more details

Since OneTrueError includes all properties, you get the validation information directly. Much better then just getting exception.ToString() in a log file, huh?

File versions

File versions for all assemblies, as the assembly version might be the same while the file version is higher (GAC hell anyone?).

Operating system

Does the error happen on all windows editions or just some of them?

System information

Is the amount of available RAM memory a show stopper?

Thread information

Thread information like current UI culture.

Which thread crashed? Hint: Name threads if you start them yourself


This library is intended for ASP.NET projects which are not using MVC. So it works great for libraries based on ASP.NET such as Nancy.

Context collections

These collections are generated by the ASP.NET library.

HTTP headers

All HTTP headers for the request that failed.

Uploaded files

Name, size and context type of all files that was uploaded in the request.


All items in the HTTP form (name and value).


Query string variables (key and value).


All session items (support for complex objects).

Error pages

The library contains a custom error page which can be activated (and shown) when an exception is caught.

To activate it add the following code:

var provider = new VirtualPathProviderBasedGenerator("~/Errors/");

The code says that the library should look after error pages (either .aspx or .html) in the specified folder:

The library tries to find pages based on the HTTP code. If the code is 404 the library tries to find the following error pages:

  1. FileNotFound.aspx
  2. FileNotFound.html
  3. Error.aspx
  4. Error.html

That is, it tries to find the most specific file first. If a specific file do not exist it tries to load a generic one.

Error information

To get information into your view, simply declare one of the following properties in your code behind.

ErrorContextHttpErrorReporterContextLook in the Client API specification for more information
ExceptionExceptionThe caught exception



public partial class NotFound : System.Web.UI.Page
	protected void Page_Load(object sender, EventArgs e)


	public Exception Exception { get; set; }

	public HttpErrorReporterContext ErrorContext { get; set; }

Then simply display the error information in your HTML:

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="NotFound.aspx.cs" Inherits="OneTrueError.Client.AspNet.Demo.Errors.NotFound" %>
<!DOCTYPE html>
<html xmlns="">
<head runat="server">
    <title>Failed to find <%= Exception.Message %></title>
	<form method="post" action="$URL$">
		<input type="hidden" value="$reportId$" name="reportId" />
            Page is not found
            <%= ErrorContext.HttpStatusCode  %>
			<p>Could you please let us know how to reproduce it? Any information you	 give us will help us solve it faster.</p>
			<textarea rows="10" cols="40" name="Description"></textarea>

If you are just using HTML you can use the following template strings:

Template textDescription
$ExceptionMessageException message
$reportId$Generated report id
$URL$OneTrueErrors own url to submit error description, email etc.
$AllowReportUploading$If you want to allow the user to decide whether the report should be uploaded



<!DOCTYPE html>
<html lang="en">
    <meta charset="utf-8" />
    <title>An error occurred</title>
    <meta name="ROBOTS" content="NOINDEX, NOFOLLOW" />
    <meta name="X-powered-with" content="" />
    <style type="text/css">
    <div style="" class="container">
        <div style="width: 100%; text-align: center">
            <h1>Looks like something went wrong!</h1>
        <form method="post" action="$URL$">
            <div class="img">
                <img src="/images/Error.jpg" />
            <div class="content">
                    Thanks for taking the time and letting us know about the issue.
                    We’re working to fix it for you as fast as we can, apologies for the inconvenience.
                <input type="hidden" value="$reportId$" name="reportId" />
                <div class="AllowSubmissionStyle">
                        However, If you allow us to collect additional error information we'll be able to analyze this error much faster.
                    <input type="checkbox" name="Allowed" value="true" checked="$AllowReportUploading$" />
                    I allow thy to collect the additional information.
                <div class="AllowFeedbackStyle">
                    <p>Could you please let us know how to reproduce it? Any information you give us will help us solve it faster.</p>
                    <textarea rows="10" cols="40" name="Description"></textarea>

                <div class="AskForEmailAddress">
                    <p>Enter your email address if you would like to receive status updates about this error.</p>
                    <input type="text" name="email" placeholder="email address" />
                <hr />
                <input type="submit" value="Send report" />
                <a href="/">Back to homepage</a>
            <div style="clear: both;"></div>


This client library will provide both ASP.NET and MVC specific context information for OneTrueError.

Apart from detecting and uploading uncaught exceptions the library also provide the following features.

Error pages

The library have build in support for error pages.

To use the ones included in the library, add the following in global.asax (after the OneTrue.Configuration.Credentials() line):


Custom error pages

If our built in pages are not preferable you can include your own views.


@model OneTrueError.Client.AspNet.Mvc5.OneTrueViewModel

<h1>Internal Server Error</h1>
    We've experienced a malfunction in the core crystal cooling. The ship will explode within five seconds.


Views should be named as the HTTP codes are defined in the HttpStatusCode enum in .NET and be placed in the Views/Errors folder.

The Error.cshtml view is displayed if no other view matches.


If it's not enough to control the error handling through views only you can create your own ErrorController. Create it like any other controller in the Controllers folder.

The action methods should be named like the views. i.e. public ActionResult InternalServer().

The information provided by OneTrueError is represented as OneTrueViewModel. Take it as a parameter to your action methods.


public class ErrorController : Controller
    public ActionResult Index(OneTrueViewModel model)
        return View("Error", model);

    public ActionResult NotFound(OneTrueViewModel model)
        return View(model);

    public ActionResult InternalServerError(OneTrueViewModel model)
        return View(model);


Custom formats

An error object will be returned if XML or JSON is requested by the HTTP client. Great for ASP.NET WebApi.


  "error": { 
	"msg": "The error message", 
	"reportId": "Unique error id"
  hint: "Use the report id when contacting us if you need further assistance." 


<Error ReportId="Unique error id" hint="Use the report id when contacting us if you need further assistance">
	Error message

Context collections

The following collections are provided by the ASP.NET MVC library.


The controller name is collected.


Information about the route that MVC took is collected.


TempData is collected if set.


TempData["DemoKey"] = new {
		Amount = 20000,
		Expires = DateTime.UtcNow.AddMinutes(5)


ViewData / ViewBag

The Viewbag and/or ViewData is collected if specified.


ViewBag.Title = "Hello";
ViewBag.Model = new
	state = "Running",
	Collected = true


log4net client

The log4net library injects OneTrueError into the logging pipeline of log4net. Each time you log something and include an exception it will be reported to OneTrueError. This is by far the easiest way to use the power of OneTrueError in legacy applications (which use log4net).


If you have code like this:

catch (Exception ex)
	_logger.Warn("Failed doing some crazy stuff.", ex);

.. the exception will be picked up in OneTrueError.

As a bonus you will also see information about the log entry in OneTrueError:


The WinForms client library can help you display error pages and collect information about the open forms.

Error pages

An error page is displayed when an exception is detected. It looks like this per default:

You configure it by using the following properties:

OneTrue.Configuration.UserInteraction.AskUserForDetails = true;
OneTrue.Configuration.UserInteraction.AskUserForPermission = true;
OneTrue.Configuration.UserInteraction.AskForEmailAddress = true;


all flags set

only ask for permission

only details

only email

Context information

WinForms have two built in context collections.


OneTrueError collects information from all open forms using reflection. The information includes all controls and their configuration (position, content, visibility etc)

Let's say that you got this form open:

..which will give you this information:


Screnshots can be activated by one of the following configuration lines:

//only of the active form

// of all forms            

The context collection will be shown as:

The one true error pipeline

Here is a small diagram showing what steps OneTrueError takes to make sure that your exceptions are detected, caught, wrapped with context information and finally uploaded to the service for analysis.

It also identifies significant method calls if you would like to browse the code and get a hang of how things work together. Tip: Right-click in Visual Studio on the code line and use "Find usages" / "Find references" to see where the method call comes from.

(CodeProject have a width limit on images, see the full size image here)

Getting started

A guide to help you report the first error.

Server installation

You can either download the source code for the server, compile and install it, or use the precompiled version. Either way the installation is a xcopy deployment.

  1. Download or compile
  2. Copy the binaries to a new webserver folder, typically c:\inetpub\wwwroot\onetrueerror
  3. Go to IIS and use the context menu choice "Add application.." or "Add website.."
  4. Name it "OneTrueError" and point on the folder that you created.
  5. Create a database in your SQL server and modify the connection string in web.config.
  6. Browse to the website (using your web browser)
  7. Follow the setup wizard
  8. One the wizard is completed, change the appKey Configured to true in web.config.

The server is now installed.

Getting the appKey/sharedsecret

To be able to report exceptions you need an appKey and a sharedSecret. The first one is used to identify which application the error report is for, the latter is used to sign all uploaded reports. These can be found under the application that you create from the top menu in OneTrueError.

Once you've created an application you can find the appKey and the sharedSecret in the right side panel:

shows where the appKey can be found

If you prefer, click on the help icon and you get a copy/paste ready instruction:

copy/paste configuration


The first thing you need to do is to tell where the uploads should be sent and which application the reports are for. The URL should point on your local server installation.

var url = new Uri("http://yourServer/onetrueerror/");
OneTrue.Configuration.Credentials(url, "yourAppKey", "yourSharedSecret");

The easiest way to report an exception is like this:

catch(SomeException ex)

The exception should appear in your server installation shortly after being reported.

Attaching context information

Usually an exception is not enough information alone to be able to understand why the exception was thrown. OneTrueError will always collect a large number of parameters for you. You might however have information that directly allows you to understand why the exception was thrown.

That information can be attached when reporting:

    //some stuff that generates an exception
catch (Exception ex)
    OneTrue.Report(ex, yourContextData);

Using anonymous object

If you need to attach multiple values you can use an anonymous object:

    //some stuff that generates an exception
catch (Exception ex)
    OneTrue.Report(ex, new { UserId = userId, UserState = state });


Custom collections

We also have an object extension method which can transform any object into a context collection (one of the groups in the "Context Data" menu in our web site).

Below we are using the .ToContextCollection() extension method.

    <span spellcheck="true">//some stuff that generates an exception</span>
catch (Exception ex)
    var modelCollection = viewModel.ToContextCollection("ViewModel");
    var loggedInUser = User.ToContextCollection("User");
    OneTrue.Report(ex, new[]{modelCollection, loggedInUser});


Hence you can easily attach and group your information just as you like.

Categorize exceptions using tags

We automatically identify common tags when analyzing exceptions (to help you find answers by searching You can also add your own tags by adding a special property, named "OneTrueTags", to any context collection:

    //some stuff that generates an exception
catch (Exception ex)
    OneTrue.Report(ex, new { OneTrueTags = "important,backend" });


More information

.. or just follow us on twitter to get updates.


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


About the Author

Founder Gauffin Interactive AB
Sweden Sweden
Founder of OneTrueError, a .NET service which captures, analyzes and provide possible solutions for exceptions.

blog | twitter

You may also be interested in...

Comments and Discussions

QuestionMy Vote of 5 Pin
Sir Zeppa'Man7-Nov-16 0:16
professionalSir Zeppa'Man7-Nov-16 0:16 
GeneralMy vote of 5 Pin
Manuel A Lombardi T25-Oct-16 7:16
memberManuel A Lombardi T25-Oct-16 7:16 
QuestionMessage Removed Pin
Blake A Niemyjski11-Oct-16 18:25
memberBlake A Niemyjski11-Oct-16 18:25 
AnswerMessage Removed Pin
jgauffin11-Oct-16 20:01
memberjgauffin11-Oct-16 20:01 
QuestionWebAPI Pin
TimCirrus13-Sep-16 3:32
memberTimCirrus13-Sep-16 3:32 
AnswerRe: WebAPI Pin
TimCirrus13-Sep-16 3:40
memberTimCirrus13-Sep-16 3:40 
Questionpretty cool Pin
Sacha Barber12-Sep-16 3:53
mvpSacha Barber12-Sep-16 3:53 
QuestionGreat work Jonas Pin
Garth J Lancaster8-Sep-16 15:35
professionalGarth J Lancaster8-Sep-16 15:35 
AnswerRe: Great work Jonas Pin
jgauffin9-Sep-16 9:28
memberjgauffin9-Sep-16 9:28 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

Permalink | Advertise | Privacy | Terms of Use | Mobile
Web02 | 2.8.170217.1 | Last Updated 8 Sep 2016
Article Copyright 2016 by jgauffin
Everything else Copyright © CodeProject, 1999-2017
Layout: fixed | fluid