Serilog.Sinks.Http.LogzIo 3.0.0

通过 HTTP 向 logz.io 发送日志事件的 Serilog 溢出

可用的软件包

Serilog.Sinks.Logz.Io

软件包 - Serilog.Sinks.Logz.Io | 平台 - NET7.0, NET 6.0, .NET Standard 2.0, .NET 4.6.1

警告：破坏性更改

v7 有破坏性更改。

• 默认字段名称格式化设置可能会根据您的配置而更改，请务必核实
• 将 batchPostingLimit 字段重命名为 logEventsInBatchLimit 以与 Serilog.Sinks.Http 库匹配
• 将 bufferPathFormat 重命名为 bufferBaseFileName
• 此外，滚动时间间隔现在设置为单独的属性：bufferRollingInterval

因此现在需要进行以下更改：

    "bufferPathFormat": "Buffer-{Hour}.json",

需要将配置文件更改如下：

    "bufferBaseFileName": "Buffer",
    "bufferRollingInterval": "Hour",

• 数据中心配置已移动到单独的对象

因此现在需要进行以下更改：

    "useHttps": true,
    "dataCenterSubDomain": "listener",
    "port": null

需要将配置文件更改如下：

    "dataCenter": {
        "useHttps": true,
        "dataCenterSubDomain": "listener",
        "port": null
    }

有关更多信息，请参阅：https://github.com/FantasticFiasco/serilog-sinks-http/releases/tag/v8.0.0

安装

如果您想在项目中包含 HTTP 终端，您可以直接从 NuGet 安装它。

要安装终端，请在包管理控制台运行以下命令

PM> Install-Package Serilog.Sinks.Logz.Io

Serilog.Sinks.Http.LogzIo

该包已废弃，因为它已经是过时的并且不再维护。请更新到 Serilog.Sinks.Logz.Io. 最新版本包含完全相同的功能和配置日志记录器的扩展方法。

用法

在以下示例中，终端将通过 HTTP 将日志事件 POST 到 https://listener-eu.logz.io:8071/?type=app&token=<token>。我们通过使用 命名参数 而不是位置参数来配置终端，因为历史上我们看到大多数破坏性变化都是由于描述新功能的参数引起的。使用命名参数意味着您通常可以迁移到新的大版本而不需要更改代码。

与 Serilog.Settings.Configuration 结合使用时，可以通过以下方式配置相同的终端

{
  "Serilog": {
    "MinimumLevel": "Warning",
    "WriteTo": [
      {
        "Name": "LogzIoDurableHttp",
        "Args": {
          "requestUri": "https://listener-eu.logz.io:8071/?type=app&token=<token>"
        }
      }
    ]
  }
}

终端将配置为鲁棒性，即在下发到网络之前将日志事件持久化到磁盘，从而在系统或进程重启后防范数据丢失。更多信息请参阅 wiki。

内部

库依赖于一个出色的 Serilog.Sinks.Http 包，该包允许创建缓冲文件并控制 HTTP 上传。

在这里，我们使用 DurableHttpUsingTimeRolledBuffers 扩展方法来配置鲁棒的 HTTP 终端。

请参阅: DurableHttpUsingTimeRolledBuffers

Wiki: 鲁棒的按时间滚动的 HTTP 终端

序列化器

库正在使用 Newtonsoft.Json 包进行序列化。但是可以使用 LogzIoSerializer.Instance 属性更改/配置序列化行为。此实例应在应用程序启动时配置（最佳做法是在 Serilog 配置之前发生）。

默认行为是自动设置的

LogzIoSerializer.Instance = new LogzIoSerializer(LogzIoTextFormatterFieldNaming.CamelCase, false);

您也可以使用以下代码设置自定义 JsonSerializerSettings

LogzIoSerializer.Instance.WithSerializerSettings(customSetttings);

当然，您可以通过实现 ILogzIoSerializer 接口并配置自己的实现来完全覆盖序列化逻辑。

多播委托

用于序列化日志条目的 Newtonsoft.Json 包也能够序列化 lambda 表达式、委托和类似的功能结构，这在日志中通常没有意义。它还可能会生成包含程序集信息的巨大数据块，从而增加日志条目的大小到不可接受的程度。

为了处理这个问题，使用自定义 JsonConverter 覆盖了 MulticastDelegate 类型序列化。

如果您仍然想要启用这种行为 - 在应用程序启动时您可以使用以下代码配置包序列化器

LogzIoSerializer.Instance = new LogzIoSerializer(LogzIoTextFormatterFieldNaming.CamelCase, false);

更复杂的示例

注意：以下示例中只需要 requestUri。所有其他属性代表默认值。

