Serilog高級玩法之用Serilog記錄所選終結點附加屬性

這是該系列的第二篇文章：在ASP.NET Core 3.0中使用Serilog.AspNetCore。

1. 第1部分-使用Serilog RequestLogging來簡化ASP.NET Core的日誌輸出
2. 第2部分-用Serilog記錄所選終結點的附加屬性（本文）
3. 第3部分-使用Serilog.AspNetCore記錄MVC屬性[敬請期待]
4. 第4部分-從Serilog請求記錄中排除運行情況檢查端點[敬請期待]

做者：依樂祝

譯文地址：http://www.javashuo.com/article/p-bkvxdmfz-mg.html

原文地址：https://andrewlock.net/using-serilog-aspnetcore-in-asp-net-core-3-logging-the-selected-endpoint-name-with-serilog/

在個人上一篇文章中，我描述瞭如何配置Serilog的RequestLogging中間件爲每一個請求建立「摘要」日誌，以替換默認狀況下從ASP.NET Core獲取的10個或更多日誌。

在本文中，我將展現如何向Serilog的摘要請求日誌中添加其餘元數據，例如請求的主機名，響應的內容類型或從ASP.NET Core 3.0中使用的終結點路由中間件所選擇的端點名稱。

ASP.NET Core基礎結構日誌很詳細，可是默認狀況下具備太多詳細信息

正如我在上一篇文章(https://andrewlock.net/using-serilog-aspnetcore-in-asp-net-core-3-reducing-log-verbosity/)中所展現的那樣，在開發環境中，ASP.NET Core基礎架構將爲每個RazorPage處理程序生成10條日誌消息：

經過安裝了Serilog.AspNetCore的 NuGet包後並引入RequestLoggingMiddleware以後，能夠將其精簡爲一條日誌消息：

本文中使用的全部日誌圖片均來自一款優秀的爲結構化日誌提供可視化界面的工具-Seq

顯然，原始的日誌集更加冗長，而且其中大部分不是特別有用的信息。可是，若是您將原始的10條日誌做爲一個總體來看，則與Serilog摘要日誌相比，它們確實會在結構日誌模板中記錄一些其餘屬性。

由ASP.NET Core基礎結構記錄的而Serilog 未記錄的擴展內容包括（下面這些仍是英文的看着順眼）：

• Host (localhost:5001)
• Scheme (https)
• Protocol (HTTP/2)
• QueryString (test=true)
• EndpointName (/Index)
• HandlerName (OnGet/SerilogRequestLogging.Pages.IndexModel.OnGet)
• ActionId (1fbc88fa-42db-424f-b32b-c2d0994463f1)
• ActionName (/Index)
• RouteData ({page = "/Index"})
• ValidationState (True/False)
• ActionResult (PageResult)
• ContentType (text/html; charset=utf-8)

我認爲若是要把上述屬性中的其中一些包含在摘要日誌消息中，將很是有用。例如，若是您的應用程序綁定到多個主機名，那麼Host絕對是重要的日誌。QueryString多是另外一個有用的字段。EndpointName/ HandlerName，ActionId而且ActionName彷佛不那麼重要，由於您應該可以推斷出給定的請求路徑，可是顯式記錄它們將幫助您更加方便的捕獲錯誤，並使過濾針對特定操做的全部請求變得更加容易。

歸納地說，您能夠將這些屬性分爲兩類：

• 請求/響應特性：如Host，Scheme，ContentType，QueryString，EndpointName
• MVC / RazorPages相關的屬性：如HandlerName，ActionId，ActionResult等

在這篇文章中，我將展現如何添加這些類別中的第一種，即與請求/響應相關的屬性，在下一篇文章中，我將展現如何添加基於MVC / RazorPages的屬性。

向Serilog請求日誌添加擴展數據

在上一篇文章中，我展現瞭如何將Serilog請求日誌記錄添加到您的應用程序中，所以在此再也不贅述。如今，我假設您已經進行了設置，而且您擁有一個包含如下內容的Startup.Configure方法：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // ... Error handling/HTTPS middleware
    app.UseStaticFiles();

    app.UseSerilogRequestLogging(); // <-- Add this line

    app.UseRouting();
    app.UseAuthorization();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorPages();
    });
}

該UseSerilogRequestLogging()擴展方法將Serilog RequestLoggingMiddleware添加到請求管道中。您還能夠經過調用重載來配置RequestLoggingOptions的實例。此類具備幾個屬性，可讓您自定義請求記錄器如何生成日誌語句：

public class RequestLoggingOptions
{
    public string MessageTemplate { get; set; }
    public Func<HttpContext, double, Exception, LogEventLevel> GetLevel { get; set; }
    public Action<IDiagnosticContext, HttpContext> EnrichDiagnosticContext { get; set; }
}

