› ›

Elastic.Serilog.Sinks

一个 Serilog sink，将日志直接写入 Elasticsearch 或 Elastic Cloud

安装

添加对 Elastic.Serilog.Sinks 包的引用

<PackageReference Include="Elastic.Serilog.Sinks" Version="8.6.0" />

用法

编辑

有几种方法可以扩展 Serilog LoggerConfiguration

Log.Logger = new LoggerConfiguration()
	.MinimumLevel.Debug()
	.Enrich.FromLogContext()

注意： 不要忘记我们还发布了一个 Elastic.Apm.SerilogEnricher 用于 Elastic APM Agent！

写入 Elasticsearch

.WriteTo.Elasticsearch(new [] { new Uri("https://127.0.0.1:9200" )}, opts =>
{
	opts.DataStream = new DataStreamName("logs", "console-example", "demo");
	opts.BootstrapMethod = BootstrapMethod.Failure;
	opts.ConfigureChannel = channelOpts =>
	{
		channelOpts.BufferOptions = new BufferOptions
		{
			ConcurrentConsumers = 10
		};
	};
}, transport =>
{
	// transport.Authentication(new BasicAuthentication(username, password)); // Basic Auth
	// transport.Authentication(new ApiKey(base64EncodedApiKey)); // ApiKey
})

写入 Elastic Cloud

.WriteTo.ElasticCloud("cloudId", "cloudUser", "cloudPass", opts =>

opts 是 ElasticsearchSinkOptions 的实例，具有以下选项

配置

编辑

选项	描述
`传输`	`Elastic.Transport` 的实例，指示我们与谁以及如何通信。默认为 `https://127.0.0.1:9200`
`数据流`	数据写入的位置，默认为 `logs-dotnet-default` 数据流。
`引导方法`	sink 是否应尝试安装组件和索引模板，以确保数据流具有 ECS 映射。可以是 `None`（默认）、`Silent`（尝试但静默失败）、`Failure`（尝试，如果引导失败则引发异常）。
`文本格式化`	允许显式控制用于发出 ECS json 文档的 `EcsTextFormatterConfiguration`。有关可用选项，请参阅 `Elastic.CommonSchema.Serilog`。
`配置通道`	接收 `DatastreamChannelOptions` 的回调，允许您控制大小、背压等。有关详细信息，请参阅 `Elastic.Ingest.Elasticsearch`。

请注意，您也可以直接传递 ElasticsearchSinkOptions

.WriteTo.Elasticsearch(new ElasticsearchSinkOptions(client.Transport))

这允许您重用 Elasticsearch 客户端使用的 Transport，例如。

身份验证

编辑

启用 Elasticsearch 安全功能后，没有有效身份验证头的请求将被拒绝。您可以通过以下方法之一启用身份验证

基本身份验证

.WriteTo.Elasticsearch(new [] { new Uri("https://127.0.0.1:9200" )}, opts =>
{
	...
}, transport =>
{
	transport.Authentication(new BasicAuthentication(username, password)); 
})

基本身份验证

API 密钥

.WriteTo.Elasticsearch(new [] { new Uri("https://127.0.0.1:9200" )}, opts =>
{
	...
}, transport =>
{
	transport.Authentication(new ApiKey(base64EncodedApiKey)); 
})

API 密钥

要了解有关 Elastic Stack 身份验证的更多信息，请参阅用户身份验证。

ECS 感知消息模板

编辑

此 sink 通过其格式化程序允许您使用符合 https://messagetemplates.org/ 格式的属性直接从消息模板设置 ECS 字段。

可用的 ECS 消息模板属性列在 LogTemplateProperties.* 下，例如 LogTemplateProperties.TraceId

Log.Information("The time is {TraceId}", "my-trace-id");

将覆盖生成的 ECS json 文档上的 trace.id。

问题排查

编辑

如果出现问题，您可以启用 [Serilog 自我日志功能](https://github.com/serilog/serilog/wiki/Debugging-and-Diagnostics#selflog) 以公开您可能遇到的任何错误。

与 `Serilog.Sinks.Elasticsearch` 的比较

编辑

Serilog.Sinks.Elasticsearch 是一个很棒的社区主导的 sink，它具有大量选项，并且适用于较旧的 Elasticsearch 版本 < 8.0。
Serilog.Sinks.Elasticsearch 得到了 Elastic 的非官方支持，其中一些 .NET 团队成员帮助维护它。
Elastic.Serilog.Sinks 得到 Elastic 的官方支持，并且专门构建为遵守围绕日志记录、数据流和 ILM 的最新最佳实践。
Elastic.Serilog.Sinks 专门构建为具有比 Serilog.Sinks.Elasticsearch 更少的配置选项，并且更具指导性。
但这并不是说 Elastic.Serilog.Sinks 中没有大量的配置钩子

值得注意的缺失功能

编辑

Elastic.Serilog.Sinks 仅适用于 Elasticsearch 8.x 及更高版本。
这是因为引导 (BootstrapMethod) 尝试加载为 Elasticsearch 8.0 及更高版本构建的模板。
Elastic.Serilog.Sinks 仅有一种方式将数据发送到 Elasticsearch，符合 ecs-logging 规范
但这并不意味着您不能引入自己的其他属性。
Elastic.Serilog.Sinks 没有持久模式。
如果您需要更高的日志传递保证，请使用 Serilog.Sinks.File 以及我们用于 Serilog 的 ECS 日志格式化程序，并使用 filebeat 来传输这些日志。
请查看 Elastic Agent 和 Fleet，以简化在边缘收集日志和指标。

如果您在 Elastic.Serilog.Sinks 中缺少 Serilog.Sinks.Elasticsearch 的特定功能，请打开一个功能请求！我们很乐意在未来有机地发展这个 sink。

« ECS 摄取通道 Elastic.Extensions.Logging »

Elastic.Serilog.Sinks