Logging to elmah.io from ASP.NET Core

If you are looking to log all uncaught errors from ASP.NET Core, you've come to the right place. For help setting up general .NET Core logging similar to log4net, check out Logging from Microsoft.Extensions.Logging.

To log all warnings and errors from ASP.NET Core, install the following NuGet package:

Install-Package Elmah.Io.AspNetCore

dotnet add package Elmah.Io.AspNetCore

<PackageReference Include="Elmah.Io.AspNetCore" Version="4.*" />

paket add Elmah.Io.AspNetCore

In the Startup.cs file, add a new using statement:

using Elmah.Io.AspNetCore;

public void ConfigureServices(IServiceCollection services)
{
    services.AddElmahIo(options =>
    {
        options.ApiKey = "API_KEY";
        options.LogId = new Guid("LOG_ID");
    });
    // ...
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory fac)
{
    // ...
    app.UseElmahIo();
    // ...
}

builder.Services.AddElmahIo(options =>
{
    options.ApiKey = "API_KEY";
    options.LogId = new Guid("LOG_ID");
});

app.UseElmahIo();

Make sure to call the UseElmahIo-method after installation of other pieces of middleware handling exceptions and auth (like UseDeveloperExceptionPage, UseExceptionHandler, UseAuthentication, and UseAuthorization), but before any calls to UseEndpoints, UseMvc, MapRazorPages, and similar.

That's it. Every uncaught exception will be logged to elmah.io. For an example of configuring elmah.io with ASP.NET Core minimal APIs, check out this sample.

Configuring API key and log ID in options

If you have different environments (everyone has a least localhost and production), you should consider adding the API key and log ID in your appsettings.json file:

{
  // ...
  "ElmahIo": {
    "ApiKey": "API_KEY",
    "LogId": "LOG_ID"
  }
}

Configuring elmah.io is done by calling the Configure-method before AddElmahIo:

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<ElmahIoOptions>(Configuration.GetSection("ElmahIo"));
    services.AddElmahIo();
}

Notice that you still need to call AddElmahIo to correctly register middleware dependencies.

Finally, call the UseElmahIo-method (as you would do with config in C# too):

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    // ...
    app.UseElmahIo();
    // ...
}

You can still configure additional options on the ElmahIoOptions object:

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<ElmahIoOptions>(Configuration.GetSection("ElmahIo"));
    services.Configure<ElmahIoOptions>(options =>
    {
        options.OnMessage = msg =>
        {
            msg.Version = "1.0.0";
        };
    });
    services.AddElmahIo();
}

Logging exceptions manually

While automatically logging all uncaught exceptions is definitely a nice feature, sometimes you may want to catch exceptions and log them manually. If you just want to log the exception details, without all of the contextual information about the HTTP context (cookies, server variables, etc.), we recommend you to look at our integration for Microsoft.Extensions.Logging. If the context is important for the error, you can utilize the Ship-methods available in Elmah.Io.AspNetCore:

try
{
    var i = 0;
    var result = 42/i;
}
catch (DivideByZeroException e)
{
    e.Ship(HttpContext);
}

When catching an exception (in this example an DivideByZeroException), you call the Ship extension method with the current HTTP context as parameter.

From Elmah.Io.AspNetCore version 3.12.* or newer, you can log manually using the ElmahIoApi class as well:

ElmahIoApi.Log(e, HttpContext);

The Ship-method uses ElmahIoApi underneath why both methods will give the same end result.

Breadcrumbs

See Logging breadcrumbs from ASP.NET Core.

Additional options

Setting application name

If logging to the same log from multiple web apps it is a good idea to set unique application names from each app. This will let you search and filter errors on the elmah.io UI. To set an application name, add the following code to the options:

services.AddElmahIo(o =>
{
    // ...
    o.Application = "MyApp";
});

The application name can also be configured through appsettings.json:

{
  // ...
  "ElmahIo": {
    // ...
    "Application": "MyApp"
  }
}

Hooks

elmah.io for ASP.NET Core supports a range of actions for hooking into the process of logging messages. Hooks are registered as actions when installing the elmah.io middleware:

services.AddElmahIo(options =>
{
    // ...
    options.OnMessage = message =>
    {
        message.Version = "42";
    };
    options.OnError = (message, exception) =>
    {
        logger.LogError(1, exception, "Error during log to elmah.io");
    };
});

The actions provide a mechanism for hooking into the log process. The action registered in the OnMessage property is called by elmah.io just before logging a new message to the API. Use this action to decorate/enrich your log messages with additional data, like a version number. The OnError action is called if communication with the elmah.io API failed. If this happens, you should log the message to a local log (through Microsoft.Extensions.Logging, Serilog or similar).

Do not log to elmah.io in your OnError action, since that could cause an infinite loop in your code.

