Serilog.Exceptions.Grpc
8.4.0
Prefix Reserved
dotnet add package Serilog.Exceptions.Grpc --version 8.4.0
NuGet\Install-Package Serilog.Exceptions.Grpc -Version 8.4.0
<PackageReference Include="Serilog.Exceptions.Grpc" Version="8.4.0" />
paket add Serilog.Exceptions.Grpc --version 8.4.0
#r "nuget: Serilog.Exceptions.Grpc, 8.4.0"
// Install Serilog.Exceptions.Grpc as a Cake Addin #addin nuget:?package=Serilog.Exceptions.Grpc&version=8.4.0 // Install Serilog.Exceptions.Grpc as a Cake Tool #tool nuget:?package=Serilog.Exceptions.Grpc&version=8.4.0
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
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
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
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
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.
Serilog.Exceptions.Grpc
Add the Serilog.Exceptions.Grpc NuGet package to your project to avoid the reflection based destructurer for RpcException
when using Grpc.Net.Client:
Install-Package Serilog.Exceptions.Grpc
Add the RpcExceptionDestructurer
during setup:
.Enrich.WithExceptionDetails(new DestructuringOptionsBuilder()
.WithDefaultDestructurers()
.WithDestructurers(new[] { new RpcExceptionDestructurer() }))
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 implementingIExceptionPropertyFilter
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 | Mac | ||
Azure Pipelines | Windows | ||
Azure Pipelines | Overall | ||
GitHub Actions | Ubuntu, Mac & Windows | ||
AppVeyor | Ubuntu, Mac & Windows |
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 Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp1.0 was computed. netcoreapp1.1 was computed. netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard1.5 is compatible. netstandard1.6 was computed. netstandard2.0 is compatible. netstandard2.1 is compatible. |
.NET Framework | net461 was computed. net462 is compatible. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen30 was computed. tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETFramework 4.6.2
- Grpc.Core.Api (>= 2.47.0)
- Serilog.Exceptions (>= 8.4.0)
-
.NETStandard 1.5
- Grpc.Core.Api (>= 2.47.0)
- NETStandard.Library (>= 1.6.1)
- Serilog.Exceptions (>= 8.4.0)
-
.NETStandard 2.0
- Grpc.Core.Api (>= 2.47.0)
- Serilog.Exceptions (>= 8.4.0)
-
.NETStandard 2.1
- Grpc.Core.Api (>= 2.47.0)
- Serilog.Exceptions (>= 8.4.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
8.4.0 | 160,715 | 8/15/2022 |