在 ASP.NET Core 中使用 Serilog/Fluentd 將日志寫(xiě)入 Elasticsearch
本文轉(zhuǎn)載自微信公眾號(hào)「DotNET技術(shù)圈」，作者Andrew Lock 。轉(zhuǎn)載本文請(qǐng)聯(lián)系DotNET技術(shù)圈公眾號(hào)。
原文來(lái)自：https://andrewlock.net/writing-logs-to-elasticsearch-with-fluentd-using-serilog-in-asp-net-core/
對(duì)于在 Kubernetes 中運(yùn)行的應(yīng)用程序，將日志消息存儲(chǔ)在一個(gè)中心位置尤為重要。我認(rèn)為這對(duì)所有應(yīng)用程序都很重要，無(wú)論您使用的是 Kubernetes 還是 docker，但 pod 和容器的短暫性質(zhì)使得后一種情況特別重要。
如果您沒(méi)有集中存儲(chǔ)容器中的日志，那么如果容器崩潰并重新啟動(dòng)，日志可能會(huì)永遠(yuǎn)丟失。
有很多方法可以實(shí)現(xiàn)這一目標(biāo)。您可以直接從您的應(yīng)用程序登錄Elasticsearch或Seq，或者登錄到Elmah.io等外部服務(wù)。一種常見(jiàn)的方法是使用 Fluentd 從容器的控制臺(tái)輸出中收集日志，并將這些日志通過(guò)管道傳輸?shù)?Elasticsearch 集群。
默認(rèn)情況下，ASP.NET Core 中的控制臺(tái)日志輸出格式為人類(lèi)可讀格式。如果您采用 Fluentd/Elasticsearch 方法，您需要確保您的控制臺(tái)輸出采用 Elasticsearch 可以理解的結(jié)構(gòu)化格式，即 JSON。
在這篇文章中，我描述了如何將 Serilog 添加到 ASP.NET Core 應(yīng)用程序，以及如何自定義 Serilog 控制臺(tái)接收器的輸出格式，以便您可以使用 Fluentd 將控制臺(tái)輸出通過(guò)管道傳輸?shù)?Elasticsearch。
請(qǐng)注意，也可以將 Serilog 配置為使用Elasticsearch sink直接寫(xiě)入Elasticsearch。如果您沒(méi)有使用 Fluentd，或者沒(méi)有將您的應(yīng)用程序容器化，那么這是一個(gè)不錯(cuò)的選擇。
將日志寫(xiě)入控制臺(tái)輸出
當(dāng)您從模板創(chuàng)建新的 ASP.NET Core 應(yīng)用程序時(shí)，您的程序文件將如下所示(至少在 .NET Core 2.1 中)：
- public class Program
- {
- public static void Main(string[] args)
- {
- CreateWebHostBuilder(args).Build().Run();
- }
- public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
- WebHost.CreateDefaultBuilder(args)
- .UseStartup<Startup>();
- }
靜態(tài)輔助方法WebHost.CreateDefaultBuilder(args)創(chuàng)建一個(gè)WebHostBuilder并連接許多標(biāo)準(zhǔn)配置選項(xiàng)[1]。默認(rèn)情況下，它配置控制臺(tái)和調(diào)試記錄器提供程序：
- .ConfigureLogging((hostingContext, logging) =>
- {
- logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
- logging.AddConsole();
- logging.AddDebug();
- })
如果您從命令行使用 運(yùn)行您的應(yīng)用程序dotnet run，您將在控制臺(tái)中看到每個(gè)請(qǐng)求的日志。下面顯示了來(lái)自瀏覽器的兩個(gè)請(qǐng)求生成的日志 - 一個(gè)用于主頁(yè)，另一個(gè)用于 favicon.ico。
使用默認(rèn)控制臺(tái)記錄器的控制臺(tái)輸出
不幸的是，控制臺(tái)記錄器在如何寫(xiě)入日志方面沒(méi)有提供很大的靈活性。您可以選擇包含 scopes或禁用顏色，但僅此而已。
ASP.NET Core 中默認(rèn)Microsoft.Extensions.Logging基礎(chǔ)結(jié)構(gòu)的替代方法是使用 Serilog進(jìn)行日志記錄，并將其作為標(biāo)準(zhǔn) ASP.NET Core 記錄器進(jìn)行連接。
將 Serilog 添加到 ASP.NET Core 應(yīng)用程序
Serilog是一個(gè)成熟的開(kāi)源項(xiàng)目，早于 ASP.NET Core 中的所有日志記錄基礎(chǔ)結(jié)構(gòu)。在許多方面，ASP.NET Core 日志記錄基礎(chǔ)結(jié)構(gòu)似乎以 Serilog 為模型：Serilog 具有類(lèi)似的配置選項(xiàng)和可插拔的“接收器”來(lái)控制寫(xiě)入日志的位置。
開(kāi)始使用 Serilog 的最簡(jiǎn)單方法是使用Serilog.AspNetCore NuGet 包。使用以下命令將其添加到您的應(yīng)用程序中：
- dotnet add package Serilog.AspNetCore
您還需要添加一個(gè)或多個(gè)“sink”包，以控制日志的寫(xiě)入位置。在這種情況下，我將安裝控制臺(tái)接收器，但如果您想一次寫(xiě)入多個(gè)目的地，您也可以添加其他接收器。
- dotnet add package Serilog.Sinks.Console
Serilog.AspNetCore 包UseSerilog()在WebHostBuilder實(shí)例上提供了一個(gè)擴(kuò)展方法。這用ILoggerFactorySerilog 的實(shí)現(xiàn)替換了默認(rèn)值。您可以傳入現(xiàn)有Serilog.ILogger實(shí)例，也可以?xún)?nèi)聯(lián)配置記錄器。例如，以下代碼配置將寫(xiě)入的最低日志級(jí)別 ( info) 并注冊(cè)控制臺(tái)接收器：
- public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
- WebHost.CreateDefaultBuilder(args)
- .UseSerilog((ctx, config) =>
- {
- config
- .MinimumLevel.Information()
- .Enrich.FromLogContext()
- .WriteTo.Console();
- })
- .UseStartup<Startup>();
- }
當(dāng)您使用 Serilog 而不是默認(rèn)記錄器時(shí)再次運(yùn)行應(yīng)用程序會(huì)提供以下控制臺(tái)輸出：
使用 Serilog 而不是默認(rèn)的控制臺(tái)記錄器的控制臺(tái)輸出
輸出類(lèi)似于默認(rèn)記錄器，但重要的是它是非?？膳渲玫?。您可以隨意更改輸出模板。例如，您可以通過(guò)包含SourceContext參數(shù)來(lái)顯示生成日志的類(lèi)的名稱(chēng)。
有關(guān) Serilog.AspNetCore 包的更多詳細(xì)信息和示例，請(qǐng)參閱 GitHub 存儲(chǔ)庫(kù)[2]。有關(guān)控制臺(tái)格式選項(xiàng)，請(qǐng)參閱Serilog.Sinks.Console 存儲(chǔ)庫(kù)[3]。
除了對(duì)輸出模板的簡(jiǎn)單更改外，控制臺(tái)接收器還允許完全控制消息的呈現(xiàn)方式。我們將使用該功能將日志呈現(xiàn)為 Fluentd 的 JSON，而不是人性化的格式。
自定義Serilog Console Sink的輸出格式寫(xiě)入JSON
要更改數(shù)據(jù)的呈現(xiàn)方式，您可以添加自定義ITextFormatter. Serilog 包含一個(gè)JsonFormatter您可以使用的，但建議您考慮使用Serilog.Formatting.Compact包[4]：
“CompactJsonFormatter與 Serilog 的默認(rèn)值相比，大大減少了小日志事件的字節(jié)數(shù)JsonFormatter，同時(shí)保持人類(lèi)可讀。它通過(guò)更短的內(nèi)置屬性名稱(chēng)、更精簡(jiǎn)的格式以及排除冗余信息來(lái)實(shí)現(xiàn)這一點(diǎn)。”
我們不會(huì)將這個(gè)包用于我們的 Fluentd/Elasticsearch 用例，但我將展示如何在任何情況下插入它。使用 添加包dotnet add package Serilog.Formatting.Compact，創(chuàng)建格式化程序的新實(shí)例，并將其傳遞給調(diào)用中的WriteTo.Console()方法UseSerilog()：
- .UseSerilog((ctx, config) =>
- {
- config
- .MinimumLevel.Information()
- .Enrich.FromLogContext()
- .WriteTo.Console(new CompactJsonFormatter());
- })
現(xiàn)在，如果您運(yùn)行您的應(yīng)用程序，您將看到以 JSON 格式寫(xiě)入控制臺(tái)的日志：
使用 CompactJsonFormatter 以 JSON 格式寫(xiě)入控制臺(tái)的日志圖像
這個(gè)格式化程序可能對(duì)您有用，但就我而言，我希望編寫(xiě) JSON 以便 Elasticsearch 能夠理解它。您可以看到緊湊的 JSON 格式(在下面打印得很漂亮)，正如承諾的那樣，為時(shí)間戳 ( @t)、消息模板 ( @mt) 和呈現(xiàn)的消息 ( @r)使用了緊湊的名稱(chēng)：
- {
- "@t": "2018-05-17T10:23:47.0727764Z",
- "@mt": "{HostingRequestStartingLog:l}",
- "@r": [
- "Request starting HTTP\/1.1 GET http:\/\/localhost:5000\/ "
- ],
- "Protocol": "HTTP\/1.1",
- "Method": "GET",
- "ContentType": null,
- "ContentLength": null,
- "Scheme": "http",
- "Host": "localhost:5000",
- "PathBase": "",
- "Path": "\/",
- "QueryString": "",
- "HostingRequestStartingLog": "Request starting HTTP\/1.1 GET http:\/\/localhost:5000\/ ",
- "EventId": {
- "Id": 1
- },
- "SourceContext": "Microsoft.AspNetCore.Hosting.Internal.WebHost",
- "RequestId": "0HLDRS135F8A6:00000001",
- "RequestPath": "\/",
- "CorrelationId": null,
- "ConnectionId": "0HLDRS135F8A6"
- }
對(duì)于最簡(jiǎn)單的 Fluentd/Elasticsearch 集成，我希望使用標(biāo)準(zhǔn) Elasticsearch 名稱(chēng)(例如@timestamp時(shí)間戳)輸出 JSON 。幸運(yùn)的是，所需要的只是更換格式化程序。
使用與 Elasticsearch 兼容的 JSON 格式化程序
該Serilog.Sinks.Elasticsearch包包含正是我們所需要的格式ElasticsearchJsonFormatter。這使用標(biāo)準(zhǔn) Elasticsearch 字段(如@timestamp和 )呈現(xiàn)數(shù)據(jù)fields。
不幸的是，目前除了復(fù)制和粘貼源代碼首先檢查許可證之外，將格式化程序添加到您的項(xiàng)目的唯一方法是安裝整個(gè)Serilog.Sinks.Elasticsearch包，它有很多依賴(lài)項(xiàng)。
理想情況下，我希望將格式化程序視為它自己的獨(dú)立包，就像Serilog.Formatting.Compac一我提出了一個(gè)問(wèn)題[5]如果這對(duì)您來(lái)說(shuō)不是問(wèn)題(這對(duì)我來(lái)說(shuō)不是問(wèn)題，因?yàn)槲乙呀?jīng)依賴(lài)Elasticsearch.Net，那么添加 Elasticsearch Sink 來(lái)訪問(wèn)格式化程序是最簡(jiǎn)單的解決方案。使用添加接收器dotnet add package Serilog.Sinks.ElasticSearch，并更新您的 Serilog 配置使用ElasticsearchJsonFormatter：
- .UseSerilog((ctx, config) =>
- {
- config
- .MinimumLevel.Information()
- .Enrich.FromLogContext()
- .WriteTo.Console(new ElasticsearchJsonFormatter();
- })
連接此格式化程序后，控制臺(tái)輸出將包含常見(jiàn)的 Elasticsearch 字段，如@timestamp，如下面(漂亮打印)輸出所示：
- { "@timestamp": "2018-05-17T22:31:43.9143984+12:00", "level": "Information", "messageTemplate": "{HostingRequestStartingLog:l}", "message": "Request starting HTTP\/1.1 GET http:\/\/localhost:5000\/ ", "fields": { "Protocol": "HTTP\/1.1", "Method": "GET", "ContentType": null, "ContentLength": null, "Scheme": "http", "Host": "localhost:5000", "PathBase": "", "Path": "\/", "QueryString": "", "HostingRequestStartingLog": "Request starting HTTP\/1.1 GET http:\/\/localhost:5000\/ ", "EventId": { "Id": 1 }, "SourceContext": "Microsoft.AspNetCore.Hosting.Internal.WebHost", "RequestId": "0HLDRS5H8TSM4:00000001", "RequestPath": "\/", "CorrelationId": null, "ConnectionId": "0HLDRS5H8TSM4" }, "renderings": { "HostingRequestStartingLog": [ { "Format": "l", "Rendering": "Request starting HTTP\/1.1 GET http:\/\/localhost:5000\/ " } ] }}
現(xiàn)在日志以一種可以直接從 Fluentd 傳輸?shù)?Elasticsearch 的格式呈現(xiàn)。我們可以只寫(xiě)到控制臺(tái)。
根據(jù)托管環(huán)境在輸出格式化程序之間切換
最后的提示。如果您想在本地開(kāi)發(fā)時(shí)獲得人類(lèi)可讀的控制臺(tái)輸出，并且只在 Staging 或 Production 中使用 JSON 格式化程序怎么辦?
這很容易實(shí)現(xiàn)，因?yàn)閁seSerilog擴(kuò)展提供了IHostingEnvironment通過(guò)WebHostBuilderContext. 例如，在以下代碼段中，我將應(yīng)用程序配置為在開(kāi)發(fā)中使用人類(lèi)可讀的控制臺(tái)，并在其他環(huán)境中使用 JSON 格式化程序。
- .UseSerilog((ctx, config) =>
- {
- config
- .MinimumLevel.Information()
- .Enrich.FromLogContext();
- if (ctx.HostingEnvironment.IsDevelopment())
- {
- config.WriteTo.Console();
- }
- else
- {
- config.WriteTo.Console(new ElasticsearchJsonFormatter());
- }
- })
除了環(huán)境之外，您還可以根據(jù)通過(guò)IConfiguration對(duì)象 at提供的配置值進(jìn)行切換ctx.Configuration。
概括
將日志存儲(chǔ)在一個(gè)中心位置很重要，尤其是在您構(gòu)建容器化應(yīng)用程序時(shí)。一種可能的解決方案是將日志輸出到控制臺(tái)，讓 Fluentd 監(jiān)控控制臺(tái)，并將輸出通過(guò)管道傳輸?shù)?Elasticsearch 集群。在這篇文章中，我描述了如何將 Serilog 日志記錄添加到您的 ASP.NET Core 應(yīng)用程序并將其配置為以 Elasticsearch 期望的 JSON 格式將日志寫(xiě)入控制臺(tái)。
References
[1] 連接許多標(biāo)準(zhǔn)配置選項(xiàng): https://github.com/aspnet/MetaPackages/blob/2.1.0-rc1-final/src/Microsoft.AspNetCore/WebHost.cs#L150
[2] 請(qǐng)參閱 GitHub 存儲(chǔ)庫(kù): https://github.com/serilog/serilog-aspnetcore
[3] Serilog.Sinks.Console 存儲(chǔ)庫(kù): https://github.com/serilog/serilog-sinks-console
[4] 考慮使用Serilog.Formatting.Compact包: https://github.com/serilog/serilog-formatting-compact
[5] 我提出了一個(gè)問(wèn)題: https://github.com/serilog/serilog-sinks-elasticsearch/issues/176