{
  "Serilog": {
    "MinimumLevel": {
      "Default": "Debug",
      "Override": {
        "Microsoft.AspNetCore": "Debug"
      }
    },
    "Enrich": [ "FromLogContext", "WithMachineName", "WithThreadId" ],
    "WriteTo": [
      {
        "Name": "LogzIoDurableHttp",
        "Args": {
          "requestUri": "https://listener-eu.logz.io:8071/?type=app&token=<token>",
          "bufferBaseFileName": "Buffer",
          "bufferRollingInterval": "Day",
          "bufferFileSizeLimitBytes": "104857600",
          "bufferFileShared": false,
          "retainedBufferFileCountLimit": 31,
          "logEventsInBatchLimit": 1000,
          "period": null,
          "restrictedToMinimumLevel": "Minimum",
          "logzioTextFormatterOptions": {
            "BoostProperties": true,
            "LowercaseLevel": true,
            "IncludeMessageTemplate": true,
            "FieldNaming": "CamelCase",
            "EventSizeLimitBytes": 261120
          }
        }
      }
    ]
  }
}

在上面的示例中，logzIo 格式化选项是默认的，如果您需要这些就不需要指定。

• BoostProperties: 当为 true 时，不添加 'properties' 前缀。
• LowercaseLevel：将设置为 true 以将日志级别推送到小写。
• IncludeMessageTemplate：当为 true 时，消息模板包含在日志中。
• FieldNaming：允许转换字段名称，可能的值：null（默认），CamelCase，LowerCase

代码配置

    configuration
        .WriteTo.LogzIoDurableHttp(
            "https://listener-eu.logz.io:8071/?type=app&token=<token>",
            logzioTextFormatterOptions: new LogzioTextFormatterOptions
            {
                BoostProperties = true,
                LowercaseLevel = true,
                IncludeMessageTemplate = true,
                FieldNaming = LogzIoTextFormatterFieldNaming.CamelCase,
                EventSizeLimitBytes = 261120,
            })
        .MinimumLevel.Verbose();

无缓冲文件的日志

注意：强烈推荐使用耐用的日志记录器。它具有更高的鲁棒性和对各种网络问题的容忍性，因此您的日志不会丢失。

以下示例中， sink 将通过 HTTPS 将日志事件 POST 到 https://listener.logz.io。

ILogger log = new LoggerConfiguration()
  .MinimumLevel.Verbose()
  .WriteTo.LogzIo("<logzio token>", "<log type>", useHttps: true)
  .CreateLogger();

log.Information("Logging {@Heartbeat} from {Computer}", heartbeat, computer);

还提供了更高级的配置

ILogger log = new LoggerConfiguration()
  .MinimumLevel.Verbose()
  .WriteTo.LogzIo("<logzio token>", "<log type>",
    new LogzioOptions 
    { 
        RestrictedToMinimumLevel = LogEventLevel.Debug,
        Period = TimeSpan.FromSeconds(15),
        LogEventsInBatchLimit = 50
    })
  .CreateLogger();

或者，您可以在您的 appsettings.json 文件内完成配置

{
  "Serilog": {
    "MinimumLevel": {
      "Default": "Verbose"
    },
    "WriteTo": [
      {
        "Name": "LogzIo",
        "Args": {
          "authToken": "<logzio token>",
          "type": "<log type>",
          "dataCenterSubDomain": "listener",
          "dataCenter": {
              "subDomain": "listener",
              "useHttps": true
          },
          "logEventsInBatchLimit": 5000,
          "period": "00:00:02",
          "restrictedToMinimumLevel": "Debug",
          "lowercaseLevel": false,
          "environment": "",
          "serviceName": ""
        }
      }
    ]
  }
}

支持 Elastic Common Schema

更多详细信息请参阅：https://elastic.ac.cn/guide/en/ecs/current/ecs-reference.html

ILogger log = new LoggerConfiguration()
  .MinimumLevel.Verbose()
  .WriteTo.LogzIo(new LogzioEcsOptions
        {
            Type = "<log type>",
            AuthToken = "<logzio token>",
            DataCenter = new LogzioDataCenter
            {
                SubDomain = "listener",
                Port = 8701,
                UseHttps = true
            }
        },
        batchPostingLimit: 50,
        period: TimeSpan.FromSeconds(15),
        restrictedToMinimumLevel: LogEventLevel.Debug
    )
  .CreateLogger();

或者，您可以在您的 appsettings.json 文件内完成配置，请注意 CustomEcsTextFormatterConfiguration 的设置是可选的

{
  "Serilog": {
    "Using": [
      "Serilog.Sinks.Console",
      "Serilog.Sinks.Logz.Io"
    ],
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft": "Information",
        "System": "Warning"
      }
    },
    "WriteTo": [
      { "Name": "Console" },
      {
        "Name": "LogzIoEcs",
        "Args": {
          "options": {
            "type": "<log type>",
            "authToken": "<logzio token>"
          },
          "logEventsInBatchLimit": 30,
          "period": "00:00:02",
          "restrictedToMinimumLevel": "Debug",
          "formatterConfiguration": "Serilog.Sinks.Logz.Io.AspNetCoreApi.Logging.CustomEcsTextFormatterConfiguration, Serilog.Sinks.Logz.Io.AspNetCoreApi"
        }
      }
    ]
  }
}