Serilog.Exceptions 8.2.0 The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org. Prefix Reserved

.NET 5.0 .NET Standard 1.3 .NET Framework 4.6.1
This package has a SemVer 2.0.0 package version: 8.2.0+build.634.
Install-Package Serilog.Exceptions -Version 8.2.0
dotnet add package Serilog.Exceptions --version 8.2.0
<PackageReference Include="Serilog.Exceptions" Version="8.2.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Serilog.Exceptions --version 8.2.0
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
#r "nuget: Serilog.Exceptions, 8.2.0"
#r directive can be used in F# Interactive, C# scripting and .NET Interactive. Copy this into the interactive tool or source code of the script to reference the package.
// Install Serilog.Exceptions as a Cake Addin
#addin nuget:?package=Serilog.Exceptions&version=8.2.0

// Install Serilog.Exceptions as a Cake Tool
#tool nuget:?package=Serilog.Exceptions&version=8.2.0
The NuGet Team does not provide support for this client. Please contact its maintainers for support.

Serilog.Exceptions Banner

Serilog.Exceptions NuGet Package Serilog.Exceptions package in serilog-exceptions feed in Azure Artifacts Serilog.Exceptions NuGet Package Downloads Twitter URL Twitter Follow

Serilog.Exceptions is an add-on to Serilog to log exception details and custom properties that are not output in Exception.ToString().

What Does It Do?

Your JSON logs will now be supplemented with detailed exception information and even custom exception properties. Here is an example of what happens when you log a DbEntityValidationException from EntityFramework (This exception is notorious for having deeply nested custom properties which are not included in the .ToString()).

try
{
    ...
}
catch (DbEntityValidationException exception)
{
    logger.Error(exception, "Hello World");
}

The code above logs the following:

{
  "Timestamp": "2015-12-07T12:26:24.0557671+00:00",
  "Level": "Error",
  "MessageTemplate": "Hello World",
  "RenderedMessage": "Hello World",
  "Exception": "System.Data.Entity.Validation.DbEntityValidationException: Message",
  "Properties": {
    "ExceptionDetail": {
      "EntityValidationErrors": [
        {
          "Entry": null,
          "ValidationErrors": [
            {
              "PropertyName": "PropertyName",
              "ErrorMessage": "PropertyName is Required.",
              "Type": "System.Data.Entity.Validation.DbValidationError"
            }
          ],
          "IsValid": false,
          "Type": "System.Data.Entity.Validation.DbEntityValidationResult"
        }
      ],
      "Message": "Validation failed for one or more entities. See 'EntityValidationErrors' property for more details.",
      "Data": {},
      "InnerException": null,
      "TargetSite": null,
      "StackTrace": null,
      "HelpLink": null,
      "Source": null,
      "HResult": -2146232032,
      "Type": "System.Data.Entity.Validation.DbEntityValidationException"
    },
    "Source": "418169ff-e65f-456e-8b0d-42a0973c3577"
  }
}

Getting Started

Add the Serilog.Exceptions NuGet package to your project using the NuGet Package Manager or run the following command in the Package Console Window:

dotnet add package Serilog.Exceptions

When setting up your logger, add the WithExceptionDetails() line like so:

using Serilog;
using Serilog.Exceptions;

ILogger logger = new LoggerConfiguration()
    .Enrich.WithExceptionDetails()
    .WriteTo.RollingFile(
        new JsonFormatter(renderMessage: true), 
        @"C:\logs\log-{Date}.txt")    
    .CreateLogger();

Make sure that the sink's formatter outputs enriched properties. Serilog.Sinks.Console and many more do not do that by default. You may need to add {Properties:j} to your sink's format template. For example, configuration for console sink may look like that:

.WriteTo.Console(outputTemplate: "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] {Message:lj}{NewLine}{Exception} {Properties:j}")

JSON appSettings.json configuration

Alternatively to fluent configuration setting can be stored in application configuration using Serilog.Settings.Configuration:

{
  "Serilog": {
    "Using": [ "Serilog.Exceptions" ],
    "Enrich": [ "WithExceptionDetails" ],
    "WriteTo": [
      { "Name": "Console" }
    ]
  }
}

Performance

This library has custom code to deal with extra properties on most common exception types and only falls back to using reflection to get the extra information if the exception is not supported by Serilog.Exceptions internally. Reflection overhead is present but minimal, because all the expensive relection-based operations are done only once per exception-type.

Additional Destructurers

Serilog.Exceptions.SqlServer

Serilog.Exceptions.SqlServer NuGet Package Serilog.Exceptions.SqlServer package in serilog-exceptions feed in Azure Artifacts Serilog.Exceptions.SqlServer NuGet Package Downloads

Add the Serilog.Exceptions.SqlServer NuGet package to your project to avoid the reflection based destructurer for SqlException when using System.Data.SqlClient:

Install-Package Serilog.Exceptions.SqlServer

Add the SqlExceptionDestructurer during setup:

.Enrich.WithExceptionDetails(new DestructuringOptionsBuilder()
    .WithDefaultDestructurers()
    .WithDestructurers(new[] { new SqlExceptionDestructurer() }))

Serilog.Exceptions.MsSqlServer

Serilog.Exceptions.MsSqlServer NuGet Package Serilog.Exceptions.MsSqlServer package in serilog-exceptions feed in Azure Artifacts Serilog.Exceptions.MsSqlServer NuGet Package Downloads

Add the Serilog.Exceptions.MsSqlServer NuGet package to your project to avoid the reflection based destructurer for SqlException when using Microsoft.Data.SqlClient:

Install-Package Serilog.Exceptions.MsSqlServer

Add the SqlExceptionDestructurer during setup:

.Enrich.WithExceptionDetails(new DestructuringOptionsBuilder()
    .WithDefaultDestructurers()
    .WithDestructurers(new[] { new SqlExceptionDestructurer() }))

Serilog.Exceptions.EntityFrameworkCore

Serilog.Exceptions.EntityFrameworkCore NuGet Package Serilog.Exceptions.EntityFrameworkCore package in serilog-exceptions feed in Azure Artifacts Serilog.Exceptions.EntityFrameworkCore NuGet Package Downloads