While elmah.io supports ignore rules serverside, you may want to filter out errors without even hitting the elmah.io API. Using the OnFilter function on the options object, filtering is easy:

services.AddElmahIo(options =>
{
    // ...
    options.OnFilter = message =>
    {
        return message.Type == "System.NullReferenceException";
    };
});

The example above, ignores all messages of type System.NullReferenceException.

Decorate from HTTP context

When implementing the OnMessage action as shown above you don't have access to the current HTTP context. Elmah.Io.AspNetCore already tries to fill in as many fields as possible from the current context, but you may want to tweak something from time to time. In this case, you can implement a custom decorator like this:

public class DecorateElmahIoMessages : IConfigureOptions<ElmahIoOptions>
{
    private readonly IHttpContextAccessor httpContextAccessor;

    public DecorateElmahIoMessages(IHttpContextAccessor httpContextAccessor)
    {
        this.httpContextAccessor = httpContextAccessor;
    }

    public void Configure(ElmahIoOptions options)
    {
        options.OnMessage = msg =>
        {
            var context = httpContextAccessor.HttpContext;
            msg.User = context?.User?.Identity?.Name;
        };
    }
}

Then register IHttpContextAccessor and the new class in the ConfigureServices method in the Startup.cs file:

public void ConfigureServices(IServiceCollection services)
{
    services.AddHttpContextAccessor();
    services.AddSingleton<IConfigureOptions<ElmahIoOptions>, DecorateElmahIoMessages>();
    // ...
}

Decorating messages using IConfigureOptions requires Elmah.Io.AspNetCore version 4.1.37 or newer.

Include source code

You can use the OnMessage action to include source code to log messages. This will require a stack trace in the Detail property with filenames and line numbers in it.

There are multiple ways of including source code to log messages. In short, you will need to install the Elmah.Io.Client.Extensions.SourceCode NuGet package and call the WithSourceCodeFromPdb method in the OnMessage action:

services.AddElmahIo(options =>
{
    // ...
    options.OnMessage = msg =>
    {
        msg.WithSourceCodeFromPdb();
    };
});

Check out How to include source code in log messages for additional requirements to make source code show up on elmah.io.

Including source code on log messages is available in the Elmah.Io.Client v4 package and forward.

Remove sensitive form data

The OnMessage event can be used to filter sensitive form data as well. In the following example, we remove the server variable named Secret-Key from all messages, before sending them to elmah.io.

services.AddElmahIo(options =>
{
    // ...
    options.OnMessage = msg =>
    {
        var item = msg.ServerVariables.FirstOrDefault(x => x.Key == "Secret-Key"); 
        if (item != null)
        {
            msg.ServerVariables.Remove(item);
        }
    };
});

Formatting exceptions

A default exception formatter is used to format any exceptions, before sending them off to the elmah.io API. To override the format of the details field in elmah.io, set a new IExceptionFormatter in the ExceptionFormatter property on the ElmahIoOptions object:

services.AddElmahIo(options =>
{
    // ...
    options.ExceptionFormatter = new DefaultExceptionFormatter();
}

Besides the default exception formatted (DefaultExceptionFormatter), Elmah.Io.AspNetCore comes with a formatter called YellowScreenOfDeathExceptionFormatter. This formatter, outputs an exception and its inner exceptions as a list of exceptions, much like on the ASP.NET yellow screen of death. If you want, implementing your own exception formatter, requires you to implement a single method.

Logging responses not throwing an exception

As default, uncaught exceptions (500's) and 404's are logged automatically. Let's say you have a controller returning a Bad Request and want to log that as well. Since returning a 400 from a controller doesn't trigger an exception, you will need to configure this status code:

services.AddElmahIo(options =>
{
    // ...
    options.HandledStatusCodesToLog = new List<int> { 400 };
}

The list can also be configured through appsettings.json:

{
  // ...
  "ElmahIo": {
    // ...
    "HandledStatusCodesToLog": [ 400 ],
  }
}

When configuring status codes through the appsettings.json file, 404s will always be logged. To avoid this, configure the list in C# as shown above.

Logging through a proxy

Since ASP.NET Core no longer support proxy configuration through web.config, you can log to elmah.io by configuring a proxy manually:

services.AddElmahIo(options =>
{
    // ...
    options.WebProxy = new System.Net.WebProxy("localhost", 8888);
}

In this example, the elmah.io client routes all traffic through http://localhost:8000.

ASP.NET Core 2.1 seems to have some problems when setting up authenticated proxies.

Logging health check results

Check out Logging heartbeats from ASP.NET Core for details.

This article was brought to you by the elmah.io team. elmah.io is the best error management system for .NET web applications. We monitor your website, alert you when errors start happening, and help you fix errors fast.

See how we can help you monitor your website for crashes Monitor your website