Serilog.Exceptions.Grpc 8.4.0

Serilog.Exceptions 是 Serilog 的插件，用于记录异常细节和自定义属性，这些属性在 Exception.ToString() 中未输出。

这能做什么？

您的JSON日志现在将补充详细的异常信息和自定义异常属性。以下是一个示例，展示了当您从EntityFramework（此类异常以深入嵌套的自定义属性而闻名，这些属性不包括在.ToString()中）中记录一个DbEntityValidationException时会发生什么。

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

上面的代码记录了以下内容

{
  "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"
  }
}

入门指南

使用NuGet包管理器或运行以下命令将Serilog.Exceptions NuGet包添加到您的项目

dotnet add package Serilog.Exceptions

在设置日志记录器时，添加类似以下格式的WithExceptionDetails()行

using Serilog;
using Serilog.Exceptions;

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

确保托管的格式化程序输出富属性。《代码>Serilog.Sinks.Console以及许多其他默认情况下不会这样做。您可能需要将{Properties:j}添加到托管的格式化程序模板中。例如，控制台托管的配置可能如下所示

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

JSON appSettings.json 配置

除了流畅配置设置之外，还可以使用Serilog.Settings.Configuration将配置存储在应用程序配置中

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

性能

这个库具有处理大多数常见异常类型额外属性的专用代码，并且只有在异常不支持Serilog.exceptions内部时才会回落到使用反射来获取额外信息。由于所有昂贵的基于反射的操作都只对每个异常类型执行一次，所以反射开销存在，但最小。

额外的拆分器

Serilog.Exceptions.SqlServer

将Serilog.Exceptions.SqlServer NuGet包添加到您的项目中，以避免使用System.Data.SqlClient时使用基于反射的拆分器

Install-Package Serilog.Exceptions.SqlServer

在设置期间添加SqlExceptionDestructurer

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

Serilog.Exceptions.MsSqlServer

将Serilog.Exceptions.MsSqlServer NuGet包添加到您的项目中，以避免使用Microsoft.Data.SqlClient时使用基于反射的拆分器

Install-Package Serilog.Exceptions.MsSqlServer

在设置期间添加SqlExceptionDestructurer

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

Serilog.Exceptions.EntityFrameworkCore

警告：在Serilog.Exceptions的旧版本（小于8.0.0）中，如果您使用EntityFrameworkCore与Serilog.exceptions，则必须添加此内容，否则在某些情况下，您的整个数据库将被记录！这是因为Entity Framework Core中的异常具有链接到整个数据库模式的自定义属性（请参见#100，aspnet/EntityFrameworkCore#15214）。Serilog.exceptions的新版本通过防止执行实现IQueryable的属性，从而避免此问题。

当在您的项目中使用EntityFrameworkCore时，将Serilog.Exce closesions.EntityFrameworkCore NuGet包添加到您的项目中

Install-Package Serilog.Exceptions.EntityFrameworkCore

在设置期间添加DbUpdateExceptionDestructurer

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

Serilog.Exce closesions.Refit

将Serilog.Exce closesions.Refit NuGet包添加到您的项目中，提供使用Refit时的ApiException详细记录

Install-Package Serilog.Exceptions.Refit

在设置期间添加ApiExceptionDestructurer

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

根据您的Serilog设置，常见的System.Exception属性可能已记录。要省略这些属性的记录，请按照以下方式使用重载的构造函数

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

默认配置记录以下ApiException属性

• Uri
• StatusCode

另外，可以使用以下设置记录ApiException.Content属性

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

请注意此选项，因为HTTP体可能非常大，或者包含敏感信息。

Serilog.Exceptions.Grpc

将Serilog.Exceptions.Grpc NuGet包添加到您的项目中，以避免在使用Grpc.Net.Client时基于反射的解除构造过程。

Install-Package Serilog.Exceptions.Grpc

在设置过程中添加

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

自定义异常解除构造器

您可能想在不依赖反射的情况下添加对自定义异常的解除构造支持。为此，创建自己的解除构造类实现ExceptionDestructurer（您可以查看此处的ArgumentException），然后简单地按如下方式添加它

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

如果您编写了一个不在项目中包含的解除构造器（即使是第三方库），请贡献它。

附加配置

您可以通过在设置过程中传递自定义解除构造选项，来配置分解过程的某些附加属性。

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

目前支持以下选项

• RootName：将保存分解异常的属性名称，默认为《ExceptionDetail》。
• Filter：实现IExceptionPropertyFilter的对象，它将有机会在将属性放入分解后的异常对象之前过滤属性。有关详细信息，请参阅“过滤属性”部分。
• DestructuringDepth：基于反射的递归分解过程的最大深度。
• ReflectionBasedDestructurer：默认情况下启用基于反射的分解，但如果您想对分解过程有完全控制，可以禁用。您将必须显式为所有异常注册分解器。

过滤属性

您可能想跳过所有或部分异常类的某些属性，而不直接创建或修改自定义解除构造器。Serilog.Exceptions支持此功能，使用过滤器。

最常见的用例是需要跳过《StackTrace》和《TargetSite》。Serilog已经报告了它们，因此您可能希望Serilog.Exceptions跳过以节省空间和处理时间。为此，您只需要修改配置中的一行

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

支持过滤其他方案

• 如果您需要过滤其他命名属性集，请使用《WithIgnoreStackTraceAndTargetSiteExceptionFilter》
• 实现自定义《IExceptionPropertyFilter》以获取不同的过滤逻辑
• 使用《CompositeExceptionPropertyFilter》来组合多个过滤器

持续集成

名称	操作系统	状态	历史记录
Azure Pipelines	Ubuntu
Azure Pipelines	Mac
Azure Pipelines	Windows
Azure Pipelines	总体
GitHub Actions	Ubuntu, Mac 及 Windows
AppVeyor	Ubuntu, Mac 及 Windows

贡献与感谢

请查看贡献指南以获取更多信息。

• 304NotModified - 添加了Markdown语法高亮。
• joelweiss - 添加了Entity Framework Core分解器。
• krajek 及 JeroenDragt - 添加过滤器以帮助忽略不希望记录的异常属性。
• krajek - 在使用反射分解器时帮助解决循环依赖。
• mraming - 为记录抛出异常的属性提供帮助。
• optical - 为VS 2017的重大升级PR做出贡献。
• Jérémie Bertrand - 使 Serilog.Exceptions 与 Mono 兼容。
• krajek - 编写了急需的单元测试。