WARNING: In versions of Serilog.Exceptions older than 8.0.0, if you are using EntityFrameworkCore with Serilog.Exceptions you must add this, otherwise in certain cases your entire database will be logged! This is because the exceptions in Entity Framework Core have properties that link to the entire database schema in them (See #100, aspnet/EntityFrameworkCore#15214). Newer versions of Serilog.Exceptions avoids this issue by preventing the destructure of properties that implement IQueryable preventing their execution.

Add the Serilog.Exceptions.EntityFrameworkCore NuGet package to your project when using EntityFrameworkCore in your project

Install-Package Serilog.Exceptions.EntityFrameworkCore

Add the DbUpdateExceptionDestructurer during setup:

.Enrich.WithExceptionDetails(new DestructuringOptionsBuilder()
    .WithDefaultDestructurers()
    .WithDestructurers(new[] { new DbUpdateExceptionDestructurer() }))

Serilog.Exceptions.Refit

Serilog.Exceptions.Refit NuGet Package Serilog.Exceptions.Refit package in serilog-exceptions feed in Azure Artifacts Serilog.Exceptions.Refit NuGet Package Downloads

Add the Serilog.Exceptions.Refit NuGet package to your project to provide detailed logging for the ApiException when using Refit:

Install-Package Serilog.Exceptions.Refit

Add the ApiExceptionDestructurer during setup:

.Enrich.WithExceptionDetails(new DestructuringOptionsBuilder()
    .WithDefaultDestructurers()
    .WithDestructurers(new[] { new ApiExceptionDestructurer() }))

Depending on your Serilog setup, common System.Exception properties may already be logged. To omit the logging of these properties, use the overloaded constructor as follows:

.Enrich.WithExceptionDetails(new DestructuringOptionsBuilder()
    .WithDefaultDestructurers()
    .WithDestructurers(new[] { new ApiExceptionDestructurer(destructureCommonExceptionProperties: false) }))

The default configuration logs the following properties of an ApiException:

  • Uri
  • StatusCode

In addition, the ApiException.Content property can be logged with the following setup:

.Enrich.WithExceptionDetails(new DestructuringOptionsBuilder()
    .WithDefaultDestructurers()
    .WithDestructurers(new[] { new ApiExceptionDestructurer(destructureHttpContent: true) }))

Be careful with this option as the HTTP body could be very large and/or contain sensitive information.

Custom Exception Destructurers

You may want to add support for destructuring your own exceptions without relying on reflection. To do this, create your own destructuring class implementing ExceptionDestructurer (You can take a look at this for ArgumentException), then simply add it like so:

.Enrich.WithExceptionDetails(new DestructuringOptionsBuilder()
    .WithDefaultDestructurers()
    .WithDestructurers(new[] { new MyCustomExceptionDestructurer() }))

If you write a destructurer that is not included in this project (even for a third party library), please contribute it.

Additional configuration

You can configure some additional properties of destructuring process, by passing custom destructuring options during setup:

.Enrich.WithExceptionDetails(new DestructuringOptionsBuilder()
    .WithDefaultDestructurers()
    .WithRootName("Exception"))

Currently following options are supported:

  • RootName: The property name which will hold destructured exception, ExceptionDetail by default.
  • Filter: The object implementing IExceptionPropertyFilter that will have a chance to filter properties just before they are put in destructured exception object. Go to "Filtering properties" section for details.
  • DestructuringDepth: The maximum depth of reflection based recursive destructuring process.
  • ReflectionBasedDestructurer: Reflection based destructurer is enabled by default, but can be disabled in case you want to have complete control over destructuring process. You will have to register destructurers for all exceptions explicitly.

Filtering properties

You may want to skip some properties of all or part your exception classes without directly creating or modifying custom destructurers. Serilog.Exceptions supports this functionality using a filter.

Most typical use case is the need to skip StackTrace and TargetSite. Serilog is already reporting them so you may want Serilog.Exceptions to skip them to save space and processing time. To do that you just need to modify a line in configuration:

.Enrich.WithExceptionDetails(new DestructuringOptionsBuilder().WithFilter(someFilter));

Filtering for other scenarios is also supported:

  • Use WithIgnoreStackTraceAndTargetSiteExceptionFilter if you need to filter some other set of named properties
  • Implement custom IExceptionPropertyFilter if you need some different filtering logic
  • Use CompositeExceptionPropertyFilter to combine multiple filters

Continuous Integration

Name Operating System Status History
Azure Pipelines Ubuntu Azure Pipelines Ubuntu Build Status
Azure Pipelines Mac Azure Pipelines Mac Build Status
Azure Pipelines Windows Azure Pipelines Windows Build Status
Azure Pipelines Overall Azure Pipelines Overall Build Status Azure DevOps Build History
GitHub Actions Ubuntu, Mac & Windows GitHub Actions Status GitHub Actions Build History
AppVeyor Ubuntu, Mac & Windows AppVeyor Build Status AppVeyor Build History

Contributions and Thanks

Please view the contributing guide for more information.

  • 304NotModified - Added Markdown syntax highlighting.
  • joelweiss - Added Entity Framework Core destructurers.
  • krajek & JeroenDragt - For adding filters to help ignore exception properties you don't want logged.
  • krajek - For helping with cyclic dependencies when using the reflection destructurer.
  • mraming - For logging properties that throw exceptions.
  • optical - For a huge VS 2017 upgrade PR.
  • Jérémie Bertrand - For making Serilog.Exceptions compatible with Mono.
  • krajek - For writing some much needed unit tests.
Product Versions
.NET net5.0 net5.0-windows net6.0 net6.0-android net6.0-ios net6.0-maccatalyst net6.0-macos net6.0-tvos net6.0-windows
.NET Core netcoreapp1.0 netcoreapp1.1 netcoreapp2.0 netcoreapp2.1 netcoreapp2.2 netcoreapp3.0 netcoreapp3.1
.NET Standard netstandard1.3 netstandard1.4 netstandard1.5 netstandard1.6 netstandard2.0 netstandard2.1
.NET Framework net46 net461 net462 net463 net47 net471 net472 net48
MonoAndroid monoandroid
MonoMac monomac
MonoTouch monotouch
Tizen tizen30 tizen40 tizen60
Universal Windows Platform uap uap10.0
Xamarin.iOS xamarinios
Xamarin.Mac xamarinmac
Xamarin.TVOS xamarintvos
Xamarin.WatchOS xamarinwatchos
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (143)

Showing the top 5 NuGet packages that depend on Serilog.Exceptions:

Package Downloads
Serilog.Exceptions.EntityFrameworkCore The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

Log exception details and custom properties that are not output in Exception.ToString(). Contains custom destructurers for Entity Framework Core exceptions.

Sitko.Core.App

Sitko.Core is a set of libraries to help build .NET Core applications fast

Serilog.Exceptions.SqlServer The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

Log exception details and custom properties that are not output in Exception.ToString(). Contains custom destructurers for SQL Server exceptions.

BioEngine.BRC.Domain

Package Description

BumperLane.Tenant.Api.Framework

Framework for BumperLane API sites

GitHub repositories (22)

Showing the top 5 popular GitHub repositories that depend on Serilog.Exceptions:

Repository Stars
Dotnet-Boxed/Templates
.NET project templates with batteries included, providing the minimum amount of code required to get you going faster.
Belphemur/SoundSwitch
C# application to switch default playing device. Download: https://soundswitch.aaflalo.me/
Bililive/BililiveRecorder
B站录播姬 | BiliBili Stream Recorder | 哔哩哔哩直播录制
phongnguyend/Practical.CleanArchitecture
Asp.Net Core 6 Clean Architecture (Microservices, Modular Monolith, Monolith) samples (+Blazor, Angular 13, React 17, Vue 2.6), Domain-Driven Design, CQRS, Event Sourcing, SOLID, Asp.Net Core Identity Custom Storage, Identity Server 4 Admin UI, Entity Framework Core, Selenium E2E Testing, SignalR, Hosted Services, Health Checks, Security Headers, ...
reactiveui/splat
Makes things cross-platform
Version Downloads Last updated
8.2.0 872 5/20/2022
8.1.0 621,551 2/19/2022
8.0.0 1,444,046 11/9/2021
7.1.0 726,127 9/28/2021
7.0.0 2,207,932 6/15/2021
6.1.0 3,012,070 3/12/2021
6.0.0 2,413,460 11/18/2020
5.7.0 808,995 11/3/2020
5.6.0 3,055,304 7/9/2020
5.5.0 914,125 6/2/2020
5.4.0 4,052,031 12/26/2019
5.3.1 3,340,351 7/11/2019
5.3.0 189,251 6/26/2019
5.2.0 58,637 6/22/2019
5.0.0 2,489,376 12/27/2018
4.1.0 2,046,916 5/1/2018
4.0.0 874,606 2/11/2018
3.0.0 159,568 11/17/2017
2.5.0 143,731 8/21/2017
2.4.1 335,718 5/13/2017
2.4.0 188,295 2/7/2017
2.3.0 101,423 1/30/2017
2.2.1 187,027 9/18/2016
2.2.0 2,221 9/7/2016
2.0.1 29,378 9/3/2016
2.0.0 19,551 6/28/2016
2.0.0-rc 835 6/17/2016
2.0.0-build0009 815 9/2/2016
2.0.0-build0008 793 8/22/2016
2.0.0-beta0007 800 8/22/2016
1.2.0 14,591 5/19/2016
1.1.0 54,160 2/5/2016
1.0.1 2,084 12/7/2015
1.0.0 2,022 12/7/2015