Serilog.Sinks.Elasticsearch 10.0.0

Serilog.Sinks.Elasticsearch

此存储库包含两个 nuget 包：Serilog.Sinks.Elasticsearch 和 Serilog.Formatting.Elasticsearch。

提醒一下，@elastic 的 .NET 团队创建了自己的新型 Serilog Sink，名为 Elastic.Serilog.Sinks（包名：[Elastic.Serilog.Sinks](https://nuget.net.cn/packages/Elastic.Serilog.Sinks#readme-body-tab)，文档：[Elastic.Serilog.Sinks 文档](https://elastic.ac.cn/guide/en/ecs-logging/dotnet/current/serilog-data-shipper.html)）。尽管当前的 Sink 仍然可以使用，但建议先查看官方的 Elastic 实现，因为它支持更好且更新更及时。

目录

• 这个 Sink 是什么
• 特性
• 快速入门
  • Elasticsearch Sink
  • Elasticsearch 格式化器
• 更多信息
  • 有关 Elasticsearch 中字段的说明
  • 有关 Kibana 的说明
  • appsettings.json JSON 配置
  • 错误处理
  • 重大变更

这个 Sink 是什么

Serilog Elasticsearch Sink 项目是为 Serilog 日志框架设计的 Sink（本质上是一个写程序）。结构化日志事件被写入 Sink，每个 Sink 负责将其写入自己的后端、数据库、存储等。这个 Sink 将数据传输到 Elasticsearch，一个 NoSQL 搜索引擎。它以与 Logstash 类似的方式完成，这使得使用 Kibana 来可视化日志变得容易。

特性

• 简化配置以将日志事件发布到 Elasticsearch。只需服务器地址即可。
• 所有属性都存储在 ES 中的字段里。这允许你查询所有相关数据，还可以运行此数据上的分析。
• 能够自定义存储；指定使用的索引名称、序列化器或与服务器的连接（负载均衡）。
• 持久模式；在将事件传输到 ES 之前首先在磁盘上存储日志事件，确保即使在连接到你的 ES 集群时出现问题也不会丢失事件。
• 自动为 ES 中日志事件的最佳使用情况创建正确的映射，或自动上传自己的自定义映射。
• 从版本 3 开始，兼容 Elasticsearch 2。
• 6.x 版本支持新的 Elasticsearch.net 6.x 库。
• 从 8.x 版本开始，支持 Elasticsearch.net 7 版本。
• 从 9.x 版本开始，支持 Elasticsearch.net 8。默认启用版本检测，在这种情况下，TypeName 在 6、7 和 8 的大版本之间自动处理。不再支持 Elasticsearch 的 2 和 5 版本。此 Sink 的 9.0.0 版本针对 netstandard2.0，因此可以在支持它的任何 .NET Framework 中运行（包括 .NET Core 和 .NET Framework），但我们专注于使用 .NET 6.0 进行测试，以便简化维护。

快速入门

Elasticsearch Sink

Install-Package serilog.sinks.elasticsearch

使用默认配置注册此 Sink 简单易懂

var loggerConfig = new LoggerConfiguration()
    .WriteTo.Elasticsearch(new ElasticsearchSinkOptions(new Uri("https://127.0.0.1:9200")));

或者，如果你在使用 .NET Core 和 Serilog.Settings.Configuration Nuget 包以及 appsettings.json，则默认配置如下所示

{
  "Serilog": {
    "Using": [ "Serilog.Sinks.Elasticsearch" ],
    "MinimumLevel": "Warning",
    "WriteTo": [
      {
        "Name": "Elasticsearch",
        "Args": {
          "nodeUris": "https://127.0.0.1:9200"
        }
      }
    ]
  }
}

更复杂的配置，使用额外的 Nuget 包（例如 Serilog.Enrichers.Environment）如下所示

{
  "Serilog": {
    "Using": [ "Serilog.Sinks.Elasticsearch" ],
    "MinimumLevel": "Warning",
    "WriteTo": [
      {
        "Name": "Elasticsearch",
        "Args": {
          "nodeUris": "https://127.0.0.1:9200"
        }
      }
    ],
    "Enrich": [ "FromLogContext", "WithMachineName" ],
    "Properties": {
      "Application": "My app"
    }
  }
}

采用这种方式，Sink 将检测 Elasticsearch 服务器版本（《DetectElasticsearchVersion》默认设置为 true）并正确处理 TypeName 的行为，根据服务器版本 (6.x、7.x 或 8.x)。

禁用 Elasticsearch 服务器版本的检测

或者，可以将 DetectElasticsearchVersion 设置为 false 并手动设置某些选项。在这种情况下，Sink 将假定 Elasticsearch 版本为 7，但选项将因为潜在的版本不兼容而忽略。

例如，你可以配置 Sink 强制注册 v6 索引模板。请注意，AutoRegisterTemplate 选项将不会覆盖现有的模板。

var loggerConfig = new LoggerConfiguration()
    .WriteTo.Elasticsearch(new ElasticsearchSinkOptions(new Uri("https://127.0.0.1:9200") ){
             DetectElasticsearchVersion = false,
             AutoRegisterTemplate = true,
             AutoRegisterTemplateVersion = AutoRegisterTemplateVersion.ESv6
     });

可配置属性

除了在代码中注册 Sink 之外，还可以使用 appSettings 读取器（从 v2.0.42+ 版本开始）注册，如下所示。

本例展示了在应用程序设置读取器中使用时当前可用的选项。

  <appSettings>
    <add key="serilog:using" value="Serilog.Sinks.Elasticsearch"/>
    <add key="serilog:write-to:Elasticsearch.nodeUris" value="https://127.0.0.1:9200;http://remotehost:9200"/>
    <add key="serilog:write-to:Elasticsearch.indexFormat" value="custom-index-{0:yyyy.MM}"/>
    <add key="serilog:write-to:Elasticsearch.templateName" value="myCustomTemplate"/>
    <add key="serilog:write-to:Elasticsearch.typeName" value="myCustomLogEventType"/>
    <add key="serilog:write-to:Elasticsearch.pipelineName" value="myCustomPipelineName"/>
    <add key="serilog:write-to:Elasticsearch.batchPostingLimit" value="50"/>
    <add key="serilog:write-to:Elasticsearch.batchAction" value="Create"/>
    <add key="serilog:write-to:Elasticsearch.period" value="2"/>
    <add key="serilog:write-to:Elasticsearch.inlineFields" value="true"/>
    <add key="serilog:write-to:Elasticsearch.restrictedToMinimumLevel" value="Warning"/>
    <add key="serilog:write-to:Elasticsearch.bufferBaseFilename" value="C:\Temp\SerilogElasticBuffer"/>
    <add key="serilog:write-to:Elasticsearch.bufferFileSizeLimitBytes" value="5242880"/>
    <add key="serilog:write-to:Elasticsearch.bufferLogShippingInterval" value="5000"/>
    <add key="serilog:write-to:Elasticsearch.bufferRetainedInvalidPayloadsLimitBytes" value="5000"/>
    <add key="serilog:write-to:Elasticsearch.bufferFileCountLimit " value="31"/>
    <add key="serilog:write-to:Elasticsearch.connectionGlobalHeaders" value="Authorization=Bearer SOME-TOKEN;OtherHeader=OTHER-HEADER-VALUE" />
    <add key="serilog:write-to:Elasticsearch.connectionTimeout" value="5" />
    <add key="serilog:write-to:Elasticsearch.emitEventFailure" value="WriteToSelfLog" />
    <add key="serilog:write-to:Elasticsearch.queueSizeLimit" value="100000" />
    <add key="serilog:write-to:Elasticsearch.autoRegisterTemplate" value="true" />
    <add key="serilog:write-to:Elasticsearch.autoRegisterTemplateVersion" value="ESv7" />
    <add key="serilog:write-to:Elasticsearch.detectElasticsearchVersion" value="false" />
    <add key="serilog:write-to:Elasticsearch.overwriteTemplate" value="false" />
    <add key="serilog:write-to:Elasticsearch.registerTemplateFailure" value="IndexAnyway" />
    <add key="serilog:write-to:Elasticsearch.deadLetterIndexName" value="deadletter-{0:yyyy.MM}" />
    <add key="serilog:write-to:Elasticsearch.numberOfShards" value="20" />
    <add key="serilog:write-to:Elasticsearch.numberOfReplicas" value="10" />
    <add key="serilog:write-to:Elasticsearch.formatProvider" value="My.Namespace.MyFormatProvider, My.Assembly.Name" />
    <add key="serilog:write-to:Elasticsearch.connection" value="My.Namespace.MyConnection, My.Assembly.Name" />
    <add key="serilog:write-to:Elasticsearch.serializer" value="My.Namespace.MySerializer, My.Assembly.Name" />
    <add key="serilog:write-to:Elasticsearch.connectionPool" value="My.Namespace.MyConnectionPool, My.Assembly.Name" />
    <add key="serilog:write-to:Elasticsearch.customFormatter" value="My.Namespace.MyCustomFormatter, My.Assembly.Name" />
    <add key="serilog:write-to:Elasticsearch.customDurableFormatter" value="My.Namespace.MyCustomDurableFormatter, My.Assembly.Name" />
    <add key="serilog:write-to:Elasticsearch.failureSink" value="My.Namespace.MyFailureSink, My.Assembly.Name" />
  </appSettings>

使用appSettings配置需要nodeUris属性。可以使用,或;将节点隔开来指定多个节点。所有其他属性都是可选的。另外，还需要设置<add key="serilog:using" value="Serilog.Sinks.Elasticsearch"/>来包含该下沉设备。所有其他属性都是可选的。如果您没有显式指定索引格式设置，将自动使用通用索引，如'logstash-[当前日期]'。

然后使用Serilog开始编写事件。

Elasticsearch 格式化器

Install-Package serilog.formatting.elasticsearch

Serilog.Formatting.Elasticsearch NuGet 包包含几个格式化程序。

• ElasticsearchJsonFormatter - 尊重配置属性名处理的自定义 JSON 格式化程序，并将Timestamp强制转换为 @timestamp。
• ExceptionAsObjectJsonFormatter - 将任何异常序列化为异常对象的 JSON 格式化程序。

如果可能，可以覆盖默认格式化程序以用作所选的下沉设备

var loggerConfig = new LoggerConfiguration()
  .WriteTo.Console(new ElasticsearchJsonFormatter());

更多信息

• 有关如何配置和使用此下沉设备的详细信息的基本信息。
• 可用的配置选项。
• 如何使用耐用性模式。
• 获取NuGet 包。
• 向问题跟踪报告问题。欢迎PR，但请针对dev分支进行
• 查看最近更改的概述，请参阅变更日志。

有关 Elasticsearch 中字段的说明

请注意，在Elasticsearch索引内部存在显式和隐式类型映射。作为字符串的值X将被作为字符串索引。在下一个日志消息中使用整数X将不起作用。ES将引发映射异常，但您的日志项目因执行批量操作而没有存储这一点并不明显。

因此，在定义和配置您的字段（及其类型）时请小心。很容易错过，您首次将{User}发送为简单的用户名（字符串），然后将其作为User对象发送。索引中创建的第一个映射将获胜。有关详细信息和建议的解决方案，请参阅问题#184。ES对索引中使用动态字段的数量也有限制。

有关 Kibana 的说明

为了避免在具有嵌套异常的异常中使用深度嵌套的JSON结构，默认情况下，已记录的异常及其内部异常以异常数组的格式在exceptions字段中记录。使用'Depth'字段遍历内部异常流程。

但是，并非Kibana中的所有功能都适用于JSON数组 - 例如，在仪表板和可视化中包含异常字段。因此，我们提供了一个替代格式化程序，即ExceptionAsObjectJsonFormatter，它将异常序列化到具有嵌套InnerException属性的exception字段中作为对象。这是下沉设备版本2之前的默认行为。

使用它时，只需在创建下沉设备时指定它作为CustomFormatter即可

    new ElasticsearchSink(new ElasticsearchSinkOptions(url)
    {
      CustomFormatter = new ExceptionAsObjectJsonFormatter(renderMessage:true)
    });

appsettings.json JSON 配置

要在例如ASP.NET Core或.NET Core中使用Microsoft.Extensions.Configuration与Elasticsearch下沉设备，请使用Serilog.Settings.Configuration包。首先，如果您还没有这样做，请安装该软件包

Install-Package Serilog.Settings.Configuration

改为直接在代码中配置下沉设备，请调用ReadFrom.Configuration()

var configuration = new ConfigurationBuilder()
    .SetBasePath(env.ContentRootPath)
    .AddJsonFile("appsettings.json")
    .Build();

var logger = new LoggerConfiguration()
    .ReadFrom.Configuration(configuration)
    .CreateLogger();

在你的 appsettings.json 文件中，在 Serilog 节点下，

{
  "Serilog": {
    "WriteTo": [{
        "Name": "Elasticsearch",
        "Args": {
          "nodeUris": "https://127.0.0.1:9200;http://remotehost:9200/",
          "indexFormat": "custom-index-{0:yyyy.MM}",
          "templateName": "myCustomTemplate",
          "typeName": "myCustomLogEventType",
          "pipelineName": "myCustomPipelineName",
          "batchPostingLimit": 50,
          "batchAction": "Create",
          "period": 2,
          "inlineFields": true,
          "restrictedToMinimumLevel": "Warning",
          "bufferBaseFilename":  "C:/Temp/docker-elk-serilog-web-buffer",
          "bufferFileSizeLimitBytes": 5242880,
          "bufferLogShippingInterval": 5000,
          "bufferRetainedInvalidPayloadsLimitBytes": 5000,
          "bufferFileCountLimit": 31,
          "connectionGlobalHeaders" :"Authorization=Bearer SOME-TOKEN;OtherHeader=OTHER-HEADER-VALUE",
          "connectionTimeout": 5,
          "emitEventFailure": "WriteToSelfLog",
          "queueSizeLimit": "100000",
          "autoRegisterTemplate": true,
          "autoRegisterTemplateVersion": "ESv2",
          "overwriteTemplate": false,
          "registerTemplateFailure": "IndexAnyway",
          "deadLetterIndexName": "deadletter-{0:yyyy.MM}",
          "numberOfShards": 20,
          "numberOfReplicas": 10,
          "templateCustomSettings": [{ "index.mapping.total_fields.limit": "10000000" } ],
          "formatProvider": "My.Namespace.MyFormatProvider, My.Assembly.Name",
          "connection": "My.Namespace.MyConnection, My.Assembly.Name",
          "serializer": "My.Namespace.MySerializer, My.Assembly.Name",
          "connectionPool": "My.Namespace.MyConnectionPool, My.Assembly.Name",
          "customFormatter": "My.Namespace.MyCustomFormatter, My.Assembly.Name",
          "customDurableFormatter": "My.Namespace.MyCustomDurableFormatter, My.Assembly.Name",
          "failureSink": "My.Namespace.MyFailureSink, My.Assembly.Name"
        }
    }]
  }
}

请参考上述 XML <appSettings> 示例，讨论可用的 Args 选项。

错误处理

从版本 5.5 开始，您可以选择如何处理与 Elasticsearch 相关的问题。由于接收器是分批处理的，可能实际上无法将一个或多个事件存储在 Elasticsearch 存储中。例如，可能是一个映射问题。很难找出这里发生了什么。有一个新的选项叫做 EmitEventFailure，它是一个枚举（标记）并有以下选项

• WriteToSelfLog，默认选项，将错误写入 SelfLog。
• WriteToFailureSink，失败的日志事件将被发送到另一个接收器。确保通过设置 FailureSink 选项来配置此接收器。
• ThrowException，将引发异常。
• RaiseCallback，当事件无法提交到 Elasticsearch 时，会调用失败回调函数。确保设置 FailureCallback 选项来处理事件。

示例

.WriteTo.Elasticsearch(new ElasticsearchSinkOptions(new Uri("https://127.0.0.1:9200"))
                {
                    FailureCallback = e => Console.WriteLine("Unable to submit event " + e.MessageTemplate),
                    EmitEventFailure = EmitEventFailureHandling.WriteToSelfLog |
                                       EmitEventFailureHandling.WriteToFailureSink |
                                       EmitEventFailureHandling.RaiseCallback,
                    FailureSink = new FileSink("./failures.txt", new JsonFormatter(), null)
                })

使用 AutoRegisterTemplate 选项时，接收器会将默认模板写入 Elasticsearch。当此模板不存在时，可能不需要索引，因为它可能影响数据质量。从版本 5.5 开始，您可以使用 RegisterTemplateFailure 选项。将其设置为以下选项之一

• IndexAnyway；默认选项，将事件发送到服务器
• IndexToDeadletterIndex；使用 deadletterindex 格式，将事件写入死信队列。当您修复模板映射后，可以将数据复制到正确的索引。
• FailSink；这将简单地通过引发异常来使接收器失败。

从版本 7 开始，如果指定了持久文件，您可以指定因为数据（有效负载）而由 Elasticsearch 拒绝的日志行的操作。

BufferCleanPayload = (failingEvent, statuscode, exception) =>
                    {
                        dynamic e = JObject.Parse(failingEvent);
                        return JsonConvert.SerializeObject(new Dictionary<string, object>()
                        {
                            { "@timestamp",e["@timestamp"]},
                            { "level","Error"},
                            { "message","Error: "+e.message},
                            { "messageTemplate",e.messageTemplate},
                            { "failingStatusCode", statuscode},
                            { "failingException", exception}
                        });
                    },

当指定持久文件时，IndexDecider 未能很好地工作，因此增加了指定 BufferIndexDecider 的选项。日志事件的类型为字符串，即

 BufferIndexDecider = (logEvent, offset) => "log-serilog-" + (new Random().Next(0, 2)),

Option BufferFileCountLimit 添加。将保留的最大日志文件数，包括当前日志文件。如果要保留无限数量，请传递 null。默认值为 31。Option BufferFileSizeLimitBytes 添加。允许特定日期的缓冲日志文件增长的最大大小（以字节为单位）。默认应用 100L * 1024 * 1024。

重大变更

版本 9

• 已取消对 456 的支持，现在正在坚持使用 NETSTANDARD。
• 已取消对 Opensearch 的支持 - 此软件包（无保证）支持写入最后一个版本中的 Opensearch，更新的 ES 软件包已取消对 Opensearch 的支持。

版本 7

• Nuget Serilog.Sinks.File 现在使用而非已弃用的 Serilog.Sinks.RollingFile。
• SingleEventSizePostingLimit 选项从 int 更改为 long？具有默认值 null，不要使用值 0，否则将不会记录任何内容！

版本 6

从版本 6 开始，接收器已升级以与 Elasticsearch 6.0 一起使用，并支持 ES 6 的新模板。

如果您使用 AutoRegisterTemplate 选项，则需要将 AutoRegisterTemplateVersion 选项设置为 ESv6，以生成与 ES 6 破坏性更改兼容的默认模板。

版本 4

从版本 4 开始，接收器已升级以与 Serilog 2.0 一起使用，并支持 .NET Core。

版本 3

从版本 3 开始，接收器支持 Elasticsearch.Net 2 软件包和 Elasticsearch 版本 2。如果您需要 Elasticsearch 1.x 支持，则继续使用接收器的版本 2。该函数

protected virtual ElasticsearchResponse<T> EmitBatchChecked<T>(IEnumerable<LogEvent> events)

现在使用泛型类型。这允许您在使用 Elasticsearch.NET 时映射到 DynamicResponse，或者如果您想使用 NEST，则映射到 BulkResponse。

我们也取消了.NET 4的支持，因为Elasticsearch.NET客户端也不再支持这个框架版本了。如果您需要使用.NET 4，那么您需要坚持使用2.x版本的组件。

第2版

注意，第2版引入了一些破坏性更改。

• 重载已被缩减为单个Elasticsearch函数，您可以传递一个选项对象。
• 命名空间和函数名称现在在所有地方都使用Elasticsearch而不是ElasticSearch。
• Serilog记录的异常现在被序列化到Exceptions属性，该属性是一个数组而不是对象。
• 内部异常记录在同一个数组中，但具有增加的深度参数。因此，您不需要嵌套对象，而是需要查看此参数以找到异常的深度。
• 请不要再使用Gist中提供的一次性映射。组件可以自动为您创建正确的映射，但此功能默认禁用。我们建议您使用它。
• 从2.0.42版本开始，使用AppSettings读取器注册此组件的功能已恢复。您可以传入一个节点（或节点集合），以及可选的索引名称和模板。