Reference Ids

Nikolaj Jørgensen edited this page Jan 14, 2017 · 8 revisions

Reference Ids are unique identifiers that let you look up a submitted event. This is important because event Ids are not created until after an event is processed, so there's no other way to look up an event.

Reference Ids are also used to help deduplicate events on the server side.


One example of using Reference Ids is to help support your users. For instance, we always include a Reference Id with every error message for our users, allowing them to contact us with that Reference Id and receive help faster because we can easily track it down.

Reference Id Example

To attach Reference Ids to our errors in Exceptionless, we register a default Reference Id plugin that sets a Reference Id when the event is submitted and stores the Id in an implementation of ILastReferenceIdManager. With the default plugin, we enable this behavior by calling UseReferenceIds() on the configuration object.

C# Example

using Exceptionless;

JavaScript Example


You can also create your own plugin to create your own Reference Ids.

Get Last Used Reference Id

Call GetLastReferenceId() on the ExceptionlessClient instance.

C# Example

using Exceptionless;
// Get the last created Reference Id

JavaScript Example

// Get the last created Reference Id

Displaying Reference Ids to End Users

We do this for our end users because it allows them to better support their app users.

To do so, we add a custom IExceptionHandler and return a new error response to include the Reference Id as shown below:

public class ExceptionlessReferenceIdExceptionHandler : IExceptionHandler {
    public Task HandleAsync(ExceptionHandlerContext context, CancellationToken cancellationToken) {
        if (context == null)
            throw new ArgumentNullException(nameof(context));
        var exceptionContext = context.ExceptionContext;
        var request = exceptionContext.Request;
        if (request == null)
            throw new ArgumentException($"{typeof(ExceptionContext).Name}.{"Request"} must not be null", nameof(context));
        context.Result = new ResponseMessageResult(CreateErrorResponse(request, exceptionContext.Exception, HttpStatusCode.InternalServerError));
        return TaskHelper.Completed();
    private HttpResponseMessage CreateErrorResponse(HttpRequestMessage request, Exception ex, HttpStatusCode statusCode) {
        HttpConfiguration configuration = request.GetConfiguration();
        HttpError error = new HttpError(ex, request.ShouldIncludeErrorDetail());
        string lastId = ExceptionlessClient.Default.GetLastReferenceId();
        if (!String.IsNullOrEmpty(lastId))
            error.Add("Reference", lastId);
        // CreateErrorResponse should never fail, even if there is no configuration associated with the request
        // In that case, use the default HttpConfiguration to con-neg the response media type
        if (configuration == null) {
            using (HttpConfiguration defaultConfig = new HttpConfiguration()) {
                return request.CreateResponse(statusCode, error, defaultConfig);
        return request.CreateResponse(statusCode, error, configuration);

Then we replace the existing IExceptionFilter

Config.Services.Replace(typeof(IExceptionHandler), new ExceptionlessReferenceIdExceptionHandler());

Now you'll get a user friendly error response that contains a Reference Id, like:

{ "message": "An error has occurred.", “reference”: “411085622e” }

Looking up Events by Reference Id


Link directly to an event by outputting a link in your UI or log files, like


Or you can search via the api/ui with reference:YOUR_REFERENCE_ID

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.