該MessageTemplate屬性控制將日誌呈現爲的字符串格式，GetLevel容許您控制給定日誌索要記錄的級別，如 Debug/ Info/ Warning等。這裏咱們所關心的是EnrichDiagnosticContext屬性。

設置了該屬性的Action<>以後，在生成日誌消息時它將被Serilog中間件調用並執行。它在日誌寫入以前運行，這意味着它在中間件管道執行以後運行。例如，在下圖中（取自個人書《 ASP.NET Core in Action》），當響應「回傳」到中間件管道時，在第5步寫入日誌：

在管道處理以後寫入日誌這一事實意味着兩件事：

• 咱們能夠訪問Response的屬性，例如狀態碼，通過的時間或內容類型
• 咱們能夠訪問在管道後面設置的中間件的功能，例如，由EndpointRoutingMiddleware（經過UseRouting()添加的）設置的功能：IEndpointFeature

在下一部分中，我將提供一個幫助程序功能，該功能會將全部「缺乏」屬性添加到Serilog請求日誌消息中。

在IDiagnosticContext中設置擴展值

Serilog.AspNetCore會將接口IDiagnosticContext做爲單例添加到DI容器中，所以您能夠從任何類中訪問它。而後，您能夠調用Set()方法，將其餘屬性附加到請求日誌消息中。

例如，如文檔所示，您能夠從操做方法中添加任意值：

public class HomeController : Controller
{
    readonly IDiagnosticContext _diagnosticContext;
    public HomeController(IDiagnosticContext diagnosticContext)
    {
        _diagnosticContext = diagnosticContext;
    }

    public IActionResult Index()
    {
        // The request completion event will carry this property
        _diagnosticContext.Set("CatalogLoadTime", 1423);
        return View();
    }
}

而後，結果摘要日誌將包含屬性CatalogLoadTime。

RequestLoggingOptions經過設置所提供IDiagnosticContext實例的值，咱們基本上使用徹底相同的方法來定製中間件所使用的方法。下面的靜態幫助器類從當前HttpContext上下文檢索值，並在值可用時對其進行設置。
下面的靜態helper類從當前HttpContext檢索值，並在值可用時設置它們。

public static class LogHelper 
{
    public static void EnrichFromRequest(IDiagnosticContext diagnosticContext, HttpContext httpContext)
    {
        var request = httpContext.Request;

        // Set all the common properties available for every request
        diagnosticContext.Set("Host", request.Host);
        diagnosticContext.Set("Protocol", request.Protocol);
        diagnosticContext.Set("Scheme", request.Scheme);

        // Only set it if available. You're not sending sensitive data in a querystring right?!
        if(request.QueryString.HasValue)
        {
            diagnosticContext.Set("QueryString", request.QueryString.Value);
        }

        // Set the content-type of the Response at this point
        diagnosticContext.Set("ContentType", httpContext.Response.ContentType);

        // Retrieve the IEndpointFeature selected for the request
        var endpoint = httpContext.GetEndpoint();
        if (endpoint is object) // endpoint != null
        {
            diagnosticContext.Set("EndpointName", endpoint.DisplayName);
        }
    }
}

上面的幫助器函數從「Request」，「Response」以及其餘中間件（端點名稱）設置的功能中檢索值。您能夠擴展它，以根據須要在請求中添加其餘值。

您能夠在你的Startup.Configure()方法中經過調用UseSerilogRequestLogging的EnrichDiagnosticContext屬性，來註冊上面的幫助類：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // ... Other middleware

    app.UseSerilogRequestLogging(opts
        => opts.EnrichDiagnosticContext = LogHelper.EnrichFromRequest);

    // ... Other middleware
}

如今，當您發出請求時，您將看到添加到Serilog結構化日誌中的全部其餘屬性：

只要您具備經過當前HttpContext可供中間件管道使用的值，就可使用此方法。可是MVC的相關屬性是個例外，它們是MVC中間件「內部」的特性，例如action 名稱或RazorPage處理程序名稱。在下一篇文章中，我將展現如何將它們添加到Serilog請求日誌中。

總結

默認狀況下，用Serilog的請求日誌記錄中間件替換ASP.NET Core基礎結構日誌記錄時，與開發環境的默認日誌記錄配置相比，您會丟失一些信息。在本文中，我展現瞭如何經過自定義Serilog RequestLoggingOptions來添加這些附加屬性。

這樣的作法很是簡單-您能夠訪問HttpContext，所以你能夠檢索它包含的任何可用的值，並將它們設置爲IDiagnosticContext所提供的屬性。這些屬性將做爲附加屬性添加到Serilog生成的結構化日誌中。在下一篇文章中，我將展現如何將MVC特定的屬性值添加到請求日誌中。敬請期待吧！